Creating Custom Skills

Advanced Guide · 15 min read

✓Based on source code analysis

What are Skills?

Skills are reusable workflows encapsulated as Markdown files with YAML frontmatter. They serve as "operation manuals" for Claude, guiding behavior for specific tasks.

Minimal Skill Example

---
description: Code review assistant
when_to_use: When user requests code review
allowed-tools: Read, Grep, Glob
---
# Code Review Guidelines

1. Check code style consistency
2. Look for security vulnerabilities
3. Verify error handling
4. Suggest performance improvements

Frontmatter Fields (13+ Fields)

Core Fields

  • description - Skill description for model triggering
  • when_to_use - Trigger condition description
  • allowed-tools - Tool whitelist
  • arguments - Parameter definitions with $arg_name variables

Execution Control

  • context - Execution mode: inline (default) or fork
  • agent - Specify agent type
  • effort - Effort level (low/medium/high)
  • model - Override model (sonnet/haiku/opus)

Security & Permissions

  • disable-model-invocation - Disable auto model calling
  • user-invocable - Can user call via /skill command
  • hooks - Pre/post execution scripts
  • paths - Path restrictions

Two Execution Modes

Inline Mode (Default)

Skill content injected directly into current conversation. Model continues in same context.

Best for: Lightweight guidance (code style, writing guidelines)

Fork Mode

Creates isolated sub-agent with independent token budget and context window.

Best for: Heavy tasks (code generation, multi-step workflows)

Loading Priority

  1. bundled - Built-in skills (29 skills)
  2. managed - Enterprise managed (~/.config/.claude/skills)
  3. user - User level (~/.claude/skills)
  4. project - Project level (.claude/skills)
  5. plugin - Plugin-carried
  6. mcp - MCP server exposed

Variable Substitution

  • $arg_name - User-passed parameters
  • ${CLAUDE_SKILL_DIR} - Skill file directory absolute path
  • ${CLAUDE_SESSION_ID} - Current session ID
  • !`command` - Inline shell execution (local skills only)

29 Built-in Skills

  • commit - Smart Git commit
  • create-pr - Create Pull Request
  • review-pr - PR code review
  • security-review - Security audit
  • verify - Code verification
  • skillify - Convert session to skill
  • debug - Debug assistant
  • test - Test generation
  • doc - Documentation generation

Skill Security Model

Safe attributes (auto-allowed): name, description, version, when_to_use, arguments, paths

Unsafe attributes (require authorization): allowed-tools, hooks, context: fork, model, effort

💡 Pro Tip: Use /skillify to automatically create skills from current sessions!