DEV Community: Muhammad Moeed

Claude Code slow or worse? How to diagnose and fix it in 2026

Muhammad Moeed — Sat, 23 May 2026 19:05:07 +0000

If Claude Code has felt slower or less capable this spring, you were not imagining it. Anthropic confirmed in an official post mortem on April 23, 2026 that three product changes stacked between March and April caused real, measurable quality drops. All three were reverted by April 20.

This is the short version. The full guide is on my blog: Claude Code Slow or Worse? How to Diagnose and Fix It (2026).

What actually happened

Change	Landed	Reverted
Reasoning effort dropped from high to medium	March 4	April 7
Cache eviction bug fired every turn	March 26	April 10 (fixed)
System prompt "25 words between tool calls"	April 16	April 20

All resolved in v2.1.116. Anthropic reset usage limits as an apology.

Three quick checks

1. Are you on the fixed build?

claude --version

Update if you are below v2.1.116. Fast mode now defaults to Opus 4.7 as of v2.1.142 (May 14).

2. Run `/doctor`

It catches about 80 percent of "Claude is broken" cases. Stale install, wrong API key, broken MCP server, outdated CLAUDE.md, silently failing hook. Fix anything yellow or red before blaming the model.

3. Check status

status.claude.com

If it is red, stop and come back later.

Six fixes for the rest

Start fresh sooner. Long sessions lose attention to context bloat. Run /compact every 30 to 45 minutes or restart.
Write a real CLAUDE.md. Project context that belongs in every session. Keep it under two pages.
Use /fast only when speed matters. Same intelligence as standard Opus 4.7, six times the cost.
Put quality constraints at the end of your prompt. Attention weight is higher there.
Shrink your MCP surface. Every connected server eats tokens before you type.
Full restart. Kill Claude Code, wait 10 to 15 minutes, start again.

The diagnostic tree

version >= 2.1.116?      no → update
/doctor clean?           no → fix it
status.claude.com clean? no → wait
session > 45 minutes?    yes → /compact or restart
> 3 MCP servers?         yes → disconnect what you do not use
still bad?               → restart, then file a GitHub issue

Most people stop at one of the middle steps.

The full guide covers what each platform change did, the cost trade off of fast mode, when to file a GitHub issue, and a longer FAQ: Claude Code Slow or Worse? How to Diagnose and Fix It (2026).

Claude Agent SDK vs Vercel AI SDK 6 — which to pick in 2026

Muhammad Moeed — Sat, 23 May 2026 19:02:11 +0000

Two libraries land on most shortlists when you start an agent project in 2026: Anthropic's Claude Agent SDK and Vercel AI SDK 6. Both build agents that use tools, stream, and speak MCP. They were built by teams with different beliefs.

This is the short version. The full guide is on my blog: Claude Agent SDK vs Vercel AI SDK 6: Which to Pick (2026).

The short version

Pick the Claude Agent SDK when your model is Claude and you want the same runtime that powers Claude Code, with caching, compaction, and built in tools on day one. Python and TypeScript.

Pick the Vercel AI SDK 6 when you need multi provider support, your stack is TypeScript and React or Next.js, or you want chat, tools, images, reranking, and speech in one library.

Side by side at a glance

Area	Claude Agent SDK	Vercel AI SDK 6
Languages	Python, TypeScript	TypeScript only
Models	Claude only	Any provider through AI Gateway
Agent API	`query()` with `ClaudeAgentOptions`	`ToolLoopAgent` class
Built in tools	Read, Write, Edit, Bash, Glob, Grep, WebSearch	None by default, you define them
Subagents	First class, own context window	Not built in
MCP support	First class	First class as of v6, OAuth supported
Prompt caching	On by default	Provider dependent, opt in
Context compaction	Automatic	Manual
DevTools UI	None	Local UI at `localhost:4983`
Frameworks	Any	Next.js, React, Svelte, Vue, Node.js

The Anthropic SDK is opinionated and Claude shaped. The Vercel SDK is flexible and provider neutral.

Same agent in both

Claude Agent SDK

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "What changed in HTTP/3 in 2025?",
  options: {
    allowedTools: ["WebSearch", "WebFetch"],
    systemPrompt: "You are a research assistant. Always cite sources.",
  },
})) {
  if ("result" in message) console.log(message.result);
}

WebSearch and WebFetch are built in.

Vercel AI SDK 6

import { ToolLoopAgent, tool } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

const webSearch = tool({
  description: "Search the web. Returns the top three results.",
  inputSchema: z.object({ query: z.string() }),
  execute: async ({ query }) => results,
});

const agent = new ToolLoopAgent({
  model: anthropic("claude-opus-4-7"),
  instructions: "You are a research assistant. Always cite sources.",
  tools: { webSearch },
});

const result = await agent.generate({
  prompt: "What changed in HTTP/3 in 2025?"
});

You bring your own search function. Swap anthropic(...) for openai(...) and the rest of the file is unchanged.

Where each wins

The Claude Agent SDK wins on built in tools, subagents with their own context window, hooks that mirror Claude Code, and defaults that match production. Prompt caching is on, compaction is automatic, retries are sensible.

The Vercel AI SDK 6 wins on provider flexibility, the DevTools UI at localhost:4983, one line human in the loop with needsApproval, and having image, audio, and reranking in the same library.

A simple way to choose

Are you locked to Claude models?
  Yes → Claude Agent SDK
  No  → TypeScript and React stack?
          Yes → Vercel AI SDK 6
          No  → Claude Agent SDK Python build

For LangChain comparisons, the Claude Agent SDK vs LangChain post has the answer.

The full guide covers MCP wiring on both sides, defaults and cost, the June 15 2026 Agent SDK billing change, and a longer FAQ: Claude Agent SDK vs Vercel AI SDK 6: Which to Pick (2026).

AWS Copilot CLI is reaching end of support — your migration options

Muhammad Moeed — Wed, 20 May 2026 13:32:59 +0000

If you have been using AWS Copilot CLI to deploy containers on ECS, the tool has a date on it. AWS Copilot CLI reaches end of support on June 12, 2026. After that, the open-source project stays on GitHub, but AWS will not ship features, fixes, or security patches for it.

This is the short version. The full walkthrough is on my blog: AWS Copilot CLI End of Support: Migration Guide for 2026.

What changes on June 12, 2026

Your running apps do not. The ECS services, load balancers, and CloudFormation stacks Copilot created stay in your account.

What changes is the tool:

No new features.
No security updates from AWS.
No technical support.
The GitHub repo stays open, but it is no longer AWS-maintained.

What AWS recommends instead

Two paths, for two kinds of teams.

Amazon ECS Express Mode. The fastest path from a container image to production. You hand it an image and two IAM roles, and it builds the load balancer, listener, target groups, security groups, scaling, and monitoring. Fargate-only. Closest in spirit to Copilot. Pick this if your service is a standard load-balanced or request-driven web app.

AWS CDK Layer 3 constructs. The aws-ecs-patterns library has constructs like ApplicationLoadBalancedFargateService, QueueProcessingFargateService, and ScheduledFargateTask that cover most patterns Copilot supported. Pick this if you need fine-grained control, blue/green, a service mesh, or non-Fargate launch types.

