Creating extensions

Creates slash commands, subagents/workflows, or agent skills for Claude Code following the decision framework and best practices.

What you should do

When invoked, guide the user through creating the right type of extension:

1. Understand the requirement - Gather information about what the user wants to create:

   • What task or capability do they want to add?
   • How complex is the workflow?
   • Should it be manually triggered or automatically discovered?
   • Does it generate extensive output or "chatter"?
   • Does it need supporting files, scripts, or templates?
   • Is this for personal use or team-wide adoption?

2. Evaluate using the framework - Apply the Claude request type framework criteria:

   • Initiation: User-only (manual) or Discoverable (automatic)?
   • Context needs: Full conversation history or summary context?
   • Verbosity: Manageable output or extensive (pollutes main thread)?
   • Specialization: General purpose or needs specialist persona?
   • Resource use: Standard (instructions only) or heavy (requires references/scripts)?

3. Determine the extension type based on evaluation profile:

   Slash Command when:

   • User-only initiation (manual trigger required)
   • Full context needed
   • Manageable output
   • Generalist (no special persona)
   • Standard resources (single file sufficient)

   Subagent/Workflow when:

   • Discoverable (automatic invocation)
   • Summary context (context isolation needed)
   • Extensive verbosity (PRIMARY INDICATOR - pollutes main thread)
   • Specialist persona (PRIMARY INDICATOR - needs distinct system prompt)
   • Standard resources

   Agent Skill when:

   • Discoverable (automatic invocation)
   • Any context needs
   • Any verbosity level
   • Any specialization level
   • Heavy resource use (PRIMARY INDICATOR - requires multiple files, scripts, templates, or references)

4. Determine the scope and format - Critical: Different formats for different scopes:

   Project-specific (Claude Code format):

   • Project-level: .claude/commands/, .claude/subagents/, .claude/skills/ (shared with team)
   • Personal-level: ~/.claude/commands/, ~/.claude/subagents/, ~/.claude/skills/ (personal only)
   • Uses Claude Code format (minimal frontmatter, platform-specific)

   Agent-playbook global (Multi-platform format):

   • Repository: core/workflows/, core/skills/ in agent-playbook repo
   • Uses extended frontmatter with platforms, status, category, tags
   • Gets distributed to multiple platforms via build process
   • Ask user to check if this is agent-playbook repo before using this format

   Ask the user which scope, then use the appropriate format.

5. Generate the extension - Use format based on scope (see reference files for complete examples):

   Project-specific (Claude Code format):

   • Minimal frontmatter
   • Platform-specific conventions
   • See COMMANDS.md, WORKFLOWS.md, SKILLS.md for Claude Code format

   Agent-playbook global (Multi-platform format):

   • Extended frontmatter with platforms: ["claude-code"], status, category, tags
   • Platform-agnostic content
   • Build process transforms for each platform
   • Only use if user confirms this is agent-playbook repository

6. Validate and test - Ensure the extension follows best practices:

   • Correct file location
   • Proper frontmatter format
   • Clear, actionable instructions
   • Follows naming conventions
   • Includes appropriate metadata

Decision framework reference

Use this quick reference to determine extension type:

Primary indicators (strongest signals)

• Extensive verbosity → Subagent (context isolation required)
• Specialist persona → Subagent (distinct system prompt needed)
• Heavy resources → Skill (multiple files, scripts, templates)

Supporting indicators

• User-only initiation → Slash command (manual trigger)
• Discoverable initiation → Subagent or Skill (automatic)
• Single file sufficient → Slash command (simplest)
• Context pollution → Subagent (isolate the chatter)

File naming conventions

Slash commands: <area>[-<subarea>]-<verb>[-<object>].md

• Examples: git-review.md, docs-format.md, test-run.md

Subagents/workflows: <area>[-<subarea>]-<verb>[-<object>].md

• Examples: repo-code-quality-review.md, git-commit.md, docs-organize.md

Agent skills: <area>[-<subarea>]-<verb>[-<object>]/SKILL.md

• Directory name uses kebab-case
• Examples: creating-agent-skills/, tests-run/, gh-project-setup/

All names use:

• Kebab-case (lowercase with hyphens)
• American English spelling
• Imperative verbs for workflows
• Gerund form for skill names

