architecture/skills/create-capability/SKILL.md

name, description, model, argument-hint, user-invocable

name	description	model	argument-hint	user-invocable
create-capability	Create a new capability (skill, agent, or a cohesive set) for the architecture repository. Use when creating new skills, agents, extending AI workflows, or when user says /create-capability.	claude-haiku-4-5	<description>	true

Create Capability

@~/.claude/skills/capability-writing/SKILL.md

Create new capabilities following latest Anthropic best practices (progressive disclosure, script bundling, Haiku-first).

Process

1. Understand the capability: Analyze "$1" to understand what the user wants to build

   • What domain or workflow does this cover?
   • What user need does it address?
   • What existing capabilities might overlap?

2. Determine components needed: Based on the description, recommend which components:

   Pattern	When to Use
   Skill only (background)	Knowledge to apply automatically (reused across other skills)
   Skill only (user-invocable)	User-invoked workflow
   Skill + Agent	Workflow with isolated worker for complex subtasks
   Full set	New domain expertise + workflow + isolated work

   Present recommendation with reasoning:

   ## Recommended Components for: $1
   
   Based on your description, I recommend:
   - **Skill**: `name` - [why this knowledge is needed]
   - **Agent**: `name` - [why isolation/specialization is needed] (optional)
   
   Reasoning: [explain why this combination fits the need]
   

3. Analyze complexity (NEW): For each skill, determine structure needed:

   Ask these questions:

   a) Expected size: Will this skill be >300 lines?

   • If NO → Simple structure (just SKILL.md)
   • If YES → Suggest progressive disclosure

   b) Error-prone operations: Are there complex bash operations?

   • Check for: PR creation, worktree management, complex git operations
   • If YES → Suggest bundling scripts

   c) Degree of freedom: What instruction style is appropriate?

   • Multiple valid approaches → Text instructions (high freedom)
   • Preferred pattern with variation → Templates (medium freedom)
   • Fragile operations, exact sequence → Scripts (low freedom)

   Present structure recommendation:

   ## Recommended Structure
   
   Based on complexity analysis:
   - **Size**: [Simple | Progressive disclosure]
   - **Scripts**: [None | Bundle error-prone operations]
   - **Degrees of freedom**: [High | Medium | Low]
   
   Structure:
   [Show folder structure diagram]
   

4. Gather information: For each recommended component, ask:

   For all components:

   • Name (kebab-case, descriptive)
   • Description (one-line summary including trigger conditions)

   For Skills:

   • What domain/knowledge does this cover?
   • What are the key concepts to teach?
   • What patterns or templates should it include?
   • Is it user-invocable (workflow) or background (reference)?

   For Agents:

   • What specialized role does this fill?
   • What skills does it need?
   • Should it be read-only (no Edit/Write)?

5. Select appropriate models (UPDATED):

   Default to Haiku, upgrade only if needed:

   Model	Use For	Cost vs Haiku
   haiku	Most skills and agents (DEFAULT)	Baseline
   sonnet	When Haiku would struggle (<80% success rate)	12x more expensive
   opus	Deep reasoning, architectural analysis	60x more expensive

   Ask for justification if not Haiku:

   • "This looks like a simple workflow. Should we try Haiku first?"
   • "Does this require complex reasoning that Haiku can't handle?"

   For each component, recommend Haiku unless there's clear reasoning for Sonnet/Opus.

6. Generate files: Create content using templates from capability-writing skill

   Structure options:

   a) Simple skill (most common):

   skills/skill-name/
   └── SKILL.md
   

   b) Progressive disclosure (for large skills):

   skills/skill-name/
   ├── SKILL.md (~200-300 lines)
   ├── reference/
   │   ├── detailed-guide.md
   │   └── api-reference.md
   └── examples/
       └── usage-examples.md
   

   c) With bundled scripts (for error-prone operations):

   skills/skill-name/
   ├── SKILL.md
   ├── reference/
   │   └── error-handling.md
   └── scripts/
       ├── validate.sh
       └── process.sh
   

   Ensure proper inter-references:

   • User-invocable skill references background skills via @~/.claude/skills/name/SKILL.md
   • Agent lists skills in skills: frontmatter (names only, not paths)
   • User-invocable skill spawns agent via Task tool if agent is part of the set
   • Scripts are called with ./scripts/script-name.sh in SKILL.md

7. Present for approval: Show all generated files with their full content:

   ## Generated Files
   
   ### skills/name/SKILL.md
   [full content]
   
   ### skills/name/scripts/helper.sh (if applicable)
   [full content]
   
   ### agents/name/AGENT.md (if applicable)
   [full content]
   
   Ready to create these files?
   

8. Create files in correct locations after approval:

   • Create directories if needed
   • skills/<name>/SKILL.md
   • skills/<name>/scripts/ (if scripts recommended)
   • skills/<name>/reference/ (if progressive disclosure)
   • agents/<name>/AGENT.md (if agent recommended)

9. Report success:

   ## Capability Created: name
   
   Files created:
   - skills/name/SKILL.md
   - skills/name/scripts/helper.sh (if applicable)
   - agents/name/AGENT.md (if applicable)
   
   

Guidelines (UPDATED)

• Follow all conventions from capability-writing skill
• Default to Haiku for all new skills/agents (12x cheaper, 2-5x faster)
• Bundle scripts for error-prone bash operations
• Use progressive disclosure for skills >500 lines
• Reference existing skills rather than duplicating knowledge
• Keep components focused - split if scope is too broad
• User-invocable skills should have approval checkpoints
• Skills should have descriptive description fields with trigger conditions
• Be concise - assume Claude knows basics

Output Style

Be concise and direct:

• No preambles ("I'll help you...")
• No sign-offs ("Let me know...")
• Show structure diagrams clearly
• Use tables for comparisons
• One decision per section