You can also take over the CloudFormation Copilot generated and manage it directly. Low effort short-term, but those templates are not built to be human-edited. Treat it as a bridge.

Service-by-service map

Copilot service type	Replacement
Load Balanced Web Service	ECS Express Mode, or CDK `ApplicationLoadBalancedFargateService`
Request-Driven Web Service	ECS Express Mode with request-based scaling
Backend Service	CDK internal ALB, or ECS Service Connect
Worker Service	CDK `QueueProcessingFargateService`
Scheduled Job	EventBridge Scheduler + ECS `RunTask`, or CDK `ScheduledFargateTask`
Static Site	CDK CloudFront constructs, or AWS Amplify Hosting

Most teams find that web services land on Express Mode and workers/scheduled jobs land on CDK.

How to plan the move

One service at a time, not one big switch:

Inventory every service. copilot svc ls gives the list; the copilot/ manifests give the type.
Match each to its replacement.
Pick a low-traffic service for the first migration. The point is to learn the workflow, not to ship the hardest case.
Run both versions in parallel for a few days, watch metrics, cut over.
Delete the Copilot service to remove its stack cleanly.
Repeat. Hardest cases last.

If you only do one thing before June 12, do step one.

The full guide covers the IAM-role split for Express Mode, when CDK is actually worth it, the third path of taking over the CloudFormation directly, and what happens if you cannot migrate in time: AWS Copilot CLI End of Support: Migration Guide for 2026.

Claude Code /goal and Agent View, explained

Muhammad Moeed — Tue, 19 May 2026 11:39:31 +0000

The May 2026 Claude Code update added two features for running it without watching every step: the /goal command and Agent View. They are separate, but built for the same workflow, so here they are together. Everything below is from the official docs. The full version is on my blog: Claude Code /goal and Agent View: A Practical Guide.

What /goal does

You write one completion condition. After each turn, instead of stopping, Claude Code asks a separate model whether the condition is true. No, it takes another turn, using the reason as guidance. Yes, the goal clears and you get your terminal back. Requires v2.1.139 or later.

You set one by running /goal followed by the condition, for example: /goal all tests in test/auth pass and the lint step is clean.

Running /goal with no argument shows status. /goal clear stops it early. It also runs non-interactively with claude -p "/goal CHANGELOG.md has an entry for every PR merged this week".

The detail most posts skip

The evaluator is a small fast model (Haiku by default). It does not run commands or open files. It only judges the text already in the session. So the condition has to be something Claude can prove by what it prints. "All tests in test/auth pass" works because the test output lands in the transcript. "The code is good" never will.

A condition that holds up has one measurable end state, a stated check (how Claude proves it), and the constraints that must not change. It can be up to 4,000 characters. Add a clause like "or stop after 20 turns" so it does not run forever. That one clause is the difference between a task that ends and a task that quietly keeps spending tokens.

How it compares

/goal: next turn after the previous finishes; stops when a model confirms the condition.
/loop: next turn on a time interval.
Stop hook: your own script decides. (/goal is actually a thin wrapper over a session-scoped Stop hook.)
Auto mode: removes per-tool approvals inside a turn. Complementary: auto mode plus /goal means turns run unattended and keep coming until done.

Agent View

Once a session runs on its own, you want several. Agent View is one CLI screen listing your sessions: status, last response, when you last touched it. Open it with the left arrow from any session, or by running claude agents. Statuses are Running, Blocked (needs you), and Done. Peek at a session, answer inline if it is blocked, press Enter to attach fully.

Background sessions connect the two: /bg sends the current session to the background, and claude --bg [task] starts one already detached. Start a few goals with turn limits, background them, watch the fleet in Agent View, and step in only on Blocked or Done.

Agent View is a research preview on Pro, Max, Team, Enterprise, and Claude API plans.

The full guide covers writing conditions in depth, the requirements and limits, when not to use it, and how it differs from Outcomes and plan mode: Claude Code /goal and Agent View: A Practical Guide.

What is AWS ECS Express Mode (and when to use it)

Muhammad Moeed — Tue, 19 May 2026 11:33:31 +0000

If you have ever deployed a normal web service on ECS, the slow part was never the container. It was everything around it: a load balancer, listener rules, target groups, two security groups, a task definition, the service, auto scaling, alarms, and the networking that ties it together. ECS Express Mode is Amazon's answer to that. You give it a container image, and it builds the rest.

This is the short version. The full walkthrough is on my blog: What is AWS ECS Express Mode.

What you give it

Three inputs, that is the whole list:

A container image — your actual app, the kind of image you would push to ECR.
A task execution IAM role — the role ECS uses to start the container, pull the image, and write logs.
An infrastructure IAM role — the new one. The permission Express Mode uses to create the load balancer and the rest on your behalf.

The two roles are kept separate on purpose. One runs your app, the other provisions infrastructure. You do not want your running container holding permission to create load balancers.

What it builds

From those three inputs it provisions an Application Load Balancer, an HTTPS endpoint on an AWS-provided domain, auto scaling, health checks, security groups, and monitoring set up with AWS's recommended defaults. Every resource stays fully visible and editable in your own account.

It runs on Fargate only, not the EC2 launch type. It also places up to 25 Express Mode services behind a single shared load balancer when their networking is compatible, so you are not paying for a load balancer per tiny service.

What it costs

The feature has no extra charge and is in all regions. You pay only for the AWS resources it creates to run the app. You save the setup time, not the running cost.

When not to use it

Express Mode trades configurability for speed. Skip it when you need:

Blue/green deployments — not supported.
A service mesh or detailed networking control — not available.
The EC2 launch type — Fargate only.
A dedicated load balancer with custom listener logic.

Because every resource stays in your account, you are not locked in. Start on Express Mode, and when a service grows into one of those cases, migrate it to a standard ECS service rather than rebuilding from scratch.

The full version explains the IAM roles, the shared load balancer model, the comparison table against a standard ECS service, and a full FAQ: What is AWS ECS Express Mode (and when to use it).

How Anthropic's own teams use Claude Code

Muhammad Moeed — Tue, 19 May 2026 11:11:04 +0000

Anthropic published a report on how its own staff use Claude Code. It comes from interviews with internal power users across ten teams, including non-technical ones like legal and marketing. A lot of people have been looking for the PDF, so here is the short version plus the parts that matter even if you are one person and not a company with a large monorepo.

The source is How Anthropic teams use Claude Code (PDF). This is my reading of it, not a copy.

The report in one paragraph

Ten teams, some technical and some not. The recurring lessons are simple and consistent: write a detailed CLAUDE.md, commit checkpoints often so you can revert, treat Claude Code as a partner you iterate with rather than a one-shot machine, paste screenshots instead of describing things, and learn which tasks can run on their own versus which need you watching. The biggest jumps came from people who do not write code for a living.

A few of the stories