Best practices by type

Slash commands

• Keep it simple (one file only)
• Use clear argument hints
• Specify allowed-tools if restrictive
• Write clear, direct instructions

For detailed slash command best practices, see COMMANDS.md.

Subagents/workflows

• Define clear persona and specialization
• Include step-by-step invocation workflow
• Specify model if non-default needed
• Restrict tools to minimum required
• USE PROACTIVELY statement in description

For detailed workflow best practices, see WORKFLOWS.md.

Agent skills

• Use gerund form naming ("Managing X")
• Write third-person descriptions
• Include specific trigger keywords
• Keep SKILL.md under 500 lines
• Use progressive disclosure for details
• Test discovery with real scenarios

For detailed skill best practices, see SKILLS.md.

Example interactions

User request: "Create a command to run my tests"

• Analysis: User-only, manageable output, single purpose → Slash command
• Scope: Ask if project or personal
• Location: .claude/commands/test-run.md (project) or ~/.claude/commands/test-run.md (personal)
• Format: Claude Code format (minimal frontmatter)

User request: "I need something that does a deep code quality audit"

• Analysis: Extensive verbosity (would pollute main thread), specialist persona needed → Subagent
• Scope: Ask if project-specific or global (agent-playbook)
• Location: .claude/subagents/code-quality-audit.md (project) or core/workflows/code-quality-audit.md (agent-playbook)
• Format: Claude Code format for project, multi-platform for agent-playbook

User request: "Create a workflow for managing GitHub Projects with our team conventions"

• Analysis: Heavy resources (needs field IDs, templates, examples), team-wide → Skill
• Scope: Ask if project-specific or global (agent-playbook)
• Location: .claude/skills/gh-project-manage/SKILL.md (project) or core/skills/gh-project-manage/SKILL.md (agent-playbook)
• Format: Claude Code format for project, multi-platform for agent-playbook

Output format

When creating an extension, provide:

1. Analysis summary:

   • Extension type chosen and why
   • Scope (project vs personal)
   • File location

2. Complete file content with proper formatting

3. Next steps:

   • How to test or use it
   • Any additional setup needed
   • Build or distribution steps if applicable

Format selection guide

CRITICAL: Use the correct format for the scope.

For project-specific extensions

Location: .claude/ directories in any project Format: Claude Code format (minimal frontmatter) When: Extension is specific to this project or personal workflow

Example workflow frontmatter:

---
name: workflow-name
description: Brief description. USE PROACTIVELY when <trigger>.
persona: You are a <role> specializing in <specialization>.
tools: Bash, Read, Grep, Glob
model: haiku
---

For agent-playbook global extensions

Location: core/workflows/, core/skills/ in agent-playbook repo ONLY Format: Multi-platform format (extended frontmatter) When: Extension should be available globally across all projects and platforms

Example workflow frontmatter:

---
name: workflow-name
descriptive-title: Human-readable title
description: Brief description. USE PROACTIVELY when <trigger>.
persona: You are a <role> specializing in <specialization>.
tools: Bash, Read, Grep, Glob
model: haiku
---

Check first: Ask "Is this the agent-playbook repository?" before using multi-platform format.

After creation (agent-playbook only)

If created in core/:

1. Run npm run build:claude to generate distribution files
2. Run npm run dist:local to deploy to ~/.claude/

Remember

• Primary indicators (verbosity, specialization, resources) are strongest signals
• Context pollution is the key heuristic for subagents
• Automatic discovery is the key benefit of skills over commands
• Simplicity favors commands over more complex types
• When uncertain, ask the user clarifying questions
• Default to project-level unless clearly personal
• Always follow repository conventions and templates

Reference documentation

For detailed best practices by type:

• COMMANDS.md - Complete slash command reference with patterns and examples
• WORKFLOWS.md - Comprehensive subagent/workflow guide with system prompt patterns
• SKILLS.md - Detailed skill creation guide with progressive disclosure strategies

Official documentation

For complete details:

• Request type framework: docs/type-decision-framework.md
• Extension architecture: docs/claude-code-extension-architecture.md
• Slash commands: https://code.claude.com/docs/en/slash-commands
• Agent skills: https://code.claude.com/docs/en/skills
• Subagents: https://code.claude.com/docs/en/sub-agents