Claude Code Skills

Steps

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

Frontmatter Extensions

Claude Code extends the base Agent Skills frontmatter:

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

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)

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

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

1. Verify loading: claude --debug and check for load messages
2. Test discovery: Ask something that should trigger the skill
3. Verify tool restrictions: Confirm permitted tools run without prompts
4. 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