Data Infrastructure debugged a Kubernetes outage by pasting dashboard screenshots in and letting Claude Code walk them through the console until they found pod IP exhaustion. They also taught the finance team to run plain-text workflow files.
The Claude Code team builds Claude Code with it. Edge features run in auto-accept loops to about an eighty-percent solution; core logic is watched closely. Vim mode was roughly seventy percent autonomous.
Security Engineering pastes Terraform plans in and asks, in plain words, what it will do and whether they will regret it. They own about half the custom slash commands in the whole monorepo.
Data Science builds React and TypeScript dashboards without reading the code, and treats messy refactors "like a slot machine": commit, let it run thirty minutes, then accept or restart fresh.
Growth Marketing, a non-technical team of one, built ad-generation workflows with subagents and a Figma plugin, cutting two-hour copy tasks to fifteen minutes.
Legal built a predictive-text speaking app for a family member in about an hour.

The patterns worth keeping

These came up independently across teams doing very different work:

CLAUDE.md is the highest-leverage file you have. Three unrelated teams reached this on their own.
Commit checkpoints and be willing to throw work away. Restarting clean usually beats fixing a bad attempt.
It is a partner you iterate with, not a one-shot oracle. Give it the minimum, watch, steer.
Screenshots are an input, not a fallback.
Judge the task before you pick the mode. Edge work can run alone; core logic needs you in the room.
Documentation is a first-class use, not a side effect.
Use MCP and subagents to keep things controlled and focused.

The honest parts

Most write-ups drop these. The RL team says a first attempt fully works only about a third of the time, and that it sometimes puts comments in odd places. Data Science says it tends toward complex solutions and has to be told to keep it simple. That is not a reason to avoid it. It is the reason the checkpoint-and-revert habit exists.

What a solo developer can copy today

Write a real CLAUDE.md, even a short one.
Start risky runs from a clean git state and commit as you go.
Automate the repetitive thing that sits behind an API first.
Plan in a normal chat, then move the structured prompt into Claude Code.
If a run goes sideways, revert and restart instead of wrestling it.

The full version on my blog goes team by team through all ten, with the specific numbers and tips for each: How Anthropic's own teams use Claude Code.

Claude Code vs Cursor — 90 days with both in 2026

Muhammad Moeed — Fri, 15 May 2026 00:43:39 +0000

If you have already tried one of them, you are probably wondering whether the other is worth a switch. The short version is that Claude Code and Cursor are not competing for the same job, even though they look like they are. One lives in your terminal and behaves like a junior engineer with shell access. The other lives inside an editor and behaves like a very fast pair programmer sitting next to you.

I ran both on real work for ninety days. Some of it was a Next.js client project, some of it was a Python data pipeline, and a fair amount was housekeeping in my own blog. The picture that came out of that is more nuanced than the comparison posts I had read going in.

TL;DR

Claude Code is better when the task is large and the work happens across many files. Cursor is better when the task is small and you need to stay in the file you are looking at. Most working developers end up using both.

What they actually are

	Claude Code	Cursor
Form	Terminal CLI (plus IDE extension)	Forked VS Code editor
Default working mode	Agentic — reads, plans, edits, runs cmds	Inline completion + chat + agent
Pricing	Pro $20 / Max $200 per month	Pro $20 / Ultra $200, free tier
Best for	Multi-file refactors, repo-wide work, CI	Single-file edits, fast iteration

Cursor is an editor. Claude Code is an agent. That one sentence explains most of the differences below.

Where Cursor wins

I want to be honest here because the internet has decided Claude Code is the winner and Cursor is yesterday's news. That is not what I saw.

Inline tab completion is still the best in the category. For small edits where you already know what you want, this beats any agent loop on raw speed.
Diff review inside a real editor. Hunk-by-hunk accept/reject with keyboard shortcuts is genuinely nicer than reading the same diff in a terminal.
Exploring an unfamiliar codebase. Right-click → "explain this function" while looking at the function is the fastest way to learn a new repo.
Per-request model switching. Mix Opus 4.7, GPT-5, and cheaper models depending on the task.

Where Claude Code wins

These are the cases where I would not even open Cursor. The gap is large enough that there is no contest.

Large refactors across many files

The first time Claude Code paid for itself was a migration job. Rename a config option across thirty-eight files, update the types, fix every test, add a deprecation notice. In Cursor I would have done this with search-and-replace and a lot of cleanup. In Claude Code I described the task in two sentences and walked away for ten minutes. When I came back, it was done and the tests were passing.

For anything that touches more than four or five files, the agent loop is the right shape. You stop being a typist and start being a reviewer. That shift is the real product.

Long-running, autonomous work

Claude Code can run for thirty or forty minutes on a single task without losing the thread. It plans, executes, hits errors, debugs, and finishes. Ultraplan, the newer cloud-planning feature, pushes this even further by separating planning from execution.

Cursor's agent mode can do similar work, but I have never gotten a clean half-hour run out of it. It stops to ask questions or loses context. Claude Code is more comfortable with autonomy.

Running in CI and headless environments

Because Claude Code is a CLI, it runs anywhere a shell runs. Drop it into a GitHub Action and have it review PRs. Pipe data into it. Cursor is an editor, so it lives where editors live: on a developer's laptop. For team automation, this is a real gap.

Real cost over three months

People hand-wave about cost. Here are numbers I actually saw.

Tool	Plan	Months	Real spend
Cursor	Pro $20/mo	3	$60
Claude Code	Max $200/mo	3	$600
Total			$660

That Claude Code spend looks high until you compare it to what those tasks would have cost in human hours. The refactor I mentioned above would have taken me a full day. Claude Code did it for about eight dollars of compute.

If you are on a tight budget, Cursor Pro at $20 is the better starting point. If you bill client work and your time is worth more than $50 an hour, Claude Code pays for itself inside the first project.

Which one to pick for which work

Your situation	Pick
Solo developer, writing a lot of new code	Cursor
Bug fixes in a codebase you know well	Cursor
Multi-file refactor or migration	Claude Code
Writing tests for an existing module	Either
Reviewing a PR (especially in CI)	Claude Code
Learning a new codebase	Cursor for poking, Claude Code for summaries
Heavy automation, scripting, glue work	Claude Code
Very limited budget	Cursor Pro
Client work where your hourly rate is high	Claude Code Max

The honest answer for most working developers is to use both. They are inexpensive enough together that the question is not which to pick, but how to set up your workflow so each one does what it is good at.

The setup I actually shipped

After ninety days, this is what stayed.

Cursor for active coding sessions. Fast tab complete, quick diffs.
Claude Code for everything else. Refactors, test runs, PR reviews, repo-wide search, anything I want running while I am doing something else.
Both pointed at the same shared .claude/ folder so my hooks, skills, and MCP config travel with the repo. A server I write once works in both places.
A few small subagents for jobs I do often — diff review before commit, weekly change log.

Total: $220 a month for the two of them. Saved a lot of time, I have not measured it carefully enough to put a defensible number on it.

A few common questions I get asked about this

Is Cursor going to be replaced by Claude Code?

No. Cursor is an editor with AI. Claude Code is an agent in your terminal. Either can copy a feature, but the form factor of each one limits how much it can become the other.

Can I use Claude Code inside Cursor?

Yes — run the CLI in Cursor's integrated terminal. You lose the editor integration with the agent but keep Cursor's other features.

