Claude Code Skills Skill

Claude Code Skills

Steps

Load the outfitter:skills-dev skill
Consider the Claude Code-specific features that extend the base specification within this skill

Frontmatter Extensions

Claude Code extends the base Agent Skills frontmatter:

| Field | Type | Description | |-------|------|-------------| | allowed-tools | string | Space-separated tools that run without permission prompts | | user-invocable | boolean | Default true. Set false to prevent /skill-name access | | disable-model-invocation | boolean | Prevents auto-activation; requires manual Skill tool invocation | | context | string | inherit (default) or fork for isolated subagent execution | | agent | string | Agent for context: fork (e.g., Explore, outfitter:analyst) | | model | string | Override model: haiku, sonnet, or opus | | hooks | object | Lifecycle hooks: on-activate, on-complete | | argument-hint | string | Hint shown after /skill-name (e.g., [file path]) |

Example

---
name: code-review
version: 1.0.0
description: Reviews code for bugs, security, and best practices. Use when reviewing PRs, auditing code, or before merging.
allowed-tools: Read Grep Glob Bash(git diff *)
argument-hint: [file or directory]
model: sonnet
---

Tool Restrictions

Use allowed-tools to specify which tools run without permission prompts.

Syntax

# Space-separated list
allowed-tools: Read Grep Glob

# With Bash patterns
allowed-tools: Read Write Bash(git *) Bash(npm run *)

# MCP tools (double underscore format)
allowed-tools: Read mcp__linear__create_issue mcp__memory__store

Bash Pattern Syntax

| Pattern | Meaning | Example | |---------|---------|---------| | Bash(git *) | All git commands | git status, git commit | | Bash(git add:*) | Specific subcommand | git add ., git add file.ts | | Bash(npm run *:*) | Nested patterns | npm run test:unit |

Common Patterns

# Read-only analysis
allowed-tools: Read Grep Glob

# File modifications
allowed-tools: Read Edit Write

# Git operations
allowed-tools: Read Write Bash(git *)

# Testing workflows
allowed-tools: Read Write Bash(bun test:*) Bash(npm test:*)

# Full development
allowed-tools: Read Edit Write Bash(git *) Bash(bun *) Bash(npm *)

Tool Names (Case-Sensitive)

| Tool | Purpose | |------|---------| | Read | Read files | | Write | Write new files | | Edit | Edit existing files | | Grep | Search file contents | | Glob | Find files by pattern | | Bash | Execute bash commands | | WebFetch | Fetch web content | | WebSearch | Search the web |

User Invocable Skills

Skills are callable as /skill-name by default. Use user-invocable: false for auto-activate-only skills.

---
name: code-review
description: Reviews code for bugs and best practices...
argument-hint: [file or PR number]
---

Users invoke with /code-review src/auth.ts or wait for auto-activation.

Disabling Slash Command Access

---
name: internal-validator
description: Validates internal state when specific patterns are detected...
user-invocable: false
---

Arguments

The argument-hint field provides context in the command picker:

argument-hint: [error message or bug description]

Arguments available via $ARGUMENTS in skill body.

String Substitutions

| Pattern | Replaced With | |---------|---------------| | $ARGUMENTS | User input after /skill-name | | ${CLAUDE_SESSION_ID} | Current session identifier | | ${CLAUDE_PLUGIN_ROOT} | Path to the plugin root directory |

Example

# Debug Skill

Investigating: $ARGUMENTS

Session: ${CLAUDE_SESSION_ID}

Use the debugging script:
${CLAUDE_PLUGIN_ROOT}/scripts/debug-helper.ts

Dynamic Context Injection

Use backtick-command syntax to inject dynamic content:

## Current Git Status

`git status`

## Recent Changes

`git log --oneline -5`

Commands execute when Claude loads the skill; output replaces the syntax.

Use cases: Current branch state, environment info, dynamic config, recent history.

Context Modes

The context field controls execution environment.

inherit (default)

