Acquire Skill

Step 2: Research the Domain

Gather comprehensive information to write an authoritative skill definition:

1. Official documentation — WebFetch from official docs
2. Web search — WebSearch for best practices, tutorials, common pitfalls
3. Codebase patterns — Grep/Glob for any existing usage or related code
4. Existing skills — Read similar skills for structural patterns
5. Template — Read .claude/skills/_templates/SKILL.md.template for required structure

Record all sources with URLs and key findings.

Step 3: Draft the Skill Definition

Create .claude/skills/<skill-name>/SKILL.md following the template structure.

Required Sections

Every skill must have:

1. Frontmatter — YAML between --- delimiters:

   ---
   name: <skill-name>
   description: <one-line description>
   argument-hint: <usage hint>
   ---
   

2. Context — Why this skill exists and when to use it

3. Workflow — Numbered steps the agent follows. Each step must be:

   • Atomic (one clear action)
   • Testable (you can verify it happened)
   • Include expected outputs

4. Inputs — Parameters table with required/optional, types, defaults

5. Outputs — Artifacts produced (files, GH objects, notifications)

6. Error Handling — Failure modes and recovery actions

Quality Criteria

• Steps reference specific commands, file paths, or API calls
• No vague instructions like "configure as needed" — be specific
• Include concrete examples with realistic values
• Error handling covers the top 3 most likely failures
• Follows conventions from existing skills (read 2-3 for style)

Step 4: Create Companion Reference (if needed)

If the skill requires extensive reference data (API docs, config options, decision trees):

1. Create .claude/skills/<skill-name>/reference.md using the reference template
2. Link it from the SKILL.md: "For detailed reference, see reference.md"
3. Keep the SKILL.md focused on workflow; put lookup data in the reference

Step 5: Register the Skill

5a. Update CLAUDE.md

Add the skill to the appropriate table in the project's CLAUDE.md:

If user-invocable (has a /command), add to the "Commands" table:

| `/command` | `.claude/skills/<name>/SKILL.md` | Description |

If agent-only, add to the "Skills" table:

| **Skill Name** | `.claude/skills/<name>/SKILL.md` | Description |

5b. Update Agent Definitions

For each agent that will use this skill:

1. Read .claude/agents/<agent>.md
2. Add the skill to the agent's skills: frontmatter list
3. Add a reference in the agent's Quick Reference section

5c. Commit

git add .claude/skills/<skill-name>/
git commit --no-gpg-sign -m "acquire-skill: Add <skill-name> skill definition"

Step 6: Validate

Run a quick validation:

1. Frontmatter check — name, description, argument-hint all present
2. Section completeness — Context, Workflow, Inputs, Outputs, Error Handling exist
3. No placeholders — no unresolved template tokens remain (except project-level ones like {{PROJECT_NAME}})
4. File exists — .claude/skills/<name>/SKILL.md committed

Step 7: Summary

Skill acquired: <skill-name>
  - File: .claude/skills/<skill-name>/SKILL.md
  - Reference: .claude/skills/<skill-name>/reference.md (if created)
  - Invocable: /command (or agent-only)
  - Agents: <list of agents>
  - Registered in: CLAUDE.md
  - Sources: N consulted

Next: Test the skill by running /<command> or delegating to an agent.

Inputs

Outputs

Error Handling

Examples

User invocation

/acquire-skill azure-blob-storage

From EM during sprint

The mobile-engineer reports they don't know how to configure EAS
submissions. Running /acquire-skill eas-submit to create the skill.