Does Cursor support MCP?

Yes. Same .cursor/mcp.json format. An MCP server you write once works in both.

Better for non-developers?

Cursor. CLIs have a learning curve not everyone wants to climb.

The full version

This is the dev.to cut. The full version on my blog goes deeper on:

Speed, reliability, and memory benchmarks I tracked
Editor lock-in concerns with Cursor
A longer "common questions" section
Decision rules I now follow when picking which tool to open

If you have the opposite experience from what I described above, I genuinely want to hear it. The most useful comparisons come from people whose work shape is different from mine.

7 Claude Code Routines That Actually Save Me Hours Each Week

Muhammad Moeed — Wed, 13 May 2026 00:51:53 +0000

For a long time, Claude Code felt like a power tool you had to pick up and put down. You opened the terminal, did the work, and closed it. If you wanted Claude to do something while your laptop was asleep, like review a pull request, scan new issues, or summarise the week, you needed a separate setup. A cron job, a GitHub Action, some glue code, and a way to keep your credentials safe.

Routines remove all of that.

A routine is a saved Claude Code configuration. A prompt, one or more repositories, and a set of connectors, packaged once and run automatically on Anthropic cloud. You set it up once. You forget it. It keeps working when your laptop is closed.

This post walks through what a routine actually is, how the three trigger types work, and seven workflows I either run myself or set up for clients. Most of them save more time in a week than they took to write.

What a routine is

The shortest possible definition: a routine is a packaged Claude Code job that runs in the cloud.

Concretely, each routine includes four things.

A prompt describing the work.
One or more repositories the routine should have access to.
The connectors the job needs (Slack, Linear, your MCP servers, anything you have wired up).
A trigger that decides when the routine runs.

When a routine fires, Anthropic spins up a fresh Claude Code session in the cloud, clones the repositories, attaches the connectors, runs the prompt, and shuts down. There is no permission prompt during the run. The session has the same capabilities as your local Claude Code, including shell commands, file edits, skills, and MCP, but it executes autonomously.

You can create routines from three places, and all three write to the same cloud account.

The web app at claude.ai/code/routines.
The Claude Code desktop app.
The CLI, with claude routines create.

A routine created in the web shows up in the desktop app and the CLI immediately. Pick whichever surface you find easiest.

The three trigger types

Triggers are where Routines get interesting. Each routine can have one or more.

Scheduled

The routine runs on a recurring cadence. Hourly, nightly, weekly, or at a specific future time once. This is the closest thing to a cron job, except you describe the cadence in plain English and the cloud handles time zones and retries for you.

API

Each routine gets a private HTTP endpoint and a bearer token. Send a POST and the routine runs. This is the trigger you use when something outside the Claude ecosystem needs to kick off work, like a deploy script, a monitoring tool, or a webhook from another service.

GitHub

A routine attached to a repository can fire on GitHub events. Pull request opened. Pull request synchronised. Release published. Issue created. The event payload is passed into the routine context, so the prompt can refer to "the PR that just opened" and Claude knows what that means.

You can mix them. A nightly schedule plus an on-demand API trigger is a common pattern. The routine runs every night for housekeeping, and you can also poke it manually from a script when you need it.

Who can use them, and how many

Routines are part of the Claude Code on the web offering. The limits map onto your plan.

Plan	Routines per day
Pro	5
Max	15
Team	25
Enterprise	25

If you regularly bump against these limits, the answer is usually to combine smaller routines into bigger ones rather than upgrade plans. A single routine can do quite a lot of work in one session.

A first routine, end to end

Before the workflow examples, here is a complete walkthrough so you can see the moving parts.

1. Create the routine

From the web at claude.ai/code/routines, click New routine. Give it a name like weekly-todo-cleanup. Pick the repository it should work in. Add any connectors it needs.

2. Write the prompt

The prompt is the heart of the routine. Treat it like a clear request to a teammate.

Read the TODOs in this repository that match the pattern
"// TODO" or "# TODO". For each one:

Decide whether the surrounding code still makes sense.
If the TODO is stale (the referenced bug is fixed, the referenced function no longer exists, or the comment is older than 90 days with no recent commits to the file) remove it and add a short note to the commit.
Group the survivors by directory and post a summary to #engineering on Slack, grouped by priority.

Open a pull request titled "chore: weekly TODO cleanup"
against main. Tag @moeed for review.

A few things to notice. The prompt is specific. It names the patterns to look for. It defines what "stale" means. It says what to do with the survivors. Vague prompts produce vague routines.

3. Add a trigger

Schedule it for every Monday at 9am. Save.

4. Run it once by hand

The first run should always be a manual one. You click Run now from the routine page. Watch the session in the web viewer. If the prompt or the connector setup is wrong, you catch it before the scheduled run fires for real.

5. Iterate

The first version of most routines is not quite right. The Slack summary is too long, or the PR title is off, or the TODO heuristic is too aggressive. You read the output, tighten the prompt, and run it again. After two or three rounds, the routine becomes reliable.

Seven workflows worth setting up

These are routines I run or have set up for clients. Each one solves a specific problem. The prompt for each is short. The magic is the trigger and the repo it sees, not the cleverness of the writing.

1. Nightly issue triage

Trigger: Schedule, daily at 7am.

What it does: Reads new GitHub issues from the last 24 hours. Adds labels based on content. Estimates priority based on the components touched. Posts a short summary to your team Slack channel grouped by priority.

Why it pays off: You walk into the office with a categorised list, not an unread inbox. The labels make the existing GitHub workflow faster too. Search and filter actually work because the labels are consistent.

A trimmed version of the prompt:

For every issue opened in this repo in the last 24 hours:

Read the title and body.
Add labels from this set: [bug, feature, docs, infra, perf].
Set a priority label from: [p0, p1, p2, p3] based on:
- p0: production outage or data loss
- p1: regression in a core feature
- p2: notable bug or feature request
- p3: everything else
If priority is p0 or p1, leave a comment tagging @oncall.
Post a Slack summary to #engineering grouped by priority, with links to each issue.

2. PR review pre-pass

Trigger: GitHub, on pull request opened or synchronised.

What it does: Runs your team review checklist before a human looks at the PR. Posts inline comments on mechanical issues, missing tests, unhandled errors, style violations, security smells. Adds a top-level summary so the human reviewer can focus on design.

Why it pays off: Humans review faster because the noise has already been filtered. PR authors get faster feedback. Reviewer fatigue drops.

3. Friday changelog

Trigger: Schedule, every Friday at 4pm.

What it does: Reads all merged PRs from the past week. Groups them into Features, Fixes, Infrastructure, and Docs. Writes a short, plain-English changelog and opens a PR adding it to CHANGELOG.md.

Why it pays off: Your changelog actually gets written. The PR is small, you review it in two minutes, you merge it. Over a year, that compounds into a real document.

4. Stale branch sweeper

Trigger: Schedule, weekly.

What it does: Lists branches that have not had a commit in 30 days, are not the default branch, and are not referenced by an open PR. Posts the list to Slack with one-click links to delete them. Does not delete by itself.