Skill runs in main conversation context with access to history and prior tool results.

context: inherit

fork

Skill runs in isolated subagent context. Useful for:

Preventing context pollution
Parallel execution
Specialized processing that shouldn't affect main conversation

context: fork
agent: outfitter:analyst
model: haiku

When context: fork, specify:

agent: Which agent handles the fork
model: Override model for forked context

In Steps sections: Use "delegate by loading" language for delegated skills (they run agents, not load instructions):

3. Delegate by loading the `outfitter:security-audit` skill for vulnerability scan

See context-modes.md for patterns.

Testing

claude --debug

Debug output shows:

Loaded skill: skill-name from path — Skill discovered
Error loading skill: reason — Loading failed
Considering skill: skill-name — Activation evaluated
Skill allowed-tools: [list] — Tool restrictions applied

Testing Process

Verify loading: claude --debug and check for load messages
Test discovery: Ask something that should trigger the skill
Verify tool restrictions: Confirm permitted tools run without prompts
Test with real data: Run actual workflows

Force Skill Reload

Skills are cached per session. To reload after changes:

/clear

Troubleshooting

Skill Not Loading

Check file location:

# Personal skills
ls ~/.claude/skills/my-skill/SKILL.md

# Project skills
ls .claude/skills/my-skill/SKILL.md

# Plugin skills
ls <plugin-path>/skills/my-skill/SKILL.md

Validate YAML frontmatter:

# Check for tabs (YAML requires spaces)
grep -P "\t" SKILL.md

Skill Not Activating

Improve description specificity:

# Before (too vague)
description: Helps with files

# After (specific with triggers)
description: Parse and validate JSON files including schema validation. Use when working with JSON data, .json files, or configuration files.

Add trigger keywords users naturally say: file types (.pdf, .json), actions (parse, validate), domains (API, database).

Tool Permission Errors

Tool names are case-sensitive:

# Correct
allowed-tools: Read Grep Glob

# Wrong
allowed-tools: read grep glob

Bash patterns need wildcards:

# Correct
allowed-tools: Bash(git *)

# Wrong (matches nothing)
allowed-tools: Bash(git)

MCP tools use double underscores:

# Correct
allowed-tools: mcp__memory__store

# Wrong
allowed-tools: mcp_memory_store

Integration Patterns

With Commands

Skills activate automatically when commands need their expertise:

Command (.claude/commands/analyze-pdf.md):

---
description: Analyze PDF file
---

Analyze this PDF file: $ARGUMENTS

Use the PDF processing skill for extraction and analysis.

With Hooks

Hooks can suggest skill usage:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)|Edit(*.ts)",
        "hooks": [{ "type": "command", "command": "echo 'Consider typescript-linter skill'" }]
      }
    ]
  }
}

Using Skill Tool

Load skills programmatically:

Use the Skill tool to invoke the pdf-processor skill

Useful for forcing activation, chaining skills, loading for agents.

See integration.md for advanced patterns.

Master-Clone Architecture

For orchestrating specialized work with context isolation:

Master Agent: Coordinates, maintains conversation context, delegates specialized tasks Clone Agents: Isolated context, loads specific skill, returns focused output

User request
   |
Master agent decides: needs security analysis
   |
Launch clone agent with security-audit skill
   |
Clone returns findings (only findings in main context)
   |
Master synthesizes and continues

Implementation

---
name: security-audit
context: fork
agent: outfitter:reviewer
model: sonnet
---

Or via Task tool:

{
  "description": "Security audit of auth module",
  "prompt": "Review src/auth/ for vulnerabilities using security-audit skill",
  "subagent_type": "outfitter:reviewer",
  "run_in_background": true
}

References

| Reference | Content | |-----------|---------| | context-modes.md | Fork vs inherit patterns | | integration.md | Commands, hooks, MCP integration | | performance.md | Token impact, optimization |

Agent Skills: Claude Code Skills

Install this agent skill to your local

Skill Files