Skill Lifecycle: Six Stages
Uma skill e um "named, reusable prompt workflow" armazenado como SKILL.md com YAML frontmatter. O lifecycle completo passa por 6 estagios:
Walk managed/user/project directories. Resolve symlinks para deduplicate.
Read SKILL.md. Parse YAML frontmatter. Estima token budget.
Extract fields into Command object. Validate hooks, paths, effort, shell.
Replace $ARGUMENTS, $1/$name, shell !backtick, ${CLAUDE_SKILL_DIR}.
Run inline (same context) ou fork (isolated sub-agent com own token budget).
Tool result enters conversation. Allowed tools e model override applied.
flowchart LR
D["**Discovery**
Walk managed / user /
project / --add-dir paths.
Read dir entries.
Resolve symlinks."]
L["**Load**
Read SKILL.md.
Parse YAML frontmatter.
Estimate token budget."]
P["**Parse**
Extract all frontmatter
fields into Command
object. Validate hooks,
paths, effort, shell."]
S["**Substitute**
Replace $ARGUMENTS,
$1/$name, shell !backtick,
${CLAUDE_SKILL_DIR},
${CLAUDE_SESSION_ID}."]
E["**Execute**
Run inline (expand into
conversation) or fork
(isolated sub-agent with
own token budget)."]
I["**Inject**
Tool result enters
conversation. Allowed
tools and model override
applied for this turn."]
D --> L --> P --> S --> E --> I
style D fill:#22201d,stroke:#7d9ab8,color:#b8b0a4
style L fill:#22201d,stroke:#7d9ab8,color:#b8b0a4
style P fill:#22201d,stroke:#6e9468,color:#b8b0a4
style S fill:#22201d,stroke:#c47a50,color:#b8b0a4
style E fill:#22201d,stroke:#8e82ad,color:#b8b0a4
style I fill:#22201d,stroke:#6e9468,color:#b8b0a4
Four Sources & Priority Order
Skills sao carregadas de 4 fontes com prioridade definida. "When two sources define a skill with the same name, the first one loaded wins." Deduplication usa resolved file paths, nao nomes.
managed/.claude/skills/ -- Enterprise-controlled, highest priority
~/.claude/skills/ -- Personal cross-project library
.claude/skills/ -- Repository-scoped
Compiladas no CLI -- Lowest priority
SKILL.md Format & Frontmatter
O formato SKILL.md usa YAML frontmatter com 15+ fields que controlam tudo: quais tools a skill pode usar, em qual modelo roda, quando ativa automaticamente.
---
name: "Display Name"
description: "One-line summary"
when_to_use: "Auto-invoke hint"
allowed-tools:
- Bash(gh:*)
- Read
- Write
argument-hint: "[branch] [message]"
arguments: branch message
context: fork
model: claude-opus-4-5
effort: high
version: "1.0.0"
user-invocable: true
paths: src/payments/**
hooks:
PreToolUse: [...]
shell:
interpreter: bash
---
# Markdown body with $variable substitutionFrontmatter Field Reference
| Field | Type | Purpose |
|---|---|---|
| name | string | Override directory-derived name |
| allowed-tools | list | Tool permission patterns |
| context | fork | Isolated sub-agent execution |
| model | string | Model override for skill |
| effort | low/med/high | Thinking budget |
| paths | glob | Conditional activation by file pattern |
| disable-model-invocation | bool | Block Skill tool invocation |
Argument Substitution Pipeline
A substituicao de argumentos segue uma pipeline de 6 passos em ordem definida. Se nenhum placeholder for encontrado, argumentos sao appended automaticamente.
$foo, $bar (from arguments frontmatter)$ARGUMENTS[0], $0, $1$ARGUMENTSARGUMENTS: ...!`command` ou blocos ```! (local skills only)${CLAUDE_SKILL_DIR}, ${CLAUDE_SESSION_ID}Exemplo: /myskill "hello world" foo e parseado como ["hello world", "foo"] via shell-quote parsing.
MCP Skills & Bundled Skills
MCP Skills (Remote)
- ⛔ No shell injection -- !backtick e ```! blocos silently skipped
- ⛔ ${CLAUDE_SKILL_DIR} unavailable -- sem directory local
- ✅ Separate registry em
AppState.mcp.commands - ✅ Merged via
getAllCommands()at invocation - 🔒 "MCP skills are remote and untrusted"
Bundled Skills (Built-in)
- ⚡
/simplify-- 3 parallel review agents - ⚡
/commit,/remember,/verify - ⚡
/debug,/stuck - ⚡
/skillify-- writes SKILL.md (internal) - 🔒 Secure nonce dirs (
O_EXCL | O_NOFOLLOW | 0o600)
registerBundledSkill({
name: 'simplify',
description: 'Review changed code for reuse, quality, and efficiency.',
userInvocable: true,
async getPromptForCommand(args) {
return [{ type: 'text', text: SIMPLIFY_PROMPT }]
},
})Permissions, Auto-Allow & Live Reloading
checkPermissions() segue um waterfall de 5 passos:
Live Reloading
O skillChangeDetector monitora directories com chokidar. Quando qualquer SKILL.md muda, debounce de 300ms, fire ConfigChange hooks, e limpa memoization caches. Em Bun, stat-polling substitui FSWatcher (deadlock bug).
Conditional Skills & Legacy Support
Conditional Skills (paths-based)
"A skill with a paths frontmatter field is a conditional skill. It is loaded at startup but not surfaced to Claude until the user opens or edits a file whose path matches one of the glob patterns."
---
paths: src/payments/**
description: "Stripe refund workflow"
---Patterns usam .gitignore syntax. Um ** pattern e tratado como unconditional.
Legacy Support
O diretorio antigo /commands/ (.claude/commands/) ainda funciona com single .md files e skill-name/SKILL.md format, mas novo trabalho deve usar .claude/skills/.
📋 Resumo do Modulo
skill-name/SKILL.md; directory name vira slash command