Why it pays off: The repo stays clean. Branches do not pile up. Most teams I have set this up for delete twenty or thirty branches the first week and four or five every week after.

5. Dependency report

Trigger: Schedule, weekly. Or API, on demand.

What it does: Runs npm outdated, pip list --outdated, or whatever the project uses. For each outdated dependency, reads the changelog of the new version and decides whether the upgrade is patch (safe), minor (probably safe), or major (needs a careful look). Posts a summary with recommendations.

Why it pays off: You see the upgrade landscape at a glance instead of running commands and reading changelogs yourself. It does not perform the upgrade. It just tells you what is worth doing.

6. Customer support synthesis

Trigger: Schedule, daily.

What it does: Reads new support tickets and chat transcripts. Clusters them by topic. Writes a short brief for the engineering team listing the top five issues by volume, with example messages and any links between them.

Why it pays off: Engineering hears what users are actually saying. The brief is short enough to read in two minutes and specific enough to drive real changes.

This is one of the highest-leverage routines I have set up. It is also the easiest to over-engineer. Keep the brief short. Two paragraphs and five bullets, no more.

7. Documentation drift watch

Trigger: GitHub, on pull request merged to main.

What it does: Compares the changes in the PR against the docs. If a function signature changed, an environment variable was renamed, or a configuration option was added, flags any docs that reference the old version and proposes the update as a follow-up PR.

Why it pays off: Docs stop rotting. The most common reason docs go stale is that nobody notices the gap between a code change and the doc that describes it. This routine notices.

When a routine is the wrong tool

Routines are powerful, and the temptation is to turn everything into one. Two cases where you should not.

Anything that needs a human decision in the middle. A routine runs end to end without prompts. If the work has a "should I do this?" step, the answer is a skill or a hook inside an interactive session, not a routine.
Anything safety-critical. A routine runs autonomously with whatever connectors you give it. If a wrong run could send the wrong message to a customer, charge a credit card, or push to production, treat it like a deploy. Gate it behind a human-triggered API call rather than a schedule.

A useful rule of thumb. If the work is bounded, reversible, and the cost of a bad run is small, a routine is great. If any of those three is not true, slow down and add a human in the loop.

Best practices that have held up

A few things I keep coming back to.

Start with one routine, not a portfolio. The first routine is the one you will tune the most. Do that work on one job, not five. Once it is reliable, copying the pattern to the next one takes minutes.

Treat the prompt like a small spec. Vague prompts produce flaky routines. Tight prompts produce reliable ones. Spend ten minutes on the prompt for a routine you will run weekly for a year. The cost-benefit is obvious.

Log everything to a place you will actually read. A routine that posts to a Slack channel you mute is a routine you do not benefit from. Send output to a channel or an inbox you check.

Review the run log once a week. Routines drift. APIs change, repos restructure, the world moves. A two-minute weekly review of recent runs catches most issues before they pile up.

Use API triggers as the safety hatch. For any routine with non-trivial side effects, prefer API triggers over schedules. A schedule that runs while you are on holiday and goes wrong is a story you will tell for years. An API endpoint you only call when you mean to is a tool.

Common mistakes

Connectors set up at the wrong scope. Routine-level connectors live with the routine. Personal connectors do not transfer to scheduled runs. The most common "why isn't this working" is a personal connector that the cloud session cannot see.
No dry run. First runs should be manual. Always. The cost of a bad scheduled run on a Monday morning is much higher than the cost of clicking Run now once.
Mega-routines. One routine doing five different jobs is harder to debug than five routines doing one job each. Split them.
Forgetting time zones. The cloud is on UTC. "Every weekday at 8am" can mean different things to different routines. Be explicit.
Treating routines like cron. A cron job runs a deterministic command. A routine runs a Claude session, which is probabilistic. Two runs of the same routine can produce slightly different outputs. Design for that. The wrapping logic (PRs, comments, summaries) should be the deterministic part.

FAQ

What is a Claude Code routine?

A saved Claude Code configuration (prompt, repositories, connectors) that runs on Anthropic cloud on a schedule, an API call, or a GitHub event.

How is it different from Claude Code on the desktop?

Desktop runs interactively, with you in the loop. Routines run autonomously in the cloud. The capabilities are largely the same.

Are routines free?

They count against the daily routine limit on your plan. 5 a day on Pro, 15 on Max, 25 on Team and Enterprise.

Can I trigger a routine from a webhook?

Yes. Every routine has a private API endpoint and bearer token. A webhook can POST to that endpoint to fire the routine.

Can routines call my MCP servers?

Yes. Add the connector at the routine level and the cloud session attaches it like a local one. Make sure the MCP server is reachable from the internet, since the cloud session will not see anything on localhost.

Can routines modify the repository?

Yes, including opening pull requests, leaving comments, and pushing branches. The routine acts with the permissions you grant it.

How do I see what a routine did?

Each run has a session log you can open from the routines dashboard. The log shows the prompts, tool calls, and outputs, just like a local session.

Can I share a routine with my team?

Yes, if your plan supports shared routines. Otherwise, exporting the prompt and connector setup and re-creating it in a teammate account works too.

A short closing thought

The thing routines change is not the work Claude Code can do. It is whether that work happens when you are not there.

A weekly changelog you intend to write rarely gets written. A weekly changelog that writes itself and opens a PR for your review does. Multiply that across triage, review, dependency reports, and docs drift, and the change is not a productivity boost. It is a different relationship with your repo. You stop being the only person who notices.

If you have not set one up yet, the issue triage routine is the best place to start. Pick a repo. Write the prompt. Run it manually once. Schedule it for 7am tomorrow. You will know within two days whether it earns its place. Most do.

Claude Code Dreaming - What /dream Actually Does for Your Memory

Muhammad Moeed — Wed, 13 May 2026 00:07:00 +0000

If you have used Claude Code on the same project for more than a week, you have probably watched your memory files slowly turn into a mess. A few notes here. A list of conventions there. Some half-written instructions that were urgent on Tuesday and are stale by Friday. By the time you notice, your MEMORY.md is a few hundred lines long and Claude is using maybe a tenth of it.

Dreaming is the feature Anthropic shipped to fix this.

A dream is a background pass where Claude reads its own memory, decides what is still useful, merges duplicates, drops anything stale, and writes a cleaner version back. It runs while you are not actively working. You wake up, the memory file is shorter, sharper, and Claude actually uses it again.

This is a friendly walkthrough of what Dreaming is in practice. What AutoDream does in the background. What the /dream slash command does on demand. When to trust it, when to look at the output, and the small mistakes to avoid the first few times you try it.

What Dreaming actually is

Dreaming is best understood as memory consolidation. Claude already writes notes to memory files during a session: what you asked it to do, decisions it made, conventions you taught it. Over time those notes accumulate. Dreaming is the cleanup pass that turns scattered notes into organised knowledge.

There are two ways it runs.

AutoDream runs on its own when Claude Code is idle. By default, it triggers after roughly 24 hours and 5 sessions of activity. You do not start it. You do not see it. You just notice that your memory files are tidier the next morning.
The /dream command is the manual trigger. You run it after a big change, like a framework migration or a renamed module, and Claude consolidates immediately instead of waiting for the next idle window.

