The latest articles on DEV Community by Hammad Parveez (@hammadparveez). https://dev.to/hammadparveez https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F1390425%2F7cba967f-457e-41e2-aeff-53503e6fd1c8.jpeg https://dev.to/hammadparveez en Hammad Parveez Fri, 24 Apr 2026 01:53:00 +0000 https://dev.to/hammadparveez/skill-or-subagent-the-30-second-rule-most-claude-code-devs-still-get-wrong-24ij https://dev.to/hammadparveez/skill-or-subagent-the-30-second-rule-most-claude-code-devs-still-get-wrong-24ij <p>Two Claude Code primitives. Two very different jobs. Here's the rule I use to pick between them.</p> <h2> Most devs still confuse these </h2> <p>Almost every Claude Code setup I review has the same bug: subagents doing the work of skills, and skills being skipped where they'd actually help.</p> <p>The two primitives look similar from the outside. They do very different jobs.</p> <h2> The rule </h2> <p>Skill = knowledge you reuse.</p> <p>Subagent = capability you delegate.</p> <p>Everything else is examples.</p> <h2> Skill: durable knowledge the model reads every time </h2> <p>A skill is a folder in <code>~/.claude/skills/&lt;name&gt;/</code> with a <code>SKILL.md</code> and any supporting files. When you invoke it, Claude reads the whole folder into your current context.</p> <p>My post-generator skill holds:</p> <ul> <li>12 reference posts I admire, annotated with voice notes</li> <li>16 researched excerpts from engineers I respect</li> <li>12 human-writing patterns</li> <li>5 AI tells to avoid</li> <li>Per-platform output templates (LinkedIn, X, Medium, Dev.to, Hashnode)</li> </ul> <p>None of that is <em>a task</em>. It's what I want applied every time I draft a post. Skill territory.</p> <h2> Subagent: a focused job with isolated context </h2> <p>A subagent is a specialist you dispatch. It runs in its own context window, does the work, and returns a summary.</p> <p>This afternoon I ran a researcher subagent that did 10 web searches to find AI tip-guide angles trending this week. It came back with 900 words I could act on.</p> <p>If I'd done that in my main session, I'd have flushed maybe 30K tokens of tool output into my context — search results, page fetches, HTML — none of which I actually needed once the summary was written.</p> <p>Subagent territory.</p> <h2> The quick test </h2> <p>Ask yourself: is this <em>what to know</em> or <em>a job to do</em>?</p> <ul> <li>Coding style rules → skill</li> <li>A lint-fix runner for a specific repo → subagent</li> <li>Your team's API design principles → skill</li> <li>Scanning a repo for security issues → subagent</li> <li>Your post-writing voice → skill</li> <li>Researching a topic and returning findings → subagent</li> </ul> <p>Rule of thumb: if it's going to be referenced across many tasks, it's a skill. If it's going to be invoked once to produce a specific output and then exit, it's a subagent.</p> <h2> Why people get it wrong </h2> <p>The most common mistake I see: turning a rulebook into a subagent.</p> <p>Someone writes a "code review agent" that's 500 lines of "always check X, reject Y, prefer Z." That's a skill wearing a subagent costume. You could have just written those rules as a skill and invoked it in your main session — same behavior, fewer tokens, simpler mental model.</p> <p>The flip side is worse: stuffing genuine capability work into your main context. Tool output drowns your working context. You wanted to delegate; you actually just inlined.</p> <h2> Close </h2> <p>Stop building subagents for things that are really knowledge.<br> Stop cramming subagent work into your main context.</p> claudecode claude ai mcp