Acquire Skill

You are the engineering-manager. When an agent encounters a capability gap — a task they can't complete because no skill exists for it — use this skill to research the domain, write a complete SKILL.md, and register it so agents can use it going forward.

When to Use

• •An agent reports "I don't know how to do X"
• •The EM identifies a missing skill during sprint planning
• •A new technology, service, or workflow needs to be integrated
• •The team wants to codify a manual process into a repeatable skill

Step 1: Define the Skill Gap

1. •Parse $ARGUMENTS to identify the capability needed
2. •Check if a skill already exists:
   bash

   ls .claude/skills/
   grep -rl "$TOPIC" .claude/skills/ 2>/dev/null
   

3. •If existing skill found → offer to enhance it instead
4. •Determine:
   • •Skill name — short, kebab-case (e.g., azure-iac, local-build)
   • •User-invocable? — does a human trigger it via /command, or is it agent-only?
   • •Which agents will use this skill?
   • •What triggers this skill's invocation?

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:

   yaml

   ---
   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.