Both do the same work. The only difference is who decides when to start.

TL;DR: Dreaming is a background memory consolidation pass that reads your existing memory files, drops anything stale, merges duplicates, and rewrites them into a tighter version. AutoDream runs while you sleep. The /dream command runs on demand.

Why this matters more than it sounds

You can get a long way with Claude Code without ever touching memory. The first time you start using it well, though, you write things to memory often. Project conventions. Names of internal services. The reason a certain test is skipped. The format your team uses for commit messages.

Three months in, two things happen at the same time. The memory file grows past a thousand lines, and the entries inside it start to drift. A convention you wrote in February has been replaced by a different one in April, but both are in the file. A reference to a deleted service is still there. A note about a bug is sitting next to the fix that closed it. The file is no longer a clean summary of how your project works. It is a log.

Long memory files are also less useful than people expect. When Claude pulls memory into context, more is not better. Past a certain length, the model spends attention parsing your notes instead of using them. A shorter, well-edited memory file outperforms a long, sprawling one almost every time.

Dreaming is the answer to both problems. It keeps the file short. It keeps the entries current. You stop having to babysit MEMORY.md by hand.

How AutoDream works under the hood

AutoDream runs in four phases. You can think of it as a small subagent that wakes up, reads your memory, makes a plan, and rewrites the file. Each phase has one job.

Phase 1: read everything

Claude reads every memory file in the project plus your personal MEMORY.md. It does not modify anything yet. It just builds a picture of what is currently there.

Phase 2: classify

Each entry gets sorted into one of three buckets.

Still useful. A real convention, a real preference, a real bit of context.
Stale. References to code that no longer exists, decisions that were reversed later, or notes that were specific to one task and never meant to last.
Duplicate or near-duplicate. Two entries saying the same thing from different angles. The same convention written twice, six weeks apart, with slightly different words.

Phase 3: rewrite

Claude produces a new draft of each memory file. Stale entries are dropped. Duplicates are merged into a single canonical entry. The remaining entries get tightened up so the file is shorter without losing anything that matters.

Phase 4: write back

The new draft replaces the old file. The previous version is kept as a backup so you can diff or revert if something looks off.

The whole pass usually takes a few minutes for a typical project. It happens in the background. Your next session opens against the cleaner file.

Using AutoDream - the default workflow

For most projects, the right thing to do is leave AutoDream on and let it run. The defaults are sensible. You will rarely need to intervene.

A reasonable rhythm looks like this:

Work normally for a few days. Claude writes to memory as you go.
AutoDream fires overnight after the trigger condition is met.
The next morning, your memory files are tidier. You can skim the diff if you want.
Repeat.

The only thing worth doing on your side is to occasionally read what AutoDream produced. Not every time. Maybe once a week. You are looking for two things: that nothing important got dropped, and that the entries that remain are written in a way you agree with.

Using /dream - the manual workflow

Sometimes you do not want to wait. The most common case is a structural change to the project. You renamed half the directories. You migrated from one framework to another. You replaced your test runner. The memory file is now full of references to things that no longer exist, and Claude will keep using those references until the next dream.

That is when you type /dream.

▎ /dream

▎ Reading memory files...

▎ Found 47 entries across MEMORY.md and 3 topic files.

▎ Classifying entries (still-useful / stale / duplicate)...

▎ 12 stale, 6 duplicates, 29 still useful.

▎ Rewriting MEMORY.md...

▎ Saved backup to MEMORY.md.bak

▎ Done. Memory consolidated.

That output is illustrative. The exact wording will differ across versions, but the shape is right. You get a count of what was kept, what was dropped, and a backup of the previous state. The whole thing takes a minute or two on a normal project.

A small note. The /dream command is being rolled out gradually, so on some accounts it may not be available yet. If it does not work for you, you can ask Claude in plain English: "consolidate my memory files" or "run a dream cycle." Claude does the same thing under the hood.

When to trigger a dream by hand

A few moments are worth the small interruption of running /dream.

After a big refactor. Renamed modules, restructured folders, changed your build tool. Old references in memory turn into noise after a change like this.
After a framework migration. You moved from Vue to Svelte, from Express to Fastify, from one ORM to another. The same logic.
Before sharing the project with a new collaborator. A clean memory file is much easier for someone else to read than a six-month log.
When Claude starts behaving oddly. If Claude is making suggestions that feel out of date, the memory is probably stale. A dream usually fixes it.

For everything else, leave AutoDream alone.

AutoDream vs /dream vs editing by hand

This is the question I get most often. Here is how I think about the three options in practice.

Method	When to use	Cost
AutoDream	Default. Day-to-day projects you do not want to think about.	Zero. Runs while you sleep.
/dream	After a big change, before a handoff, or when memory feels stale.	A minute or two on demand.
Edit by hand	When you disagree with something Claude wrote.	Real time, but full control.

A useful rule of thumb. If the issue is "the file is messy," that is a job for AutoDream or /dream. If the issue is "the file is wrong," that is a job for you. Memory consolidation cleans up the file. It does not fix bad source material.

A small example: before and after

Suppose you started a project in March and your MEMORY.md now looks something like this.

The auth service lives in /src/auth.
We use bcrypt for password hashing.
Auth has been moved to /server/auth in April.
Use bcrypt rounds = 12.
Session tokens expire after 1 hour.
We switched from bcrypt to argon2 in May.
Session tokens are now 30 minutes by default.
Use argon2id with parallelism = 4.
Do not put session tokens in localStorage.
We use argon2 (id mode).

After a dream cycle, that becomes:

The auth service lives in /server/auth.
Use argon2id for password hashing with parallelism = 4.
Session tokens expire after 30 minutes.
Do not store session tokens in localStorage.

Four lines instead of ten. No contradictions. No stale references. Same project knowledge, much easier for Claude to use in the next session.

Common mistakes the first few times

A few patterns I have seen.

Disabling AutoDream because of one bad pass. AutoDream occasionally drops something you wished it had kept. The right response is usually to add the dropped fact back by hand, not to turn the feature off. The average across a hundred passes is strongly net positive.
Treating /dream as a fix for bad memory. If your memory file has wrong information, dreaming will keep the wrong information, just in a tidier form. Fix the source first.
Running /dream in the middle of a task. Memory consolidation rewrites files that Claude is using. Save it for between tasks.
Ignoring the backup file. Every dream writes a .bak of the previous memory. If you do not like the result, you can revert.
Expecting it to merge across projects. Dreaming runs per project. It does not pool memory across all your repos.

Best practices that actually matter

Three rules I follow after a few months with this feature.

Read the diff once a week. Not every dream. Just one a week. You are checking that nothing important is being quietly dropped and that the writing style matches what you want. A two-minute skim catches drift early.

Keep CLAUDE.md and memory separate. CLAUDE.md stays small and always-on. Memory grows and is consolidated. Mixing them weakens both.

Pair Dreaming with Skills. If a piece of guidance is a stable workflow, promote it from memory into a skill. Skills are explicit, versioned, and shared with your team. Dreaming makes the ephemeral side sustainable. Skills make the stable side reliable.

