Vadym/obsidian
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
obsidian/wiki/claude-code/skills.md
Vadym Samoilenko 40845b7e50 vault backup: 2026-04-17 12:46:21
2026-04-17 12:46:21 +01:00

7.2 KiB
Raw Blame History

title aliases tags sources created updated
Claude Code Skills
skills
custom-skills
slash-commands
claude-skills
claude-code
skills
customization
automation
slash-commands
raw/Extend Claude with skills.md
2026-04-17 2026-04-17

Claude Code Skills

Skills extend Claude's capabilities via a SKILL.md file. Claude loads them automatically when relevant, or you invoke directly with /skill-name. They supersede the old .claude/commands/ system — commands still work, but skills add more features.

When to Create a Skill

  • You keep pasting the same playbook or checklist into chat
  • A section of CLAUDE.md has grown into a procedure rather than a fact
  • Skill body only loads when used → long reference material costs nothing at rest

Where Skills Live

Scope Path Applies to
Enterprise Managed settings All org users
Personal ~/.claude/skills/<name>/SKILL.md All your projects
Project .claude/skills/<name>/SKILL.md This project only
Plugin <plugin>/skills/<name>/SKILL.md Where plugin is enabled
  • Priority order: enterprise > personal > project; plugin skills use plugin-name:skill-name namespace
  • Live reload: edits take effect within the session (no restart needed unless adding a brand-new directory)
  • Monorepo: nested .claude/skills/ in subdirectories are auto-discovered

File Structure

my-skill/
├── SKILL.md           # Main instructions (required, keep < 500 lines)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output
└── scripts/
    └── helper.py      # Script Claude can execute

Reference supporting files from SKILL.md so Claude knows when to load them.

Frontmatter Reference

All fields optional; description is strongly recommended.

Field Description
name Display name (lowercase, hyphens, max 64 chars). Defaults to directory name.
description What the skill does; Claude uses this to decide when to apply it. Front-load key use case.
when_to_use Extra trigger phrases; appended to description in skill listing.
argument-hint Autocomplete hint, e.g. [issue-number].
disable-model-invocation true = only you can invoke (not auto-triggered by Claude).
user-invocable false = hidden from / menu; Claude-only.
allowed-tools Tools pre-approved for this skill (no per-use prompt). Space-separated or YAML list.
model Override model for this skill.
effort Override effort level: low, medium, high, xhigh, max.
context fork = run in isolated subagent.
agent Which subagent to use when context: fork (e.g. Explore, Plan, general-purpose).
hooks Lifecycle hooks scoped to this skill.
paths Glob patterns; skill auto-activates only when working with matching files.
shell Shell for inline ! commands: bash (default) or powershell.

Invocation Control

Frontmatter You invoke Claude invokes In context
(default) Yes Yes Description always; full body on invoke
disable-model-invocation: true Yes No Not in context; full body on your invoke
user-invocable: false No Yes Description always; full body on invoke

Use disable-model-invocation: true for side-effect workflows (/deploy, /commit, /send-slack-message).

Passing Arguments

  • $ARGUMENTS — full argument string
  • $ARGUMENTS[N] or $N — positional (0-based); wrap multi-word in quotes
  • If $ARGUMENTS absent in content, appended as ARGUMENTS: <value>
---
name: fix-issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.

Dynamic Context Injection

!`command` runs shell commands before Claude sees the prompt — output replaces the placeholder.

---
name: pr-summary
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

Multi-line variant: fenced block opened with ```!.

Disable globally: "disableSkillShellExecution": true in settings.

Running in a Subagent

context: fork isolates the skill in a subagent — no access to conversation history.

---
name: deep-research
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...
Approach System prompt Task
Skill + context: fork From agent type SKILL.md content
Subagent + skills field Subagent markdown Claude's delegation message

Bundled Skills

Available in every session: /simplify, /batch, /debug, /loop, /claude-api. Prompt-based (not fixed logic). Invoke with /skill-name.

Skill Content Lifecycle

  • On invocation: rendered SKILL.md enters conversation as a message, persists for the session
  • Auto-compaction: most recent invocation re-attached after summary (first 5,000 tokens per skill, 25,000 combined budget across all skills)
  • If a skill stops influencing behavior → re-invoke after compaction, or strengthen description

Pre-Approving Tools

allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)

This grants those tools without per-use approval. It does NOT restrict other tools.

Controlling Claude's Skill Access

# Deny all skills
Skill

# Allow specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skill
Skill(deploy *)

Syntax: Skill(name) exact match, Skill(name *) prefix match.

Sharing Skills

  • Project: commit .claude/skills/ to version control
  • Plugin: add skills/ directory in your wiki/claude-code/create-plugins
  • Org-wide: deploy via managed settings

Troubleshooting

Problem Fix
Skill not triggering Check description keywords; verify with "What skills are available?"; invoke directly
Skill triggers too often Make description more specific; add disable-model-invocation: true
Description cut short Trim description/when_to_use; front-load key use case; or set SLASH_COMMAND_TOOL_CHAR_BUDGET

Key Takeaways

  • Skills = lazy-loaded playbooks that cost nothing until invoked
  • Store globally (~/.claude/skills/) or per-project (.claude/skills/)
  • disable-model-invocation: true for side-effect commands you want to control manually
  • user-invocable: false for background knowledge Claude should load automatically
  • context: fork to run skill in an isolated subagent with its own context
  • Dynamic shell injection (!`cmd`) pre-populates prompts with live data before Claude sees them
  • allowed-tools pre-approves specific tools so Claude doesn't prompt during the skill
  • After auto-compaction, re-invoke large skills to restore full content

Related

Sources

  • raw/Extend Claude with skills.md — official Claude Code skills documentation