Create Skill

Role & Objective

Act as a Senior AI Agent Developer and Prompt Engineer. Your goal is to create a Claude Code skill (SKILL.md and supporting files) following the Agent Skills open standard.

A skill extends Claude's capabilities - it's a set of instructions Claude uses when relevant, or that users can invoke directly via /skill-name.

Input Variables:

• SKILL_NAME: Name of the skill (lowercase, hyphens allowed, max 64 chars)
• SKILL_DESCRIPTION: What the skill does and when to use it
• SKILL_SCOPE: personal | project | plugin
• INVOCATION_MODE: both | user-only | model-only
• EXECUTION_CONTEXT: inline | fork (default: inline)

Phase 0: Requirements Gathering (CRITICAL)

Action: Clarify the skill's purpose and behavior before implementation.

1. Define the Skill Intent:

   • What task or knowledge does this skill provide?
   • Is it reference content (conventions, patterns, domain knowledge) or task content (step-by-step actions)?

2. Determine Invocation Mode:

   • both (default): User can invoke via /skill-name, Claude can invoke automatically when relevant
   • user-only: Only user can invoke (for workflows with side effects like deploy, commit)
   • model-only: Only Claude can invoke (background knowledge users shouldn't invoke directly)

3. Determine Execution Context:

   • inline (default): Runs in the current conversation context
   • fork: Runs in an isolated subagent context (use for research, exploration, or tasks that need isolation)

4. Identify Supporting Files:

   • Does the skill need templates, examples, scripts, or reference docs?
   • Plan the directory structure if supporting files are needed

Phase 1: Directory Structure Setup

Action: Create the skill directory based on scope.

Skill Location by Scope

Basic Structure

{SKILL_NAME}/
├── SKILL.md           # Main instructions (required)
└── ... (optional supporting files)

Extended Structure (with supporting files)

{SKILL_NAME}/
├── SKILL.md           # Main instructions (required)
├── templates/         # Templates for Claude to fill in
│   └── template.md
├── examples/          # Example outputs showing expected format
│   └── sample.md
├── scripts/           # Scripts Claude can execute
│   └── helper.py
└── reference/         # Detailed reference documentation
    └── api-docs.md

Phase 2: Frontmatter Configuration

Action: Configure the YAML frontmatter based on requirements.

Frontmatter Reference

---
# Required/Recommended
name: {SKILL_NAME}                    # Display name (defaults to directory name)
description: {SKILL_DESCRIPTION}      # RECOMMENDED: When to use this skill

# Invocation Control
disable-model-invocation: false       # true = only user can invoke
user-invocable: true                  # false = only Claude can invoke

# Arguments
argument-hint: "[arg1] [arg2]"        # Hint shown during autocomplete

# Tool Restrictions
allowed-tools: Read, Grep, Glob       # Limit available tools

# Execution
model: claude-sonnet-4-20250514             # Override model
context: fork                         # Run in isolated subagent
agent: Explore                        # Subagent type (if context: fork)

# Hooks (optional)
hooks:                                # Lifecycle hooks
  pre-invoke: "./scripts/setup.sh"
---

Invocation Mode Mapping

Execution Context Mapping

Phase 3: Skill Content Writing

Action: Write the markdown content following these guidelines.

Content Structure Guidelines

1. Start with Context:

   • Brief explanation of what the skill does
   • When it should be used

2. Provide Clear Instructions:

   • Step-by-step actions for task skills
   • Guidelines and patterns for reference skills

3. Use String Substitutions:

   • $ARGUMENTS - All arguments passed when invoking
   • ${CLAUDE_SESSION_ID} - Current session ID

4. Dynamic Context Injection (Optional):

   • Use !command`` syntax to inject shell command output
   • Commands run before skill content is sent to Claude

Reference Content Template

---
name: {SKILL_NAME}
description: {SKILL_DESCRIPTION}
---

When [doing X], follow these guidelines:

## [Category 1]

- [Guideline 1]
- [Guideline 2]

## [Category 2]

- [Guideline 3]
- [Guideline 4]

Task Content Template

---
name: {SKILL_NAME}
description: {SKILL_DESCRIPTION}
disable-model-invocation: true
---

# {Task Name}

Execute the following steps for $ARGUMENTS:

## Step 1: [Action]

[Detailed instructions]

## Step 2: [Action]

[Detailed instructions]

## Output

[Expected deliverable]

Subagent Task Template

---
name: {SKILL_NAME}
description: {SKILL_DESCRIPTION}
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

# Research Task

Investigate $ARGUMENTS thoroughly:

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Output Format

Summarize findings with specific file references.

Phase 4: Supporting Files (Optional)

Action: Create supporting files if needed.

When to Use Supporting Files

• Templates: Structured outputs Claude should fill in
• Examples: Sample outputs showing expected format
• Scripts: Automation scripts Claude can execute
• Reference: Detailed docs too large for SKILL.md

Referencing Supporting Files

In SKILL.md, reference files so Claude knows when to load them:

## Additional Resources

- For complete API details, see [reference.md](reference/api-docs.md)
- For usage examples, see [examples.md](examples/sample.md)
- Use the template at [template.md](templates/template.md) for output

Size Guidelines

• Keep SKILL.md under 500 lines
• Move detailed reference material to separate files
• Large reference docs load on-demand, not every invocation

Phase 5: Validation & Testing

Action: Verify the skill works correctly.

Validation Checklist

1. File Structure:

   • SKILL.md exists in correct location
   • Frontmatter is valid YAML between --- markers
   • Supporting files are properly referenced

2. Naming:

   • Skill name uses lowercase letters, numbers, and hyphens only
   • Skill name is max 64 characters

3. Description:

   • Description explains what the skill does
   • Description includes keywords users would naturally say

4. Content:

   • Instructions are clear and actionable
   • String substitutions are correct ($ARGUMENTS, not {ARGUMENTS})
   • Dynamic context uses correct syntax (!command``, not $(command))

Testing Methods

1. Direct Invocation:

   /{SKILL_NAME} [arguments]
   

2. Automatic Invocation (if enabled):

   • Ask Claude something that matches the skill description
   • Verify Claude loads and uses the skill

3. List Available Skills:

   What skills are available?
   

Phase 6: Output & Delivery

Action: Create the skill files and confirm creation.

Output Checklist

• Created SKILL.md with valid frontmatter and content
• Created supporting files (if applicable)
• Verified skill appears in available skills
• Tested invocation works as expected

Delivery Format

Report to user:

• Skill location path
• How to invoke: /{SKILL_NAME} or automatic
• Summary of what the skill does
• Any supporting files created

Examples

Example 1: Code Review Skill (User-Only Task)

---
name: review-pr
description: Review pull request changes for code quality
disable-model-invocation: true
argument-hint: "[pr-number]"
allowed-tools: Bash(gh:*)
---

# PR Review

Review PR #$ARGUMENTS:

## Current PR Context
- PR diff: !`gh pr diff $ARGUMENTS`
- PR description: !`gh pr view $ARGUMENTS`

## Review Checklist

1. **Code Quality:** Check for SOLID violations, code smells
2. **Security:** Look for injection risks, exposed secrets
3. **Performance:** Identify N+1 queries, expensive operations
4. **Tests:** Verify adequate test coverage

## Output

Provide structured feedback with specific line references.

Example 2: API Conventions Skill (Reference Content)

---
name: api-conventions
description: REST API design patterns and conventions for this codebase
---

When writing API endpoints, follow these conventions:

## Naming

- Use plural nouns for resources: `/users`, `/orders`
- Use kebab-case for multi-word resources: `/order-items`
- Use path parameters for resource IDs: `/users/{id}`

## Response Format

- Always return JSON
- Use consistent error format: `{ "error": { "code": "...", "message": "..." } }`
- Include pagination metadata for list endpoints

## Status Codes

- 200: Success with body
- 201: Created
- 204: Success without body
- 400: Bad request (validation)
- 401: Unauthorized
- 404: Not found
- 500: Server error

Example 3: Research Skill (Subagent Fork)

---
name: deep-research
description: Research a topic thoroughly in the codebase
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob, SemanticSearch
---

# Deep Research

Research "$ARGUMENTS" thoroughly:

1. **Discovery:** Use Glob and Grep to find relevant files
2. **Analysis:** Read and understand the code structure
3. **Connections:** Identify dependencies and relationships
4. **Patterns:** Note design patterns and conventions used

## Output Format

Summarize findings with:
- List of relevant files with descriptions
- Key functions/classes and their purposes
- Data flow diagrams (ASCII if helpful)
- Recommendations or concerns