FAQ

What is Claude Code Dreaming?

A background pass that consolidates your memory files. It reads what Claude has written to MEMORY.md and any topic files, drops stale entries, merges duplicates, and rewrites a cleaner version.

What does AutoDream mean?

AutoDream is the automatic mode. It runs when Claude Code is idle and certain conditions are met, usually a day of activity and at least five sessions.

What does /dream do?

It triggers a dream cycle on demand. Same work as AutoDream, but it runs immediately instead of waiting for the next idle window.

Will Dreaming delete my memory?

No. It rewrites the file to be shorter and cleaner. A backup of the previous version is saved next to the file so you can diff or revert.

Is Dreaming safe to use on a shared project?

Yes. Project memory files are committed to git in most setups. After a dream, you see the diff like any other change and decide whether to merge it.

Does Dreaming work with subagents?

Dreaming only affects your main session memory. Subagents run in separate, fresh contexts and do not share that file.

Can I turn AutoDream off?

Yes, in Claude Code settings. Most people are better off leaving it on and reviewing the diff occasionally.

A short closing thought

The thing that surprised me about Dreaming is how quietly useful it is. You do not notice the feature on day one. You notice it three weeks later when you realise your memory file is still readable, still relevant, and still under a few hundred lines, without you ever having tidied it.

If you have a project where Claude already writes to memory, just leave AutoDream on for a couple of weeks and see what it does. The first time you run /dream after a big refactor and the noise goes away, you will understand why this is the feature people are quietly excited about.

Claude Code Skills: A Practical Guide for 2026

Muhammad Moeed — Mon, 04 May 2026 21:53:00 +0000

If you have spent any real time with Claude Code, you have probably noticed the same problem I did. You write the same instructions in the prompt every other day. "Use four-space indentation here." "Always run the linter after edits." "Format commit messages this way." After the third or fourth repeat, it stops feeling like a prompt and starts feeling like missing config.

Skills are how Claude Code fixes that. A skill is a small folder, with one markdown file inside, that Claude pulls into the conversation only when your request actually needs it. No setup screen. No plugin manager. Just a file in a folder and a one-line description telling Claude what it is for.

This post is a clean walkthrough for 2026. What a skill actually is, how to write your first one, where to put it, and how it compares to the two things people often confuse it with: slash commands and subagents.

What a Claude Code Skill actually is

At the most basic level, a skill is a directory with a single file called SKILL.md inside it. The file has two parts.

A short YAML frontmatter at the top, with a name and a description.
A markdown body underneath, with the instructions Claude follows when the skill is triggered.

That is the whole spec. Everything else, examples, supporting scripts, templates, helper files, is optional and lives in the same directory.

Here is the smallest valid skill you can write:

.claude/skills/run-tests/
└── SKILL.md

---
name: run-tests
description: "Run the project's test suite using the Makefile target. Use this whenever the user asks to run tests, check tests, or verify the test suite is passing."
---

Run `make test` from the repo root. If the command fails, read the failing test
output, point out the specific assertion that broke, and ask before changing
anything in the source files.

That is a working skill. Drop it in .claude/skills/run-tests/, restart Claude Code, and the next time you say "run the tests" Claude will use this instead of guessing.

How Claude actually picks up a skill

This is the part that confuses people most. Skills are not always-on. They are auto-discovered.

Here is what happens when you send a message:

Claude reads the descriptions of every skill it can see.
It compares your message to those descriptions.
If one matches, it pulls that skill's full content into the conversation.
If nothing matches, no skill is loaded and you get the default behavior.

This is why the description does most of the heavy lifting in any skill. It is the only thing Claude has to decide whether the skill applies. A vague description ("Helps with tests") will rarely fire. A specific one ("Runs the project's pytest suite when the user asks to run, check, or verify tests") will fire reliably.

A simple test: read your description out loud. If it does not start with a clear verb and end with a clear trigger, rewrite it.

Where skills live

Skills sit in one of three places. The location decides who sees them.

Location	Scope	When to use
`.claude/skills/<name>/` inside a repo	Project	Workflows specific to one codebase
`~/.claude/skills/<name>/` in your home directory	Personal	Workflows you want everywhere
Plugins or shared packages	Team	Skills you want to ship to others

Project skills win when there is a conflict. So if your repo has a run-tests skill and your personal folder has one too, the project one is used while you are inside that repo. That is almost always what you want.

A small but important detail: skills that live inside the repo are checked into git by default. That is fine. They are usually short, they help every collaborator, and they are easier to review than long CLAUDE.md files.

A walkthrough: build a skill from scratch

Let us write something slightly more useful than run-tests. Say you have a personal habit of starting every commit message with a Conventional Commit type (feat:, fix:, chore:). You want Claude to do the same when it commits.

Step 1: make the directory

From the root of your project:

mkdir -p .claude/skills/conventional-commit

Step 2: write SKILL.md

Open .claude/skills/conventional-commit/SKILL.md and put this inside:

---
name: conventional-commit
description: Use this skill any time the user asks for a git commit, to commit changes, or to write a commit message. It writes the message in Conventional Commit format.
---

When you create a git commit, follow these rules.

1. Start the subject line with one of: feat, fix, chore, docs, refactor, test, perf.
2. Add a colon and a space, then a short imperative summary, no period.
3. Keep the subject under 70 characters.
4. If the change touches more than two files, add a one-line body that says why.

Example:

  feat: add IndexNow ping to publish workflow

  Auto-pings Bing on every push to main so new posts get indexed faster.

Step 3: try it

Restart Claude Code (or just open a new conversation). Say "commit these changes". Claude should pull in the skill, follow the format, and you should see a commit subject that matches the rules.

If it does not fire, the description is the first thing to fix. Make the trigger words match what you actually say to Claude.

Skills vs slash commands vs subagents

This is the question I get most often, and the line is genuinely fuzzy because the three features have grown closer over time. Here is how I think about them in practice.

Skills

Auto-discovered. Claude decides when to use them based on your message.
Live inside the main conversation, so the work stays visible and you can intervene.
Best for: repeated workflows you do not want to type out, like commit formatting, test running, or PR conventions.

Slash commands

You invoke them by hand, with /command-name.
Same file format as skills now, in fact a single skill file gives you both an auto-trigger and a /run-tests slash command for free.
Best for: explicit triggers when you want full control over when something runs.

Subagents

Spawned by Claude into a separate, fresh context with their own tools and memory.
They do not see your conversation. They get a brief from Claude and report back.
Best for: heavy or noisy work you want to keep out of your main context, like searching the whole repo, running long evals, or summarising a large diff.

A useful rule of thumb. If the work is small and should stay in front of you, that is a skill. If the work is big and should run in a side process, that is a subagent. If you specifically want a typed entry point, slash command.

For more on the subagent side, the hooks guide on this site covers the shell-level lifecycle that pairs well with skill-based workflows.

Three small skills that pay for themselves

These are skills I have on most of my repos. None of them are clever. All of them save real time.

1. `lint-after-edit`

