🧩 What is a skill
A skill is a reusable capacity that Claude Code loads on demand. In practice, it's a file SKILL.md: a frontmatter with name e description, plus a Markdown body with steps and optional reference files.
A description is the trigger: when the task you request matches it, the skill activates on its own and injects the steps into the context. You teach it once and use it every time—without rewriting the procedure for each conversation.
💡 Practical tip
Think of a skill as a colleague who already knows the procedure. You don't explain it again — you just say "do that thing" and the description recognizes the request. The better the description, the more accurately the trigger fires.
teaches it once
loads when needed
frontmatter + steps
the active description
🕵️ What is a subagent
A subagent is a separate instance of Claude, with its own context window, its own system prompt, and its own tools. It receives a task, works in isolation, and returns only the result — so the main agent's context stays clean.
It’s a dedicated worker. What it reads, downloads, and processes stays in its context, not yours. You only get a summary of what matters—the equivalent of delegating a heavy research task without flooding the conversation.
Receives the task
The main agent delegates a specific task — "research company X," "scan this sector" — with clear instructions.
Works independently
Reads dozens of pages, runs searches, processes data — all in its own context. None of that clutters your thread.
Returns the summary
Returns only the conclusion—the findings that matter. The main agent continues with lean, focused context.
your own context
own prompt + tools
only what matters
protects the core
⚖️ Skill vs agent: when to use each
The most common mix-up is using an agent when a skill would do—and overengineering. The rule is simple. Skill is a capability you give the main agent (generating a PPTX, running a diagnostic). Subagent is a separate worker for a task that uses a lot of context or needs isolation (scanning the web, researching a company).
Rule of thumb: same thread + reusable procedure → skill. Separate thread + heavy or independent work → subagent.
✓ Becomes a SKILL when…
- ✓It’s a procedure that repeats in the same thread
- ✓You want to give the main agent a capability
- ✓The result stays in the conversation (deck, diagnosis, SOW)
- ✓Doesn’t use much context to run
✓ Becomes an AGENT when…
- ✓The work burns through a lot of context (scanning the web)
- ✓Needs isolation — doesn't want to clutter the thread
- ✓It’s independent and can run in parallel
- ✓You only want the summary back, not the process
💡 When in doubt, start with a skill
A subagent gives you more power, but also adds another moving part. If the task fits in the same thread without overwhelming the context, make it a skill. Promote it to a subagent only when isolation or context volume calls for it.
capacity
heavy delegation
→ skill
→ subagent
🔬 Anatomy of a skill (SKILL.md)
A skill is a single file. At the top, YAML frontmatter with name e description. Below is a Markdown body with the steps. See the minimum structure for an AI diagnostic skill.
// .claude/skills/diagnostico-ia/SKILL.md
--- name: diagnostico-ia description: Use ao diagnosticar a maturidade de IA de uma empresa descrita em texto — gera maturidade 1-5, quick wins e roadmap 30/60/90. --- # Diagnóstico de IA ## Passos 1. Ler a descrição da empresa. 2. Pontuar a maturidade de IA (1-5). 3. Listar 3 quick wins (esforço × impacto). 4. Sugerir um roadmap 30/60/90.
short id — the skill name, used to reference it. No spaces, straight to the point.
the trigger — describes when use the skill. That’s what Claude reads to decide whether to activate it.
the steps — the Markdown procedure the agent follows after activation.
💡 The description is the most overlooked part
It’s the most important and most neglected piece. A vague description ("helps with strategy") never activates at the right time. Say when use, with concrete triggers — that’s what makes the skill appear automatically.
short id
the trigger
the steps
everything in one SKILL.md
📁 Where skills and subagents live
Everything lives in one folder .claude/. Skills are in .claude/skills/<nome>/SKILL.md; subagents in .claude/agents/<nome>.md. The choice is between project scope (goes into Git) and personal scope (applies to all your projects).
📦 From the project (.claude/)
- ✓Lives in the project repository root
- ✓It goes into Git — the whole team inherits it
- ✓Ideal for the Factory: versioned with the code
🏠 Personal (~/.claude/)
- ✓Lives in your home directory — outside any repo
- ✓It applies to every project you open
- ✓Ideal for your own general-purpose tools
// project structure
.claude/
├── skills/
│ ├── diagnostico-ia/SKILL.md
│ └── gerar-entregavel/SKILL.md
└── agents/
├── pesquisador-empresa.md
└── redator-estrategia.md
one SKILL.md each
one .md each
goes in Git
applies to everything
💎 The ecosystem of reusable resources
Here’s why all of this becomes an asset. Each skill and each agent is built once and reused forever. Together, they form the gears of the Factory—your arsenal.
It’s the "minimum input, maximum output" thesis turned into code. The effort goes into building, not delivery. The more pieces you accumulate, the more the Factory delivers on its own—and the marginal cost of each new client plummets.
💡 Build the arsenal, not the deliverable
Every time you do a task by hand, ask yourself: “Could this become a skill or an agent?” If so, turn it into one — and never do it again from scratch. The deliverable is disposable; the reusable asset is what builds up and gives you leverage.
always reuse
Factory components
accumulates
marginal cost ↓
✅ Module summary
🎯 Mission 3.1 — Map your arsenal
List your tasks and classify each as a skill or subagent:
- 3 repetitive tasks yours that become skill (e.g., assess a company, generate a deck, write an SOW).
- 2 tasks that become subagent (e.g., research a company on the web, scan an entire industry).
Success: 3 skills + 2 agents mapped. What you gained: the design of your arsenal—what to build in the upcoming lessons.
Next module:
3.2 — Build your first skill (diagnostico-ia)