Skill Invocation and Configuration

Invoking skills

Skills activate through two mechanisms: explicit invocation and automatic activation. Knowing which applies, and how to control the behavior, makes the difference between skills that integrate smoothly and skills that get in the way.

Explicit invocation

Type /skill-name in Claude Code to invoke a skill directly. Arguments follow the skill name:

# Basic invocation
/code-review

# With arguments
/fix-issue 1234

# Multiple arguments
/migrate-component SearchBar React Vue

Codex uses different syntax. Skills invoke with $skill-name:

# Codex skill invocation
$code-review

# With arguments
$fix-issue 1234

When writing documentation for both platforms, note this syntax difference.

Automatic activation

By default, Claude can invoke skills without explicit commands. At session startup, the agent reads skill descriptions and indexes available capabilities. When a task matches a skill's description, the agent loads and executes it.

How well this works depends entirely on the description field. "Helps with code" matches everything. "Generates commit messages following conventional commits specification" matches the right tasks.

---
name: commit-message
description: Generates commit messages following conventional commits specification when staging code for commit or when explicitly asked to write commit messages
---

The description does double duty: it tells the agent when to activate, and it documents the skill for humans reading the skill file.

Controlling invocation behavior

Three frontmatter fields control how skills can be invoked:

For skills with side effects (deployments, commits, database migrations), set disable-model-invocation: true. Otherwise the agent might accidentally run a deployment because you mentioned the word "deploy" in conversation.

---
name: deploy-production
description: Deploy current branch to production environment
disable-model-invocation: true
---

The skill only runs when someone types /deploy-production. No amount of discussion about deployments triggers it accidentally.

YAML frontmatter reference

Every SKILL.md file starts with YAML frontmatter enclosed in triple dashes. The frontmatter configures behavior, resource access, and agent integration.

Core fields

---
name: skill-name
description: What the skill does and when to use it
argument-hint: [required-arg] [optional-arg]
---

name: Identifies the skill. Maximum 64 characters. Lowercase letters, numbers, and hyphens only. The name becomes the /skill-name command. If omitted, Claude Code uses the directory name.

description: What the skill does and when to activate. Maximum 1,024 characters (Codex limits this to 500). The description loads into context at session startup so the agent knows what exists. Specific enough that the agent matches appropriate tasks.

argument-hint: Appears in autocomplete to show expected arguments. Format like [issue-number] for required arguments or [format] for optional ones. Purely cosmetic; the skill still runs with any arguments or none.

Invocation control fields

---
name: dangerous-operation
description: Performs operations with production impact
disable-model-invocation: true
user-invocable: true
---

disable-model-invocation: When true, the agent cannot automatically invoke this skill. Only explicit /skill-name commands work. Use for skills with irreversible side effects.

user-invocable: When false, the skill does not appear in the autocomplete menu. The agent can still invoke it automatically if disable-model-invocation is not set. Use for skills that should run automatically but not be manually triggered.

Tool and model control

---
name: read-only-analysis
description: Analyze code without making changes
allowed-tools: Read, Grep, Glob
model: haiku
---

allowed-tools: Restricts which tools the skill can use. Space-separated list. When the skill is active, the agent can only use the listed tools. This prevents an analysis skill from making edits, or a documentation skill from running bash commands.

Common patterns:

• Read, Grep, Glob: Read-only analysis
• Read, Edit: Code modification without execution
• Bash(npm test:*): Only specific bash commands

model: Override the model for this skill. Options: sonnet, opus, haiku, or inherit (use current model). Use haiku for quick, simple tasks. Use opus for complex reasoning where quality matters more than speed.

Subagent execution

---
name: deep-research
description: Research a topic thoroughly across the codebase
context: fork
agent: Explore
---

context: Set to fork to run the skill in an isolated subagent. The main conversation continues while the skill executes independently. Results summarize back into the main conversation when complete.

agent: When context: fork, specifies the subagent type. Options include:

• Explore: Read-only codebase exploration
• Plan: Implementation planning without execution
• general-purpose: Full capabilities

Forked skills get fresh context windows. A complex research task runs in 200K tokens of clean context, not polluted by conversation history.

String substitution

Skills support variable substitution for dynamic behavior. Variables resolve when the skill loads, before instructions reach the agent.

Argument variables

---
name: fix-issue
description: Fix a GitHub issue by number
argument-hint: [issue-number]
---

## Task

Fix issue $ARGUMENTS on the current branch.
First, fetch issue details using `gh issue view $0`.

If you invoke /fix-issue 1234, then $ARGUMENTS is 1234, and $0 is 1234.

For multiple arguments:

---
name: migrate-component
description: Migrate a component between frameworks
argument-hint: [component] [from-framework] [to-framework]
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

/migrate-component SearchBar React Vue resolves to "Migrate the SearchBar component from React to Vue."

Session variables

---
name: session-logger
description: Log activity for audit purposes
---

Log activity to logs/${CLAUDE_SESSION_ID}.log

Session variables let skills maintain state across invocations within a session.

Dynamic context injection

The !`command` syntax executes shell commands and injects output into the skill before it reaches the agent:

---
name: pr-summary
description: Summarize the current pull request
---

## Current PR context

Diff:
!`gh pr diff`

Changed files:
!`gh pr diff --name-only`

## Task

Summarize this pull request focusing on the key changes.

The backtick commands run when the skill loads. Their output becomes part of the skill instructions. The agent gets fresh, current data without running commands itself.

Skill configuration hierarchy

Skills load from multiple locations with defined precedence. The hierarchy determines which skill wins when names conflict.

Claude Code discovery locations

Higher levels take precedence. An enterprise skill overrides a personal skill with the same name. A personal skill overrides a project skill.

Codex discovery locations

Codex follows the same precedence pattern: closer to the repository takes priority.

Monorepo automatic discovery

In monorepos, skills in subdirectory .claude/skills/ folders activate when editing files in those directories:

my-monorepo/
├── .claude/
│   └── skills/                    # Available everywhere
│       └── shared-conventions/
├── packages/
│   ├── frontend/
│   │   └── .claude/
│   │       └── skills/            # Available when editing frontend/
│   │           └── react-patterns/
│   └── backend/
│       └── .claude/
│           └── skills/            # Available when editing backend/
│               └── api-conventions/

Editing packages/frontend/src/App.tsx makes both root skills and frontend skills available. Backend skills do not load unless editing backend files.

Teams working in different parts of a monorepo see only relevant skills without manual configuration. No skill pollution from unrelated packages.

Context budget management

All skill descriptions load at session startup. With many skills, descriptions may exceed the default character budget (15,000 characters).

Run /context to check if skills are being truncated. If descriptions exceed the budget:

• Shorten descriptions to essential information
• Set SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable to increase the limit
• Move rarely-used skills to personal scope where they only load for you