---
name: lint-after-edit
description: Run the project's linter after any code edit. Use any time the user asks Claude to edit, refactor, fix, or modify a source file.
---

After completing any edit to a .ts, .tsx, .js, or .py file, run `npm run lint`
(or `ruff check .` for Python). If the lint fails, fix the warnings before
reporting that the edit is done.

The reason this works is that "edit a source file" is a very common trigger. The skill fires almost every coding session and you stop seeing lint failures land in commits.

2. `pr-description`

---
name: pr-description
description: Write a pull request description from the current branch's commits. Use any time the user asks for a PR description, PR body, or pull request summary.
---

Read `git log main..HEAD` and write a PR description in this format.

## Summary
One short paragraph, no marketing language.

## Changes
- One bullet per logical change, not per commit.

## Test plan
- A checklist a reviewer can run.

Do not include emojis, do not start lines with "This PR".

The "do not" lines matter. Negative instructions are how you stop Claude from drifting back to its defaults.

3. `clean-imports`

---
name: clean-imports
description: Remove unused imports and sort the rest. Use any time the user asks to clean imports, sort imports, or tidy imports in a file.
---

For each file the user asks to clean:

1. Remove imports that are not referenced anywhere in the file.
2. Sort what remains by: standard library, then third-party, then local.
3. Group each section with a blank line between them.

Do not touch import side effects (imports with no name).

Skill, slash command, and auto-trigger all in one file. Same content. Three ways to invoke it.

Best practices that actually matter

After writing dozens of skills for myself and clients, three rules stand out.

One skill, one job

The most common mistake is the mega-skill. A single SKILL.md trying to handle commits, PRs, branch naming, and changelog updates all at once. Mega-skills load late, fire less reliably, and confuse Claude when two parts conflict. Split them. A skill should fit on one screen.

Write the description like a trigger, not a label

Bad:

A skill for working with tests.

Good:

Run the project's pytest suite when the user asks to run tests, check tests, or verify the test suite is passing.

The good version names the verbs Claude needs to spot. "Run", "check", "verify" — those are the words a user actually types.

Keep instructions imperative

Skills that read like documentation ("This skill is responsible for...") fire less reliably than skills that read like instructions ("Run X. Then Y. If Z, do W.") Direct verbs map cleanly to actions.

Resist the urge to over-script

You can ship Python or shell scripts inside a skill folder, and sometimes that is right. But for most workflows, plain markdown instructions are enough and easier to maintain. Use scripts when the work is genuinely deterministic, not just because you can.

Common mistakes

A few patterns I see again and again.

Description is too generic. If yours starts with "A skill that helps with...", it will rarely fire. Rewrite it to start with a verb.
Skill is in the wrong folder. ~/.claude/skills/ is for personal skills across all projects. .claude/skills/ is for the current project only. Mixing them up is the most common reason a skill "is not picked up."
Trying to replace CLAUDE.md. Skills are for repeated, triggered workflows. CLAUDE.md is for always-on context like project conventions. They complement each other.
Forgetting to restart Claude Code. Skills are loaded on session start. If you add one mid-conversation, end the session and start a new one.
Putting secrets inside SKILL.md. Skills are committed to git in most setups. Treat them like source code, not config.

Frequently asked questions

Where exactly do project skills go?
Inside your repo at .claude/skills/<skill-name>/SKILL.md. The folder is committed to git unless you ignore it.

How is this different from a slash command?
A skill file is a slash command. The same file gives you both auto-discovery and a /skill-name invocation. Slash commands are the manual entry point. Skills are the auto-discovered side of the same thing.

How is it different from a subagent?
Subagents run in a fresh, isolated context. Skills run inside your current conversation. Use a skill when you want the work in front of you. Use a subagent when you want it offloaded.

Do I need to restart Claude Code after adding a skill?
Yes. New skills are picked up when a session starts. End the conversation and open a new one to load them.

Can a skill use external scripts?
Yes. You can include shell or Python scripts in the skill folder and reference them from SKILL.md. For most workflows, plain markdown instructions are enough.

Does this work in Claude Chat or only in Claude Code?
The same SKILL.md format works across Claude Code, Claude Chat, and Claude Cowork. Each product looks for skills in its own location, but the file format is identical.

Should I put skills in CLAUDE.md instead?
No. CLAUDE.md is for always-on project context. Skills are for triggered workflows. Loading every workflow into CLAUDE.md bloats the main context and slows the model down.

A short closing thought

The reason skills matter is not that they are clever. It is that they remove the small, repeated friction of telling Claude the same thing every day. A good skill is short, targeted, and almost invisible: you stop noticing it because the work just gets done the way you wanted.

Start with one. The smallest one you can think of. A commit format, a lint rule, a PR template. Once one is working, write the next one. Within a week or two you will have a folder of small files that quietly shape how Claude works on your project, and you will wonder how you ever managed without them.

If you are extending Claude Code with hooks for shell-level enforcement or building MCP servers for richer integrations, skills sit comfortably between the two: lighter than a server, more flexible than a hook, and easier to share across a team than either.

DEV Community: Muhammad Moeed

Claude Code slow or worse? How to diagnose and fix it in 2026

What actually happened

Three quick checks

1. Are you on the fixed build?

2. Run /doctor

3. Check status

Six fixes for the rest

The diagnostic tree

Claude Agent SDK vs Vercel AI SDK 6 — which to pick in 2026

The short version

Side by side at a glance

Same agent in both

Claude Agent SDK

Vercel AI SDK 6

Where each wins

A simple way to choose

AWS Copilot CLI is reaching end of support — your migration options

What changes on June 12, 2026

What AWS recommends instead

Service-by-service map

How to plan the move

Claude Code /goal and Agent View, explained

What /goal does

The detail most posts skip

How it compares

Agent View

What is AWS ECS Express Mode (and when to use it)

What you give it

What it builds

What it costs

When not to use it

How Anthropic's own teams use Claude Code

The report in one paragraph

A few of the stories

The patterns worth keeping

The honest parts

What a solo developer can copy today

Claude Code vs Cursor — 90 days with both in 2026

TL;DR

What they actually are

Where Cursor wins

Where Claude Code wins

Large refactors across many files

Long-running, autonomous work

Running in CI and headless environments

Real cost over three months

Which one to pick for which work

The setup I actually shipped

A few common questions I get asked about this

The full version

7 Claude Code Routines That Actually Save Me Hours Each Week

What a routine is

The three trigger types

Scheduled

API

GitHub

Who can use them, and how many

A first routine, end to end

1. Create the routine

2. Write the prompt

3. Add a trigger

4. Run it once by hand

5. Iterate

Seven workflows worth setting up

1. Nightly issue triage

2. PR review pre-pass

3. Friday changelog

4. Stale branch sweeper

5. Dependency report

6. Customer support synthesis

7. Documentation drift watch

When a routine is the wrong tool

Best practices that have held up

Common mistakes

FAQ

A short closing thought

Claude Code Dreaming - What /dream Actually Does for Your Memory

What Dreaming actually is

Why this matters more than it sounds

2. Run `/doctor`

1. `lint-after-edit`

2. `pr-description`

3. `clean-imports`