🎣 Define the trigger (a description that triggers the skill)
A description in the frontmatter, tell the model when use the skill. A good one has action verbs + concrete triggers ("Use when diagnosing the AI maturity of a company described in text"). A vague description = the skill never triggers. That’s the detail that separates a skill that works from one that sits dormant in the repository.
✓ Good description
- ✓Start with action verb ("Use when diagnosing...")
- ✓Specific trigger: "company described in text"
- ✓Say the "use when" — the model knows the right time
✗ Weak description
- ✗Generic: "help with AI strategy"
- ✗No trigger — doesn’t say when to apply it
- ✗Ambiguous — conflicts with other skills and never triggers
// .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 (esforço × impacto) e um roadmap 30/60/90. --- # Diagnóstico de IA ## Passos 1. Ler nome + descrição da empresa. 2. Pontuar a maturidade de IA numa escala 1-5. 3. Listar 3 quick wins (baixo esforço, alto impacto). 4. Propor um roadmap 30/60/90 dias. 5. Devolver em Markdown, pronto para virar entregável. ## Referências - referencias/maturidade.md - referencias/quick-wins.md
💡 Practical tip
Write the description with the way the model reads in mind: "If I saw this sentence, would I know this is the time to use the skill?" If the answer is "maybe," rewrite it with a more concrete trigger. The description is the doorway—without it, no one gets in.
the “use when”
concrete action
name + description
vague = never takes hold
📝 Write the body (clear, deterministic steps)
The Markdown body lists numbered steps to make the output repeatable: research the company → score maturity from 1-5 → list 3 quick wins → propose a 30/60/90 roadmap. Deterministic means that when you run it twice, you get the same structure — no improvising. Each step is an instruction, not a suggestion.
Read the company
Extracts the name, sector, company size, and context from the text received. Without this, the diagnosis is generic—the first step anchors all the others.
Score maturity (1-5)
Give it a score from 1 to 5 with a brief explanation. A fixed scale makes results comparable across companies—it becomes a metric, not an opinion.
List 3 quick wins
Exactly three—low effort, high impact. The fixed number prevents bloated lists and forces real prioritization.
Propose a 30/60/90 roadmap
Three windows, concrete actions in each. It returns Markdown, ready to become a deliverable — the client opens it and takes action.
steps in order
same structure
1–5 comparable
Markdown ready
📎 Attach References (the T2 cheat sheets)
The skill points to supporting files—the maturity and quick-win cheat sheets you distilled in Track 2—loaded only when needed. It’s the Lazy RAG applied: the SKILL.md stays concise, while the skill gains consulting-level rigor when it produces the work.
📄 references/maturity.md
The 1–5 scale rubric: what defines each level, with signs and examples. Loaded when step 2 needs a score.
📄 references/quick-wins.md
The catalog of departmental quick wins, mapped by effort × impact. It comes in when step 3 lists the quick wins.
// skill folder structure
.claude/skills/diagnostico-ia/
├── SKILL.md
└── referencias/
├── maturidade.md
└── quick-wins.md
💡 Practical tip
Don’t paste the cheat sheet contents into the SKILL.md. Reference the path (referencias/maturidade.md) and have the model open the file only when the step requires it. A lean SKILL.md = a skill that activates quickly and doesn't waste context.
loads when needed
Lightweight SKILL.md
T2 cheat sheets
custom context
🧪 Test the skill with a real case
Run the skill for a real company and check three things: did it trigger on its own (did the description work)? Does the output include maturity + quick wins + roadmap? Is the format ready to deliver? Testing is where theory meets real-world friction.
// what you type to Claude Code
Use a skill diagnostico-ia para a empresa "Stripe": B2B payments, fintech, ~8000 funcionários.
🔍 The test checklist
- •Did it run on its own? If you had to force it, the description is weak—go back to topic 1.
- •Complete output? Maturity 1–5 + 3 quick wins + 30/60/90 roadmap — all three included.
- •Ready to deliver? Clean Markdown, with no drafts or questions in the middle.
real company
established itself on its own?
the 3 blocks
polished deliverable
🔁 Iterate and Package
The first version rarely gets it right away. Adjust the description and steps based on what the test showed, finalize the skill folder (SKILL.md + references), and leave it ready. Iteration is the real work — the first version is just the draft taking shape.
✓ Ready-to-use skill
- ✓Runs on its own — the description completes the trigger without you forcing it
- ✓Consistent output — same structure every time it runs
- ✓References load — the cheat sheets come in at the right time
✗ Not yet
- ✗Doesn’t trigger — you need to ask for the skill by name every time
- ✗Output varies — sometimes it skips the roadmap, sometimes it invents a format
- ✗Bloated SKILL.md — content that should be in the references
💡 Practical tip
Iterate on one thing at a time: adjust only the description, test; then adjust only the steps, test. Changing everything at once hides what actually fixed it. Short, small cycles get you to the triggering version faster.
description + steps
complete folder
one change at a time
consistent and concise
🏷️ Version and share
Version-control the skill in Git (alongside the project) and optionally share it with your team or the community. The history gives you traceable progress; version control protects the asset; sharing builds authority. The skill stops being a loose file and becomes part of your repository.
💡 Practical tip
Commit a skill alongside the project that uses it, not in a separate repository. That way, it travels with the context—anyone who clones the project gets the tool ready to use. A good commit message ("adjusts diagnostico-ia trigger") is already part of the history.
alongside the project
traceable progress
the safe asset
you build
✅ Module summary
🎯 Mission 3.2 — diagnostico-ia live
Get your first skill running:
- Create
.claude/skills/diagnostico-ia/SKILL.mdwith frontmatter + 5 steps. - Attach the T2 cheat sheets as references.
- Run the skill for 1 real company.
- Iterate on the description until it triggers on its own.
Success: the diagnostico-ia skill runs and spits out a mini-diagnosis (maturity + quick wins + roadmap). What you gained: the Factory’s first gear—reusable and versioned.
Next module:
3.3 — The document skill (DocX/PPTX/Excel/PDF)