
claude-code
Claude Code-specific skills: plugin marketplace management and validation
- version
- 0.1.11
- GitHub stars
- 27
Install
/plugin install claude-code@vinnie357Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.
Contents
Discovered from sourceSkills 13
Claude Code Agents
Guide for creating custom agents that provide specialized behaviors and tool access for specific tasks.
When spawning as part of a team
Invoke /core:agent-loop for the 4-phase / 6-tier execution model.
Invoke /extras-claude-code:claude-teams if the agent joins a multi-agent team.
Invoke /core:anti-fabrication always — every claim about a tool, file, or test result requires tool execution.
Glob patterns like /core:* do not expand in Agent prompts. List skill names explicitly.
What Are Agents?
Agents are specialized Claude instances with:
- Specific tool access: Limited or specialized tool sets
- Defined behaviors: Pre-configured instructions and constraints
- Task focus: Optimized for particular workflows
- Autonomous operation: Can execute multi-step tasks independently
Agents vs Skills
| Feature | Agents | Skills |
|---|---|---|
| Activation | Explicitly launched via Agent tool | Auto-activated based on context |
| Tool Access | Configurable, can be restricted | Inherit from parent context |
| State | Independent, isolated | Share parent context |
| Use Case | Complex multi-step tasks | Knowledge and guidelines |
| Persistence | Single execution | Always available when loaded |
Agent File Structure
Location
Agents are defined in markdown files located in:
- Plugin:
<plugin-root>/agents/ - User-level:
.claude/agents/
File Naming
- Use kebab-case:
code-reviewer.md - File name becomes the agent type
- Be descriptive about the agent's purpose
Basic Agent Format
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob
model: sonnet
---
You are a code reviewer. Analyze code for quality, security, and best practices.
## Workflow
1. **Find files**: Glob to locate target files
2. **Read code**: Examine contents
3. **Check patterns**: Grep for anti-patterns
4. **Report**: Provide prioritized feedback
## Guidelines
- **Specific**: Reference file:line locations — per `assets/review-findings-format.md` in `/extras-claude-code:claude-output-styles`
- **Actionable**: Suggest concrete fixes
- **Prioritized**: Critical issues first
Writing style: direct, imperative language. Open with "You are a [role]. Your role is to [primary function]" rather than "I am a specialized [role]...". Use numbered workflow steps with specific commands, not bullet lists describing capabilities. Full style guidance and worked best-practice examples: references/patterns.md.
Agent Configuration
YAML Frontmatter
Complete field reference (source: https://code.claude.com/docs/en/sub-agents):
| Field | Required | Meaning |
|---|---|---|
name | yes | Unique identifier, lowercase letters and hyphens. Hooks receive this value as agent_type. The filename does not need to match. |
description | yes | When Claude delegates to this subagent. |
tools | no | Tool allowlist. Omit to inherit all tools. To preload skill content use skills — never list Skill here. |
disallowedTools | no | Denylist removed from the inherited or specified tool set. |
model | no | sonnet, opus, haiku, fable, a full model ID (e.g. claude-opus-4-8), or inherit. Defaults to inherit. |
permissionMode | no | default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual (alias of default, v2.1.200+). Ignored for plugin subagents. |
maxTurns | no | Maximum agentic turns before the subagent stops. |
skills | no | Skills preloaded into context at startup. See Preloading Skills below. |
mcpServers | no | MCP servers available to this subagent (name reference or inline config). Ignored for plugin subagents. |
hooks | no | Lifecycle hooks scoped to this subagent. Ignored for plugin subagents. |
memory | no | Persistent memory scope: user, project, or local. |
background | no | true forces background execution. Unset lets Claude choose; defaults to background as of v2.1.198. |
effort | no | low, medium, high, xhigh, or max (model-dependent). |
isolation | no | worktree runs the subagent in a temporary git worktree, auto-cleaned if the subagent makes no changes. |
color | no | red, blue, green, yellow, purple, orange, pink, cyan. |
initialPrompt | no | Auto-submitted first user turn when run as a main-session agent (--agent). |
Model selection: match the model to task complexity — haiku for simple/repetitive tasks, sonnet for standard tasks, opus/fable for complex reasoning, inherit (default) to match the parent session's model.
Preloading Skills
The skills field preloads full skill content into the subagent's context at startup — not just the description shown during discovery. Use the namespaced form for plugin skills:
---
name: phoenix-reviewer
description: Reviews Phoenix application code
tools: Read, Glob, Grep
skills:
- elixir:phoenix
- elixir:testing
---
Skills not listed in skills remain invocable through the Skill tool during the run — skills only controls what loads automatically at startup. Never list Skill in tools: to enable this; skills is the dedicated field.
Agent Spawning Naming Convention
Build the name parameter from four segments: <issue>-<role>-<model>-<n>. Every segment is a placeholder. None of the four is a literal.
| Segment | What goes there |
|---|---|
<issue> | The number of the tracker issue this agent's team works on — 318 for claude-skills-318. With no tracker issue, use a short task slug (audit-ci). |
<role> | The agent's job on that team (test-author, impl, ci, review). |
<model> | The model tier the agent runs on (haiku, sonnet, opus, fable). |
<n> | The session-global spawn counter. |
Join the segments with hyphens. The assembled name must match ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$. Keep every segment kebab-case, and never use a space.
A session that works issue 318 and then moves to 317 names its agents in this order:
318-test-author-sonnet-1318-impl-sonnet-2318-ci-haiku-3317-plan-fable-4
Read 318-ci-haiku-3 as the CI runner on issue 318's team, running haiku, third agent spawned this session. Each segment answers one question without opening the agent: the issue groups one team under a shared prefix, the role says what the agent does, and the model shows which tier it activated with.
Example spawning:
Agent({
name: '318-impl-sonnet-2',
description: 'Implement feature endpoint',
prompt: '...'
})
The counter is ONE GLOBAL SERIES PER SESSION. The first agent spawned takes 1, the second takes 2, whatever its issue, role, or model tier. The trailing number therefore gives both a unique name and the agent's spawn order. Assign the counter at spawn time. Never reset it mid-session, and never carry it into another session. This is a prompt-discipline convention, not an enforced mechanism.
The Agent tool's name parameter changes report delivery
Passing the Agent tool's name parameter (the convention above) converts the spawned agent into a teammate rather than a plain subagent. This changes how its report reaches the lead: a teammate's plain final text is never delivered — only a SendMessage call reaches the lead. Every spawn prompt built from this convention must instruct the agent to call SendMessage with its full report on completion.
Term collision. This file uses name for two different things. The frontmatter name: field in an agents/*.md file is an agent-type identifier — it does NOT create a teammate. The Agent tool's name parameter at spawn time is the one that does. Say "the Agent tool's name parameter" whenever meaning the latter; conflating the two implies every agent file has broken reporting, which is false.
Escalation re-spawns take a fresh name. When the escalation ladder (haiku → sonnet → opus, per /core:agent-loop "Model Escalation") promotes a failed agent, spawn it under a new name carrying the new model tier and the next counter value — never resume the failed agent under its own name as its escalation. Resuming revives the original agent on its original model while its name still advertises the old tier.
Enforcement backstop. No agent frontmatter field controls report delivery. The TeammateIdle hook (see /extras-claude-code:claude-teams references/agent-teams.md) is the available mechanism for enforcing that a teammate reports before going idle.
Common Agent Patterns
Four recurring shapes, each with a runnable template:
- Read-only analysis (security scans, code reviews, audits): restrict
toolstoRead, Grep, Glob. Template:templates/read-only-analyzer.md. Reviewer agents: noBash; a separate execution-hands agent runs commands (/core:agent-loopreferences/reviewer.md); findings per/extras-claude-code:claude-output-stylesassets/review-findings-format.md; model chosen by tier. - Write-capable (generating tests, docs, code): add
Write. Template:templates/write-capable-agent.md - Full-access (refactoring, migrations, complex modifications): omit
toolsentirely for no restrictions. Template:templates/full-access-agent.md - MCP-enabled (browser automation, external APIs): mix core tools with MCP tool names. Template:
templates/mcp-agent.md
Minimal starting point: templates/basic-agent.md. Best-practice worked examples (clear purpose, appropriate tool access, explicit instructions): references/patterns.md. Plugin wiring, invocation mechanics, and troubleshooting: references/plugin-config.md.
Security
Grant only the tools an agent's task requires — a read-only analyzer never needs Bash or Write. Never hardcode credentials, API keys, private URLs, or access tokens in agent files; agent bodies are prompts checked into repos and plugins. Worked tool-restriction and input-validation examples: references/patterns.md.
References
templates/basic-agent.md— official minimal exampletemplates/read-only-analyzer.md— security analysis patterntemplates/write-capable-agent.md— test generation patterntemplates/full-access-agent.md— refactoring pattern (no tool restrictions)templates/mcp-agent.md— MCP tools pattern (browser automation)references/patterns.md— writing style, common patterns, and worked best-practice/security examplesreferences/plugin-config.md— plugin.json wiring, invoking agents, agent communication, troubleshooting- Claude Code Agents: https://code.claude.com/docs/en/agents
- Subagents (Agent Tool): https://code.claude.com/docs/en/sub-agents
Claude Code Commands
Custom slash commands for Claude Code: prompt files invoked with /name, with argument substitution and dynamic shell context.
Custom commands have merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing .claude/commands/ files keep working and support the same frontmatter. Skills add a directory for supporting files, invocation control, and automatic loading when relevant — so create new commands as skills, and use .claude/commands/ only for single-file prompts you already maintain there. The full skill-authoring guide is the claude-skills skill; this skill covers the command surface: naming, frontmatter, arguments, and dynamic context.
File Locations and Command Names
| Location | Path | Command name |
|---|---|---|
| Personal skill | ~/.claude/skills/<dir>/SKILL.md | /<dir> |
| Project skill | .claude/skills/<dir>/SKILL.md | /<dir> |
| Project command file | .claude/commands/<file>.md | /<file> (extension dropped) |
| Plugin skill | <plugin>/skills/<dir>/SKILL.md | /<plugin>:<dir> |
| Nested project skill | apps/web/.claude/skills/deploy/SKILL.md | /apps/web:deploy when the name clashes with another skill |
- Use kebab-case directory and file names; the name on disk is the name typed.
- When a skill and a command file share a name, the skill takes precedence. Across levels, personal overrides project; enterprise managed settings take precedence over both. Plugin skills are namespaced, so they cannot conflict with other levels.
- In a plugin skill, the frontmatter
namefield replaces the last segment of the command (my-plugin/skills/review/SKILL.mdwithname: fancy→/my-plugin:fancy). In personal and project skills,nameis only a display label — the command still comes from the directory name.
Frontmatter Reference
YAML between --- markers at the top of the file. All fields are optional; description is recommended so Claude knows when to load the command automatically. Malformed YAML loads the body with empty metadata: /name still works, but Claude has no description to match against.
| Field | Type / values | Default | Effect |
|---|---|---|---|
name | string | directory name | Display name; sets the command's last segment for plugin skills only |
description | string | first paragraph of body | What it does and when to use it; drives automatic invocation |
when_to_use | string | — | Extra trigger phrases, appended to description in the listing |
argument-hint | string | — | Autocomplete hint, e.g. [issue-number] or [filename] [format] |
arguments | space-separated string or YAML list | — | Declares named positional arguments for $name substitution; names map to positions in order |
disable-model-invocation | boolean | false | Only the user can invoke; Claude cannot trigger it automatically |
user-invocable | boolean | true | false hides it from the / menu; only Claude can invoke |
allowed-tools | space/comma-separated string or YAML list | — | Tools pre-approved for the turn that invokes the command; the grant clears on the user's next message |
disallowed-tools | space/comma-separated string or YAML list | — | Tools removed from the pool while the command is active; clears on the next message |
model | model name or inherit | session model | Model override for the rest of the current turn |
effort | low | medium | high | xhigh | max | session effort | Effort override while active |
context | fork | inline | Runs the command in a forked subagent; the body becomes the subagent's prompt |
agent | agent type | general-purpose | Which subagent type executes when context: fork is set |
background | boolean | true | With context: fork, false waits for the result in the invoking turn |
hooks | hook config | — | Registered on invocation; keeps running for the rest of the session, not scoped to just that turn |
paths | glob patterns (string or list) | — | Auto-load only when working with matching files |
shell | bash | powershell | bash | Shell used for dynamic context injection in this file |
Do not put allowed-tools on skills in THIS marketplace — test/validate-plugin.nu rejects it as a hard failure; tool allowlists belong on agents here. The field itself is valid upstream Claude Code frontmatter, which is why the table documents it.
Argument Substitution
Placeholders in the body are replaced before Claude sees the content. This means a doc that shows the literal token gets it substituted too when the doc itself loads as a skill. Two different markers keep this page intact, because one escape does not cover both forms:
\$ARGUMENTSforms carry a leading backslash — the documented escape for a literal$(see "Substitution rules" below). Drop the backslash to get the real placeholder.- The
CLAUDE_*names are written bare, because that same backslash does not escape the braced form. See the note under the table. - Digit-indexed forms (
$0,$1,$2, ...) and an undeclared$nameneed no marker: with no arguments passed at load time they render unchanged, which is why they appear undecorated throughout this page.
| Placeholder | Expands to |
|---|---|
\$ARGUMENTS | The full argument string as typed |
\$ARGUMENTS[N] | The argument at 0-based index N |
$N | Shorthand for \$ARGUMENTS[N] |
$name | The named argument declared in arguments: frontmatter |
CLAUDE_SESSION_ID | The current session ID |
CLAUDE_EFFORT | The current effort level |
CLAUDE_SKILL_DIR | The directory containing the command's SKILL.md |
CLAUDE_PROJECT_DIR | The project root directory |
The four CLAUDE_* rows are written bare on purpose. In a real command you use them as brace expansions — a dollar sign, an opening brace, the name, a closing brace. They cannot be shown in that form here: the leading-backslash escape does NOT work on the braced form. Verified by loading this file as a skill — \ before a braced token leaves the backslash in place AND still expands the token, so writing them out would print this session's real ID and paths into the documentation. The backslash escape works only on the bare \$NAME form, which is why the $ARGUMENTS rows above can use it.
Indexing is 0-based: $0 is the FIRST argument and $1 is the SECOND. This runs against shell convention (where $1 is the first parameter) and is the easiest mistake to make when writing commands.
Substitution rules:
- Quoting is shell-style.
/my-skill "hello world" secondgives$0=hello world,$1=second.\$ARGUMENTSalways gets the full string as typed. - Missing arguments differ by kind. An indexed placeholder with no corresponding argument (
$2when only one argument was passed) stays in the content unchanged — this is exactly why the digit-indexed examples on this page ($0,$1,$2) are safe to show undecorated: this skill declares noarguments:and loads with none, so every indexed placeholder above has "no corresponding argument" and renders literally. A named placeholder with no matching argument expands to an empty string. - Named arguments map by position. With
arguments: [issue, branch],$issueexpands to the first argument and$branchto the second. - Escaping a literal
$: a single backslash directly before the token, e.g.\$1.00. A doubled backslash (\\$1) does NOT escape — both backslashes stay and$1still expands. A backslash before any other$is left unchanged. This same backslash is the marker used throughout this page's\$ARGUMENTSplaceholders so they stay literal while this doc itself loads. TheCLAUDE_*names in the table above are shown bare instead, because the backslash does not escape the braced form. - No
\$ARGUMENTSin the body? When a command is invoked with arguments but contains no\$ARGUMENTS, Claude Code appendsARGUMENTS: <input>to the end of the content so Claude still sees what was typed. - Stacked invocations: typing
/write-tests /fix-issue 123at the start of one message loads both commands and passes the trailing text123as\$ARGUMENTSto each. CLAUDE_SKILL_DIRandCLAUDE_PROJECT_DIRalso substitute inside Bash rules inallowed-tools, so a command can pre-approve exactly the bundled script its body tells Claude to run.
Dynamic Context Injection
Shell output can be inlined into the command content before Claude reads it. The examples below carry a KEY= prefix immediately before every ! trigger, for the same reason the previous section escapes $ placeholders with a backslash: showing the live syntax unguarded would run it, or corrupt it into a live diff, while this very page loads. Drop KEY= to get the real syntax.
- Inline:
KEY=!`git diff HEAD`on a line — the command runs and its stdout replaces the placeholder. - Fenced (multi-line): a code fence opened with an info string of exactly
!(shown here as```KEY=!to keep this line inert) runs the commands and inlines the output.
This is preprocessing, not Claude executing a tool: every command runs before Claude sees anything, and Claude receives only the rendered result. Substitution runs once over the original file — command output is not re-scanned for further placeholders.
The inline ! is recognized only at the start of a line or immediately after whitespace — in the text Claude Code actually scans, which is the text after markdown code-span delimiters are stripped, not the markdown source as written. Wrapping a bang in backticks does not by itself supply that preceding whitespace: only a real, visible character immediately before the bang in the rendered text does, which is why KEY=!`cmd` stays literal (the KEY= is real text, not a delimiter) while merely removing the space that might otherwise sit between an opening double-backtick and the bang does not — the delimiters were never counted as separating characters to begin with.
There is no file-inclusion placeholder. To inject a file's content, use KEY=!`cat path/to/file` (drop KEY=).
To block injection for user, project, plugin, and additional-directory sources, set "disableSkillShellExecution": true in settings; each command is replaced with [shell command execution disabled by policy]. Bundled and managed skills are not affected.
Plugin Wiring
Plugin commands ship two ways:
- Plugin skills (preferred): directories under
<plugin>/skills/, listed in the plugin.jsonskillsarray. Invoked as/<plugin>:<name>. - Command files: the plugin.json
commandsfield — a single path string or an array of.mdfile and directory paths; a directory entry loads every.mdfile in it.
See the claude-plugins skill for the full plugin.json schema and validation scripts.
Security
- Never hardcode secrets — API keys, passwords, tokens, private URLs — in command files. Command bodies are prompts checked into repos and plugins.
- Treat
KEY=!`command`(dropKEY=) lines as executable code in review: they run on invocation, before anyone reads the output. Audit third-party skills and plugins for injection lines andallowed-toolsgrants before installing; project-levelallowed-toolstakes effect only after the workspace trust dialog is accepted. - Use
disable-model-invocation: truefor commands with side effects (deploy, commit, send-message) so Claude cannot trigger them on its own. - In managed environments, enforce
disableSkillShellExecutionthrough managed settings, where users cannot override it.
Examples
Complete worked commands — \$ARGUMENTS, $N, named arguments, and dynamic injection — are in references/examples.md.
References
- Claude Code docs, "Extend Claude with skills" (covers custom commands): https://code.claude.com/docs/en/slash-commands
claude-skillsskill — full skill-authoring guide (structure, supporting files, evaluation)claude-pluginsskill — plugin.json schema for shipping commands in pluginscore:anti-fabricationskill — command bodies are prompts; verify every claim they make about tools, files, and behavior before shipping them
Claude Code Hooks
Hooks are shell commands or prompts that Claude Code executes in response to events. They are the only mechanism that can compel behavior — Claude reads memory and skills as guidance, but the harness runs hooks, not Claude.
Hook Configuration Locations
| Scope | Path | Use case |
|---|---|---|
| User | ~/.claude/settings.json under hooks | Personal automation across all projects |
| Project | <project>/.claude/settings.json under hooks | Repo-shared automation |
| Plugin | <plugin-root>/hooks/hooks.json | Distribute hooks via plugin install |
| Skill/Subagent | Skill or subagent frontmatter hooks: field | Hooks registered by a skill or subagent invocation |
Plugin hooks at <plugin-root>/hooks/hooks.json are auto-discovered. No registration in plugin.json required.
Skill hooks: Claude Code registers them when you or Claude invoke the skill and keeps running them for the rest of the session, on turns after the skill's own turn as well. The practical consequence: the coverage gap is a session that never invokes the skill, not a session where the skill merely "isn't loaded" at the moment a tool runs.
Plugin Hook File Structure
Plugin hooks/hooks.json uses the wrapper format — see references/hook-examples.md ("Plugin hooks.json wrapper format") for the complete file.
description— optional, surfaced in plugin metadatahooks— required wrapper containing event arraysmatcher— regex of tool names (PreToolUse/PostToolUse) or session lifecycle phases (SessionStart)CLAUDE_PLUGIN_ROOT— absolute path to the plugin root, expanded at runtime. Written bare here (not as${...}) because the braced form itself expands when this skill loads — seereferences/hook-examples.mdfor the real brace-expansion usage.
Hook Events
| Event | When it fires | Common use |
|---|---|---|
SessionStart | Session start, resume, clear | Inject binding context to turn 1 |
SessionEnd | Session ends | Cleanup, telemetry |
UserPromptSubmit | User submits a prompt | Augment prompt, log interaction |
PreToolUse | Before a tool executes | Block dangerous calls, validate input |
PostToolUse | After a tool completes | Format, lint, sync, log |
Stop | Agent finishes responding | Enforce completion standards |
SubagentStop | Spawned subagent finishes | Subagent-specific cleanup |
PreCompact | Before context compaction | Inject context to preserve |
Notification | A notification fires | Custom notification routing |
Hook Types
Command Hooks
Execute a shell command. Deterministic, fast. See references/hook-examples.md ("Command hook") for an example.
Prompt Hooks
Send a prompt to a model for context-aware decisions. Slower but flexible.
{
"type": "prompt",
"prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT",
"timeout": 30
}
Supported events for prompt hooks: Stop, SubagentStop, UserPromptSubmit, PreToolUse.
SessionStart — Injecting Turn-1 Context
SessionStart is the strongest compliance mechanism: stdout from the hook script becomes part of the model's first input. Memory and skills inform; SessionStart compels.
Plugin example (plugins/example/hooks/hooks.json) — see references/hook-examples.md ("SessionStart — plugin example").
Companion script (plugins/example/hooks/session-start.sh):
#!/usr/bin/env bash
set -u
cat >/dev/null 2>&1 || true # consume stdin
cat <<'EOF'
[PLUGIN-NAME — SESSION-START COMMAND CONTRACT]
These are commands with triggers, not informational text.
1. Run mise run ci before any commit.
2. Conventional commits, no Co-Authored-By attribution.
3. ...
EOF
The header in the heredoc lands as turn-1 context. Keep it tight — every session pays this token cost.
PreToolUse — Validation and Blocking
Exit code from a PreToolUse command hook controls whether the tool runs:
- Exit 0: continue
- Exit 2: block the tool, show stderr to the user. Exit 1, a missing script, a non-executable script, and a timeout are all non-blocking — exit 2 is the only code that blocks.
Example — block force-push to main: see references/hook-examples.md ("PreToolUse — block force-push to main").
guard-push.sh reads the tool input from stdin (JSON), parses with jq, and exits 2 on a forbidden pattern.
PostToolUse — Auto-Format, Lint, Sync
PostToolUse runs after the tool completes. Exit codes are logged but do not affect the tool result. See references/hook-examples.md ("PostToolUse — auto-format after edits") for an example.
The hook reads the tool input from stdin and runs the formatter on the modified file.
Hook Inputs and Outputs
Hook scripts receive event JSON on stdin:
{
"session_id": "abc123",
"transcript_path": "/path/to/transcript.jsonl",
"cwd": "/path/to/project",
"hook_event_name": "PreToolUse",
"tool_name": "Write",
"tool_input": { "file_path": "...", "content": "..." }
}
Parse with jq in the hook script:
file_path=$(jq -r '.tool_input.file_path' < /dev/stdin)
Stdout from SessionStart and UserPromptSubmit hooks is injected into the model's context. Stdout from other events is logged but not surfaced.
Best Practices
- Keep hooks fast. Hooks block the harness. Aim for under 1 second for
PreToolUse/PostToolUse. Set explicittimeoutvalues. - Use
CLAUDE_PLUGIN_ROOT(as a brace expansion in real hook commands — seereferences/hook-examples.md). Never hardcode plugin paths. - Validate stdin. Hook input is JSON; use
jqand exit cleanly on parse failure. - Scope matchers narrowly. Match
Write|Editover matching all tools. - Mark scripts executable.
chmod +xafter creating shell scripts; the hook will fail silently otherwise. - Test scripts standalone. Run
echo '{...}' | bash hooks/script.shbefore relying on the hook to fire.
Security
- Treat all stdin fields as untrusted input. Use
jqto parse, never eval. - Block destructive patterns in
PreToolUseBash hooks (rm -rf /,dd if=, force-push to protected branches). - Sanitize file paths with
realpathand verify they remain inside the project root. - Hooks run with the user's full privileges. A malicious plugin hook can do anything the user can do — review before installing.
Anti-Fabrication
Validate hook behavior with actual execution before claiming it works. Run the hook script standalone, observe stdin parsing, exit codes, and stdout. Do not assume an event fires without verifying the hook entry in the harness logs.
Templates
templates/plugin-hook.md— pluginhooks/hooks.jsonconfiguration withPostToolUse,Write|Editmatcher, andCLAUDE_PLUGIN_ROOTtemplates/skill-hook.md— skill/subagent frontmatter hook example forPreToolUse,PostToolUse,Stop
References
- Claude Code Hooks: https://code.claude.com/docs/en/hooks
- Plugin Configuration: https://code.claude.com/docs/en/plugins#hooks
Claude Code Output Styles
Guide for the native Claude Code output style feature and for applying the same response-contract pattern to agents, slash commands, teams, and skills.
Two Things This Skill Covers
- The Claude Code feature: a session-level system prompt modification selected via
/config, shipped as Markdown files, optionally bundled in plugins. - The pattern: a reusable response-format contract authored once and referenced from agents, commands, teams, or skills when consistent, parseable output is needed.
The feature affects the main agent loop only. The pattern is portable to anywhere a system prompt or instruction block is authored.
Part 1: The Claude Code Feature
What Output Styles Do
Output styles modify Claude Code's system prompt at session start. They can:
- Replace the default software-engineering instructions with a different role/tone/format
- Preserve core capabilities (file I/O, running scripts, TODO tracking)
- Keep or remove coding-specific instructions via
keep-coding-instructions
Output styles are always active once selected, for the whole session. They are set at session start — changes take effect next session so prompt caching stays stable.
Built-In Styles
| Style | Behavior |
|---|---|
| Default | Standard software-engineering system prompt |
| Proactive | Executes immediately, makes reasonable assumptions instead of pausing for routine decisions, and prefers action over planning — stronger autonomous-execution guidance than auto mode, applied without changing the permission mode |
| Concise | Leads with the result, skips preamble and narration, keeps responses short by default, while doing the engineering work as thoroughly as Default; error reports, security warnings, and destructive-action confirmations stay in full. Requires Claude Code v2.1.237+ |
| Explanatory | Adds educational "Insights" during task completion |
| Learning | Collaborative mode — Claude inserts TODO(human) markers for the user to fill in |
Custom Style File Format
---
name: My Custom Style
description: A brief description shown in the /config picker
keep-coding-instructions: false
---
# Custom Style Instructions
You are an interactive CLI tool that helps users with [domain].
## Specific Behaviors
- Respond in [tone]
- Structure output as [format]
- When [condition], do [action]
Frontmatter Fields
| Field | Purpose | Default |
|---|---|---|
name | Display name (inherits from filename if omitted) | filename |
description | Shown in /config picker | none |
keep-coding-instructions | Retain Claude Code's coding-specific system prompt sections | false |
force-for-plugin | Plugin output styles only: apply this style automatically whenever the plugin is enabled, without the user selecting it. Overrides the user's outputStyle setting. If multiple enabled plugins set this, Claude Code uses the first one loaded. | false |
Set keep-coding-instructions: true when the custom style augments coding behavior rather than replacing it.
File Locations
| Scope | Path |
|---|---|
| User-level | ~/.claude/output-styles/ |
| Project-level | .claude/output-styles/ |
| Managed policy | .claude/output-styles/ inside the managed settings directory |
| Plugin-shipped | <plugin-root>/output-styles/ |
Project-level resolution is not one flat path — it loads from every .claude/output-styles/ between the working directory and the repository root. When more than one of these nested directories defines a style with the same name, Claude Code uses the one closest to the working directory.
Selecting a Style
- Interactive:
/config→ Output style → pick from menu - Direct: edit
outputStylein.claude/settings.local.json:
{
"outputStyle": "Explanatory"
}
Selection is written to .claude/settings.local.json at the local project level.
Shipping Output Styles in a Plugin
Place style files under <plugin-root>/output-styles/. They are discovered when the plugin is installed and appear alongside built-in and user styles in /config.
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── skills/
└── output-styles/
├── terse-reviewer.md
└── verbose-tutor.md
No additional plugin.json field is required — the output-styles/ directory is discovered by convention.
Token Usage Considerations
- Output styles add to the input token count via system prompt expansion, but prompt caching amortizes this after the first request per session
- Built-in Explanatory and Learning styles produce longer output by design — higher output token cost
- Custom styles' output cost is driven by what the instructions ask Claude to produce
Part 2: The Pattern — Response Contracts for Agents, Commands, and Teams
The shape of an output style — a set of instructions controlling response format, tone, and structure — is portable. You can apply the same pattern anywhere a system prompt or instruction block is authored.
Important: Subagents Do Not Inherit Output Style
The session-level output style modifies the main agent loop's system prompt. It does not propagate to:
- Subagents spawned via the
Agenttool - Slash command execution contexts
- Skills loaded within a subagent
If you need a subagent to produce output in a specific shape, encode the contract in the agent's own definition or reference a shared contract file.
Exception: forks. A fork (Agent tool with subagent_type: "fork") is not an independent subagent — it's a continuation of the same conversation, so it inherits the parent's full system prompt, output style included. Regular subagents (any other subagent_type) still do not inherit it.
Where to Place a Contract
| Target | Where the contract goes |
|---|---|
Agent (.claude/agents/<name>.md) | Body of the agent markdown, under a ## Response Format heading |
Slash command (.claude/commands/<name>.md) | Body of the command markdown |
| Team worker | Prompt template passed to the worker when spawned |
| Skill | Dedicated section in SKILL.md, or a referenced file in assets/ |
| Plugin-wide | Shared file in assets/contracts/ that components link to |
Why Standardize Worker Output
When a team lead spawns multiple workers and must parse their results, inconsistent output shapes force the lead to write bespoke parsing for each worker. A shared contract lets the lead:
- Extract specific fields (e.g.,
PR_URL,STATUS) with one parser - Filter worker reports for pass/fail without reading prose
- Compare two workers' results reliably
Writing a Contract
A contract specifies:
- Sections the response must contain (fixed headings)
- Field formats inside sections (literal strings, enums, lengths)
- What must not appear (e.g., no prose preamble, no trailing summaries)
Use imperative language. Example contract body:
Respond using exactly these sections, in this order:
## SUMMARY
One sentence describing what was done. No preamble.
## EVIDENCE
Verbatim output from `mise run ci`. Paste the tail if too long,
marked with `[truncated]`.
## STATUS
One of: `passed` | `failed` | `blocked`.
## NEXT
One sentence — what the team lead should do with this report.
Do not add sections. Do not summarize at the end.
Referencing a Shared Contract
From an agent definition:
---
name: ci-validator
description: Runs mise run ci and returns a structured report
---
# CI Validator
Run `mise run ci`. Report using the contract in
`assets/contracts/ci-evidence-format.md` — copy the section headings
exactly.
From a team prompt template (pseudocode):
Spawn worker with prompt:
"Fix the failing test in src/foo.ex.
Report using {{contract: worker-report-format}}."
When to Use a Contract vs. an Output Style
| Need | Use |
|---|---|
| Session-level persona for the human user | Output style |
| Consistent shape from a specific agent role | Contract in the agent definition |
| Parseable reports from N parallel workers | Shared contract referenced by each worker |
| Reusable response shape across a plugin | Contract in assets/contracts/ |
| One-off format for a single prompt | Inline instructions, no contract needed |
Output Styles vs. Related Features
| Feature | Scope | Loaded When | Modifies |
|---|---|---|---|
| Output style | Main agent loop only | Session start (after /config) | System prompt (replaces coding sections) |
| CLAUDE.md | Main agent loop | Session start | Appended as user message after system prompt |
--append-system-prompt | Main agent loop | Session start | Appended to system prompt |
| Skill | Main loop and subagents | On-demand (invoke or auto) | Adds procedural knowledge |
| Agent | Spawned subagent | When Agent tool invoked | Independent system prompt |
| Response contract (pattern) | Wherever embedded | When the host component loads | The host's instructions |
Anti-Fabrication
Do not fabricate output-style behavior or frontmatter fields not documented at https://code.claude.com/docs/en/output-styles. When authoring contracts, verify referenced files exist with Read or Glob before claiming they do. Do not claim an agent honors the session output style — it does not. For the full anti-fabrication ruleset, see core:anti-fabrication.
Common Pitfalls
- Assuming subagents inherit the style. They do not. Encode the contract in the agent definition.
- Editing
outputStyleand expecting mid-session effect. Output style is fixed at session start for cache stability. - Mixing session persona and agent response format. A session-level output style for a reviewer persona is not the right tool for "all my workers must emit structured reports."
- Over-constraining. A contract that dictates every word produces fragile output across model versions. Specify structure, not phrasing.
- Missing
keep-coding-instructions. Custom styles default to stripping coding instructions — if the style is meant to augment coding, set this totrue.
Assets
Reference response-format contracts in assets/:
assets/worker-report-format.md— structured report for team workers (SUMMARY / EVIDENCE / STATUS / NEXT)assets/ci-evidence-format.md— verbatim CI-output contract for validation agentsassets/review-findings-format.md— findings-list contract for code review agents
Copy, reference, or adapt these when defining agents, commands, or team workers.
References
- Claude Code Output Styles: https://code.claude.com/docs/en/output-styles
- Claude Code Plugins Reference: https://code.claude.com/docs/en/plugins-reference
- Settings: https://code.claude.com/docs/en/settings
- CLAUDE.md memory: https://code.claude.com/docs/en/memory
Claude Code Plugin
Guide for creating, validating, and managing plugin.json manifests for Claude Code plugins.
Per core:anti-fabrication: run the validation scripts and read the manifest before claiming a plugin.json is valid or that a component path exists. The validator names the offending field and value; that output is the authority, not this page.
Manifest schema
A manifest lives at .claude-plugin/plugin.json inside the plugin directory.
{
"name": "plugin-name",
"version": "1.2.0",
"description": "Brief plugin description",
"author": { "name": "Author Name", "email": "author@example.com", "url": "https://github.com/author" },
"homepage": "https://docs.example.com/plugin",
"repository": "https://github.com/author/plugin",
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"commands": ["./custom/commands/special.md"],
"agents": "./custom/agents/",
"hooks": "./config/hooks.json",
"mcpServers": "./mcp-config.json",
"skills": ["./skills/skill-one", "./skills/skill-two"]
}
name is the only required field. Everything else is optional, though version, description, license, keywords, repository, and author are worth setting: they are what a user sees before installing, and author is how they reach you with a bug report or a contribution.
Field rules
| Field | Rule |
|---|---|
name | kebab-case, ^[a-z0-9]+(-[a-z0-9]+)*$. Match the marketplace entry name, and be specific rather than generic. The directory name may differ (extras-claude-code lives in plugins/tools/claude-code). Valid: my-plugin, core-skills. Invalid: myPlugin, my_plugin, My-Plugin, plugin-. Never choose a reserved name — see "Reserved names" below |
version | semver, ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$. Valid: 1.0.0, 1.0.0-beta.1, 1.0.0+build.123. Invalid: 1.0, v1.0.0, 1.0.0.0 |
license | SPDX identifier — MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, ISC. See https://spdx.org/licenses/ |
keywords | array of lowercase, specific, domain-bearing strings |
Reserved names
claude plugin validate rejects a plugin name that passes as one of Anthropic's own. Pick the name before you publish.
| Name | Result |
|---|---|
Starts with claude-, anthropic-, anthropics-, or cc-plugin- | Error |
Equals claude, anthropic, anthropics, claude-code, or claude-mods | Error |
Puts official beside claude or anthropic (official-claude-tools) | Error |
Has claude, anthropic, or anthropics as a whole word elsewhere (mcp-for-claude) | Warning |
- The check ignores case and treats any run of separators as one.
claude plugin initandclaude plugin tagrefuse a name that draws the error.- A marketplace entry does not exempt the name:
plugin@marketplaceis still checked. - Name the plugin for what it does. Example:
claude-code(error) becameextras-claude-codein this repository, which draws only the warning. - Run
mise run test:plugin-namesin this repository. It applies the rule offline (test/validate-plugin-names.nu).
Messages, version boundary, and sources: references/validation-and-troubleshooting.md ("Reserved plugin names").
Component paths
Relative to the plugin root, ./-prefixed. Each has a dedicated skill for its own file format:
skills— string or array of directories, each containing aSKILL.md, ADDING to (not replacing) the defaultskills/scan — except for a marketplace entry whosesourceresolves to the marketplace root (e.g."./"), where it REPLACES the default scan instead (seeclaude-skills)commands— string or array of.mdfiles or directories, replacing the defaultcommands/scan (seeclaude-commands)agents— string or array of files, replacing the defaultagents/scan (seeclaude-agents)workflows— string or array of workflow script files or directories, replacing the defaultworkflows/scanhooks— string path to a hooks.json, or an inline hooks object (seeclaude-hooks)mcpServers— string path to an MCP config, or an inline objectoutputStyles— string or array of output-style files/directories, replacing the defaultoutput-styles/scan (seeclaude-output-styles)lspServers— string, array, or inline object of LSP (Language Server Protocol) configs for code intelligence (go-to-definition, find-references). Defaults to a.lsp.jsonfile at the plugin root when the field is absent.
output-styles/ is discovered by convention when outputStyles is unset; setting the field replaces that default scan rather than adding to it (see claude-output-styles).
Metadata and dependency fields
displayName— human-readable name shown in the/pluginpicker and other UI surfaces. Falls back tonamewhen omitted. Unlikename, may contain spaces and any casing; not used for namespacing or lookup.defaultEnabled— boolean, whether the plugin starts enabled when the user has not set a preference. Defaults totrue. Setfalseto ship a plugin that installs disabled (e.g. one that adds cost or connects to an external service) until the user opts in withclaude plugin enable <plugin>.userConfig— object declaring values Claude Code prompts the user for at enable time (type,title,descriptionrequired per key;sensitive,required,default,multiple,min/maxoptional). Substituted as${user_config.KEY}in MCP/LSP configs and hook commands.channels— array of message-channel declarations (Telegram/Slack/Discord-style injection). Each entry'sserverfield must match a key in the plugin'smcpServers.dependencies— array of other plugins this plugin requires. Each entry is either a bare plugin-name string, or an object with a requirednameand optional semverversionconstraint:
{
"dependencies": [
"helper-lib",
{ "name": "secrets-vault", "version": "~2.1.0" }
]
}
This is a plugin.json field, not a marketplace-only one — do not confuse it with category/strict/source/tags below, which upstream documents as marketplace-entry-specific and which this manifest schema does not include. (dependencies may also be echoed inside a marketplace entry, since a marketplace entry can carry any field from the plugin manifest schema — but its home is plugin.json.)
The version field is a range, not an exact version — upstream (see Constrain plugin dependency versions): "The version field accepts any expression supported by Node's semver package, including caret, tilde, hyphen, and comparator ranges." Documented examples: ~2.1.0 (tilde), ^2.0 (caret, partial), >=1.4 (comparator, partial), =2.1.0 (exact pin), 1.2.3 - 2.3.4 (hyphen range), and ||-joined alternatives (e.g. 1.2.7 || >=1.2.9 <2.0.0). validate-plugin.nu validates version against this range grammar, not the exact-version grammar used elsewhere in this manifest (plugin.json's own top-level version field) — a range string like ~2.1.0 is correctly REJECTED by an exact-version check and correctly ACCEPTED by the range check the validator applies here.
The check also accepts every additional form node's own semver.validRange accepts (verified against the actual semver npm package, current published version 7.8.5 — npm view semver version), not just the documented examples verbatim: whitespace between an operator and its version (>= 1.2.3), a LOWERCASE v prefix only (v1.2.3 — uppercase V1.2.3 is REJECTED, node does not case-fold it), ~> as a tilde-range alias, and an empty or whitespace-only string as equivalent to * (any version). An x-range wildcard (x/X/*) is valid only in TRAILING position (1.2.x accepted, x.1.2 and 1.x.3 rejected) — enforced structurally, not just by regex. See the comment above is-version-partial in scripts/validate-plugin.nu for the full list of these decisions and why each one is deliberate rather than accidental.
experimental field
experimental is an object holding components whose manifest schema may still change between releases: experimental.themes (string or array — color theme files/directories, replacing the default themes/ scan) and experimental.monitors (string or array — background monitor configs that start automatically while the plugin is active, replacing the default monitors/monitors.json). Both keys also work unnested at the top level ("themes": ..., "monitors": ...) today, but claude plugin validate already warns on the unnested form, and a future release will require nesting under experimental — use the nested form for new plugins rather than relying on the still-working top-level fallback.
{
"outputStyles": "./styles/",
"lspServers": "./.lsp.json",
"experimental": {
"themes": "./themes/",
"monitors": "./monitors.json"
}
}
Verified against validate-plugin.nu's invalid_fields denylist (category, strict, source, tags): none of outputStyles/lspServers/experimental, nor dependencies/displayName/defaultEnabled/workflows/userConfig/channels, are on it. The complete_manifest_all_documented_fields_recognized case in scripts/validate-plugin.nu's --self-test suite carries all nine fields in one fixture manifest and asserts it passes with zero errors and zero warnings (nu <CLAUDE_SKILL_DIR>/scripts/validate-plugin.nu --self-test).
Both hooks and mcpServers accept either a path or an inline object. Inline, they use each component's own schema — hooks are event-keyed, not lifecycle-keyed:
{
"hooks": {
"PostToolUse": [
{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "<CLAUDE_PLUGIN_ROOT>/scripts/format.sh" }] }
]
},
"mcpServers": { "filesystem": { "command": "mcp-server-filesystem", "args": ["./workspace"] } }
}
CLAUDE_PLUGIN_ROOT is written in angle brackets above, but a real hooks value wraps it as a quoted brace expansion — the harness expands it at hook runtime, which is correct in a JSON config. It is shown angle-bracketed here, not braced, because the braced form expands when this skill loads, replacing it with one machine's absolute path before any reader sees it — the same reason script commands on this page use <CLAUDE_SKILL_DIR> angle-bracketed rather than braced (see /extras-claude-code:claude-skills "Dynamic context and substitutions" for the full notation convention). For the copyable braced form, see /extras-claude-code:claude-hooks, whose reference files are read as raw bytes and can carry it safely.
Fields that must NOT appear in plugin.json
The validator rejects these with Invalid field '<field>' - this belongs in marketplace.json, not plugin.json. Upstream's marketplace-entries schema documents them as marketplace-specific fields, distinct from the plugin manifest schema (see plugin-marketplace):
category— marketplace-level metadatastrict— controls marketplace behavior, not the plugin definitionsource— a plugin's location is declared by the marketplace, not by itselftags— usekeywords
dependencies is NOT on this list — see "Metadata and dependency fields" above. It is a documented plugin.json field, not marketplace-only.
Unrecognized fields warn, not fail
Any other top-level field the validator doesn't recognize produces a warning (Unrecognized field '<field>' - not a known plugin.json field), never a hard failure — matching upstream's own claude plugin validate, which treats unrecognized fields as warnings so a manifest can double as another tool's config (an npm package.json, a VS Code extension manifest) without breaking. A typo'd field name is now visible instead of silently passing.
Pass --strict to promote those warnings to a failing result, mirroring upstream's own claude plugin validate --strict ("Pass --strict to treat warnings as errors. Use it in CI to catch a misspelled field name or a field left over from another tool's manifest before publishing, even though the plugin would load at runtime."). mise run test:plugins runs every local plugin with --strict — all 30 are warning-free as of this change, so a new warning now fails CI instead of only logging. --strict never invents new warnings; a manifest with zero warnings passes identically with or without the flag.
Validation
Scripts are bundled with this skill, under its own directory:
nu <CLAUDE_SKILL_DIR>/scripts/validate-plugin.nu .claude-plugin/plugin.json
nu <CLAUDE_SKILL_DIR>/scripts/validate-plugin.nu .claude-plugin/plugin.json --strict
nu <CLAUDE_SKILL_DIR>/scripts/init-plugin.nu
nu <CLAUDE_SKILL_DIR>/scripts/validate-plugin.nu --self-test # fixture suite for the validator itself
validate-plugin.nu checks JSON syntax (rejecting both unparseable content and valid-but-non-object JSON, such as a bare scalar or array — claude-skills-243), name presence and casing, field types, path accessibility, dependencies shape and version-range syntax, and invalid-field detection, plus a warn-on-unrecognized-field pass (promoted to a failure under --strict). Add --verbose for per-field output.
With --marketplace, it also checks that description and keywords agree with the plugin's marketplace entry, when that entry's source is a local path. plugin.json is authoritative. Entries whose source is a GitHub object are skipped — there is no local manifest to compare. When plugin.json defines a field, the marketplace entry must carry it too: an entry that omits description or keywords while plugin.json defines them is flagged as missing, not treated as agreement (marketplace.json entry is missing '<field>' that plugin.json defines). A field plugin.json itself omits is not compared at all. keywords compares as a sorted list, so reordering the array alone is not a mismatch — only a genuine difference in members is.
Verifying self-test coverage against always-pass mutations
--strict (above) makes every check in validate-plugin.nu load-bearing, which means a check that regresses to always-pass — or has its reject branch quietly removed — stays invisible to mise run test:plugins (that task only catches a check mutated to always FAIL, since it runs the marketplace path against 30 real, currently-valid plugins). This exact shape shipped once already (claude-skills-234/238): the agent model allowlist had zero fixture coverage and only became a CI blocker the moment --strict landed.
Run nu <CLAUDE_SKILL_DIR>/scripts/mutation-probe.nu on demand (not wired into mise test — each probe reruns the full --self-test suite as a subprocess) to verify --self-test still catches a curated set of known-dangerous mutations: neuter a check function to always-pass, or flip one of its exit 1 branches to exit 0, in a temp copy of validate-plugin.nu — the real file is opened read-only and never mutated in place, so an interrupt mid-run cannot leave it changed. An interrupt (or a CRASHED probe, even uninterrupted) can still leave temp directories behind — the probe's own copy dir, plus whatever fixture dirs the killed child --self-test had open — since their cleanup never gets a chance to run; these are OS-purged, not cleaned up by this script. Each probe also asserts self-test's own failure banner (self-test failed:) appears — not just a nonzero exit, which a crash also produces without any fixture having caught anything — AND that the specific expected case name is among the printed failures, so a different, unrelated fixture masking the real gap doesn't read as a pass. A stale probe (its find text no longer present) fails the run rather than silently reporting a hollow "all caught." Add a new probe (a find/replace/expect_case_substring triple in the script's $probes list) whenever a new check ships.
What each message means, and the install-time failures no script detects, is in references/validation-and-troubleshooting.md.
Creating a plugin
mkdir -p my-plugin/.claude-plugin my-plugin/skills- From the plugin directory, run
nu <CLAUDE_SKILL_DIR>/scripts/init-plugin.nu— or write the manifest by hand withname,version,description,author,license,keywords, and an emptyskillsarray. - Add each skill as a directory containing
SKILL.md, and list its path inskills. - Validate, then install through a marketplace that lists the plugin (see
plugin-marketplace):/plugin install <plugin-name>@<marketplace-name>.
Recommended layout:
plugin-name/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ ├── skill-one/
│ └── skill-two/
├── commands/
├── agents/
└── output-styles/
Versioning
Semver, with the usual major/minor/patch split and pre-release tags such as 1.0.0-beta.1 for betas. Keep a plugin's version in step between its plugin.json and its marketplace entry — a mismatch is what breaks update detection for installed users. The bundled validator does NOT check this; it only checks semver format. Cross-manifest version agreement is enforced by a marketplace's own CI, if at all.
Scripts
Bundled in this skill's scripts/ directory, run as nu <CLAUDE_SKILL_DIR>/scripts/<name>.nu [args]:
| Script | Purpose |
|---|---|
validate-plugin.nu | Complete plugin.json validation |
init-plugin.nu | Generate a plugin.json template |
format-plugin.nu | Format and sort plugin.json |
mutation-probe.nu | On-demand check that --self-test catches always-pass/reject-neutered mutations of validate-plugin.nu's own checks |
References
references/plugin-schema.md— the complete JSON schema specificationreferences/validation-and-troubleshooting.md— what each validator message means, and runtime failures no script reports
Skill Benchmarking
Evaluate Agent Skills through static analysis and evaluation-driven methodology. Source: Anthropic's skill evaluation guidance.
Static Analysis Checks
The check list, pass criteria, and failure keys are defined in test/validate-skills-quality.nu — that script is the single source of truth; do not restate its checks here. Run mise run test:skills-quality to produce the current scorecard.
The checks' intent: descriptions that trigger accurately (length caps, "Use when" triggers, third person), spec-compliant naming, bounded body size, working examples, resolvable links, one-level reference depth with no orphaned files, anti-fabrication rules present, and coverage recorded in the plugin's skills/sources.toml (each entry's skills array), verified by set difference against the plugin's declared skill set in test/validate-sources.nu.
Skill Categories
Classify each skill for appropriate evaluation:
Capability Uplift: Enhances Claude's core abilities (coding, analysis, reasoning). Stable across model versions. Test by comparing base model performance with and without the skill.
Encoded Preference: Encodes user-specific workflows, formatting, and conventions. May need updates when models change. Test by verifying fidelity to the encoded workflow.
Evaluation Methodology
Writing Evals
For each skill, create:
- 5-10 representative prompts that should trigger the skill
- 3-5 out-of-scope prompts that should NOT trigger the skill
- Expected behavior criteria for each prompt
In-scope: "Benchmark the elixir plugin's skills" → skill activates
Out-of-scope: "Write an ExUnit test for this module" → skill stays silent
A/B Testing
Compare skill performance using independent agents:
- Agent A runs with the skill loaded
- Agent B runs without the skill
- A comparator judges outputs blindly
- Track: pass rate, token usage, execution time
Multi-Model Testing
Test across model tiers to verify consistency:
| Model | Target Pass Rate |
|---|---|
| Haiku | 70%+ |
| Sonnet | 85%+ |
| Opus | 95%+ |
If Haiku fails but others pass, instructions may rely on implicit reasoning — make them more explicit.
Description Optimization
The description determines activation accuracy. Optimize for:
- Reducing false positives: Too-broad descriptions waste context. Add domain-specific terms.
- Reducing false negatives: Too-narrow descriptions miss valid prompts. Add synonyms and related terms.
- Target: 90%+ true positive rate, <5% false positive rate
Scorecard Output
The validator prints one row per skill: line count, score, and the failure keys for any failed checks. It also diffs results against the shrink-only ratchet in test/quality-baseline.json, so pre-existing failures are waived while new ones fail the run.
Running Benchmarks
- Static analysis:
mise run test:skills-quality— runs all static checks, produces scorecard - Command:
/benchmark-skills— full analysis with category classification and quality assessment - Manual evals: Use
/extras-claude-code:claude-skills'stemplates/evaluation-checklist.md
Iteration
Follow the cycle: Test, Measure, Analyze, Refine, Verify.
Stop iterating when:
- Eval pass rates meet targets across model tiers
- Description triggers accurately
- Token usage is reasonable relative to benefit
- No user-reported issues for 2+ model versions
Anti-Fabrication Requirements
Report only measured results: run the validator or the evals before quoting any score, pass rate, or count, and mark unmeasured values as "requires analysis". The full rules live in the core:anti-fabrication skill.
Agent Skills
Guide for creating modular, self-contained Agent Skills that extend Claude's capabilities with specialized knowledge.
How skills load
A skill is a directory of instructions and resources that Claude discovers and loads on demand. Loading happens in tiers, and the tier a fact lands in decides whether Claude ever sees it:
- Level 1 — discovery. Only the
nameanddescriptionreach the system prompt. Claude decides relevance from these alone. - Level 2 — activation. The full
SKILL.mdbody loads. Every line costs on every activation. - Level 3+ — deep context. Bundled
references/files load only when a specific scenario calls for one.
Write to that structure: the body carries decisions, gotchas, and enforced constraints; references carry look-it-up material. A body that holds everything upfront defeats the mechanism.
Skills also fall into two categories, and the category sets testing and maintenance expectations. Capability uplift builds on general model abilities (a structured code-review procedure) and stays stable across model versions. Encoded preference captures local conventions (a team's commit format) and needs revisiting when models change.
Skill structure
skill-name/
├── SKILL.md # Required: frontmatter + body
├── scripts/ # Optional: executable code for deterministic tasks
├── references/ # Optional: documentation loaded on-demand
└── assets/ # Optional: templates, images, boilerplate
SKILL.md is the only required file: YAML frontmatter, then Markdown body.
Frontmatter
Source: Claude Code Skills documentation. All fields are optional; only description is recommended.
name: Display name. Defaults to the directory name if omitted. Lowercase letters, numbers, and hyphens only (max 64 characters). Reflect the domain in clear hyphen-case —git-operations,elixir-phoenix.description(recommended): What the skill does and when to use it. Two distinct limits apply: Claude Code truncates the combineddescription+when_to_useat 1,536 characters in the skill listing — put the key use case first — and this marketplace enforces a stricter 1024-character cap ondescriptionintest/validate-skills-quality.nu.when_to_use: Additional trigger phrases or example requests, appended todescriptionin the listing.license: License name or filename reference.
The full upstream reference — disable-model-invocation, user-invocable, allowed-tools, model, effort, context: fork, agent, hooks, paths, shell, arguments, argument-hint, metadata — is in references/frontmatter-fields.md. Load it when authoring a skill that needs anything beyond name/description/license.
Write the description in third person, stating both what the skill does and when to use it: [What it does]. Use when [trigger conditions].
Critical: The
descriptionis the ONLY text Claude sees during skill discovery (Level 1). The body's "When to Use" section only loads AFTER activation (Level 2) and cannot trigger it. All activation triggers belong in the description.
Tune a description by failure mode: too broad produces false positives — add domain-specific terms; too narrow produces false negatives — add synonyms and trigger scenarios. Activation-rate targets and eval prompt counts live in /extras-claude-code:claude-skills-benchmark.
Frontmatter policy for THIS marketplace
The upstream spec allows allowed-tools on a skill, pre-approving listed tools while it is active. This marketplace's test/validate-plugin.nu rejects allowed-tools on skills as a hard validation failure. Tool filtering belongs on agents — the tools: frontmatter on an agent file — not on the skills an agent loads. Skills here stay capability-driven and inherit tools from the calling context; an agent needing constrained access defines its own allowlist.
Keep skill frontmatter to name, description, optional license, optional metadata. In another project that does not enforce this policy, upstream allowed-tools is valid.
Pre-edit checklist
Before writing or editing any SKILL.md, verify each item. Named checks live in test/validate-skills-quality.nu unless noted.
| Item | Enforced by |
|---|---|
Description uses third person and includes a Use when ... trigger pattern | third_person + use_when checks |
No allowed-tools field in frontmatter (use agents for tool allowlists) | allowed_tools check; also test/validate-plugin.nu |
Body under 500 lines; split into references/ once exceeded | lines check |
| References stay one level deep (SKILL.md → reference, not reference → reference) | ref_depth check |
| Anti-fabrication rules present — and every claim about a tool, file, or behavior verifiable | anti_fab check (presence only; soundness is on the author) |
Combined description + when_to_use under 1,536 characters (Claude Code's listing truncation) | judgment — no check; the desc check caps description alone at 1024 |
Zero hedging verbs in directives: should, may, might, consider, try to, offer to, it would be good to. A hedge on a thin claim is required, not banned — see /core:anti-fabrication "Hedges vs directives" for the boundary | judgment — no check |
A failed enforced item is a blocker — the validator rejects it. A failed judgment item is a review-time flag: fix it or state why it stays.
Style beyond the checklist follows references/context-engineering-claude-5.md — judgment over rules, single statements, schema over prose — including its boundary test for which rules stay prescriptive.
Skill content types
Three patterns from the upstream docs guide what to put in the body:
- Reference content — knowledge, conventions, style guides. Loads inline alongside conversation context. Example: API design patterns for a codebase.
- Task content — step-by-step instructions for a specific action (deploy, commit, generate). Often pair with
disable-model-invocation: trueto prevent automatic invocation. - Subagent-fork content — runs in an isolated context (
context: fork+agent: Explore|Plan|...). Skill body becomes the task prompt; skill produces a self-contained result.
Dynamic context and substitutions
Skills support runtime substitution before content reaches the model. Source: Claude Code Skills docs.
This section documents syntax that executes or expands at load time — including the load of this very skill. Three different markers keep it intact, because no single escape covers every form:
- A
KEY=prefix immediately before a!shell-injection trigger. DropKEY=for the real syntax. - A leading backslash before a bare
\$ARGUMENTSplaceholder — the documented escape for a literal$. Drop the backslash. - Bare names for the
CLAUDE_*variables, because the backslash does not escape the braced form (see below).
Digit-indexed forms ($0, $1, $N) and an undeclared $name need no marker — with no arguments declared or passed, they render unchanged rather than expanding.
Changing anything in this section means verifying by loading the skill, not by reading the diff — see references/verifying-skill-content.md for the loop, the session-snapshot trap that silently defeats it, and the table of what does and does not protect content.
Shell injection — Claude Code can run shell commands embedded in a skill before the body reaches the model; the command's stdout replaces the placeholder. Two forms:
- Inline: a bang character followed by a backtick-quoted command on a single line.
- Fenced: a code fence whose opening line is three backticks followed by a bang.
## Current diff
KEY=!`git diff HEAD`
```KEY=!
node --version
npm --version
```
Fencing does not protect this example — nesting it inside a five-backtick outer fence was tested and it still executed, which is why the KEY= markers above are load-bearing, not decorative.
String substitutions in skill content:
\$ARGUMENTS— full arguments string\$ARGUMENTS[N]or$N— argument by 0-based index$name— named argument whenarguments:declared in frontmatterCLAUDE_SESSION_ID— current session IDCLAUDE_EFFORT— current effort levelCLAUDE_SKILL_DIR— absolute path to this skill's directory (use for bundled scripts:bash <CLAUDE_SKILL_DIR>/scripts/foo.sh)CLAUDE_PLUGIN_ROOT— absolute path to the enclosing plugin's root directory (use for scripts shared across a plugin's skills:bash <CLAUDE_PLUGIN_ROOT>/scripts/foo.sh)
The four CLAUDE_* names are written bare because they are used as brace expansions in real files and the leading-backslash escape does not work on the braced form — verified by loading: the backslash survives and the token still expands, printing the live session ID and paths. See /extras-claude-code:claude-commands "Argument Substitution" for the full rule.
Settled notation for CLAUDE_SKILL_DIR and CLAUDE_PLUGIN_ROOT in bodies (claude-skills-206): three distinct forms, three distinct roles — never interchange them within a SKILL.md or commands/*.md body.
- Bare name (
CLAUDE_SKILL_DIR,CLAUDE_PLUGIN_ROOT) — naming or defining the variable itself in prose, e.g. a definition-list entry ("CLAUDE_SKILL_DIR— absolute path to..."). Never expands; safe anywhere. - Angle brackets (
<CLAUDE_SKILL_DIR>,<CLAUDE_PLUGIN_ROOT>) — showing the variable embedded in a literal, copyable command or path, e.g.nu <CLAUDE_SKILL_DIR>/scripts/foo.nu. This is the form to use whenever the variable appears as part of runnable syntax rather than as its own subject. - Braced — a dollar sign, opening curly brace, the variable name, and a closing curly brace: the real, functioning expansion syntax. Safe in YAML frontmatter,
references/,templates/, and standalonehooks.json/.mcp.jsonfiles — anywhere that is not the live-loading body itself. Deliberately not shown literally in this paragraph, for the same reason: writing it here would expand it before any reader sees it. That is also why the braced form is never written directly in a SKILL.md or commands/*.md body — it would substitute one machine's absolute path at load time.
Disable shell injection across user/project/plugin skills via "disableSkillShellExecution": true in settings — useful for managed environments.
Authoring workflow
- Collect real use cases first. Concrete examples reveal what the skill must support; theoretical requirements do not.
- Decide what each resource is for —
scripts/for deterministic work that would otherwise be rewritten each time,references/for material loaded on demand,assets/for output templates that never enter context. - Create the directory, with its name matching the
nameproperty exactly. - Write the body in imperative form. Keep procedure in
SKILL.md, detail in references. - Record every source in the plugin's
sources.md— URL, what was taken from it, why, and the date accessed where currency matters. This is what makes a claim auditable later. - Validate before publishing. Write eval prompts that should and should not activate the skill, run them, record actual pass/fail counts, and confirm references load when needed. Full methodology in
references/evaluation-guide.md. - Iterate on evidence. Optimize the description against observed false positives and negatives, and test across Haiku, Sonnet, and Opus. Capture approaches that worked and mistakes that recurred back into the skill, asking Claude which context actually changed its behavior. If the base model passes the evals with the skill unloaded, the skill is unnecessary — deprecate it.
Write the evals before the content, and compare output with the skill loaded against output without it. Measure pass rates and token usage rather than judging quality subjectively; a single run proves nothing. references/evaluation-guide.md covers eval-driven development and blind A/B comparison, and templates/evaluation-checklist.md is a copyable checklist.
Specify constraints, not implementations — "ensure commit messages follow conventional format", not "run git commit -m with prefix type(scope):". Instructions rigid enough to break on a minor model update are too rigid; loose enough to produce inconsistent results, too loose. references/design-patterns.md has the full degree-of-freedom framework, the platform-capability matrix, and guidance on when to execute a bundled script versus read it for patterns to adapt.
Five-tier authoring pipeline
If a skill defines or modifies agent behavior (dispatch patterns, model selection, multi-agent coordination), cross-link /core:agent-loop "Five-Tier Decomposition Pipeline" — the canonical decomposition for complex tasks.
Skill updates that only edit markdown skip P2 (test author) — content-grep tests on markdown are tautological. Updates touching agent definitions (agents/*.md with dispatch logic) follow the full five-tier pipeline since those files are executable specifications.
The pipeline runs inside ONE bees issue per skill update slice. The Sub-team Leader (or bees-worker acting as one) spawns the five stages as separate Task invocations; intermediate artifacts go to bees comments on that issue and git commits on the feature branch. Skill updates do not produce five chained bees rows.
The skill-PR reviewer never runs mise test. Execution hands run it, and the reviewer judges their record (ADR 0001 decision 4).
Sizing a skill
The context window is shared, and a skill's body loads in full on every activation — so justify each line's presence rather than each file's.
Compaction behavior sets the real budget. A skill loads as a single message and stays for the session. Auto-compaction keeps the first 5,000 tokens of each invoked skill, with a 25,000-token combined budget filled from most-recently-invoked first, so older skills can drop after compaction. Re-invoke a skill if it stops influencing behavior.
Security
Install skills only from trusted sources. A skill body is executable input: it can carry shell-injection lines that run before anyone reads the output. Before installing an unfamiliar skill, audit its bundled files and scripts, its code dependencies, any instruction directing Claude to an external service, and any request for credentials or destructive operations.
Disclosure discipline for public repositories
Skill content ships to public repositories; secret references disclose infrastructure even when no credential leaks, and secret scanners do not catch them. In every SKILL.md, reference, and template:
- Use placeholder vault names in secret-manager references:
op://<vault>/item/field, never a real vault name - Use RFC5737 documentation IP ranges in examples (
192.0.2.x,198.51.100.x,203.0.113.x), not RFC1918 addresses from a real network — quote an RFC1918 literal only when it is an upstream tool's documented default - Use generic hostnames (
node1,host.example.com), never real estate hostnames as ssh/URL/mount targets - Apply the same rules to issue-tracker descriptions when the tracker exports to a tracked file (e.g. bees
issues.jsonl)
Enforce with a repo lint in CI where available (this marketplace runs mise test:disclosure).
Anti-fabrication requirements
Every SKILL.md must include anti-fabrication rules — either inline or by referencing core:anti-fabrication. The authoritative rules (evidence-based claims via tool execution, no superlatives, no unsubstantiated metrics, no unmeasured time estimates, explicit uncertainty markers) live in the core:anti-fabrication skill; skill-creation-specific guidance is in references/anti-fabrication.md.
References
Annotated examples of simple and complex skills, category classifications, and common pitfalls are in references/examples.md.
claude-skills/
├── references/
│ ├── design-patterns.md # Degree of freedom, platform matrix, script execution, reference structure
│ ├── evaluation-guide.md # Eval-driven development, A/B testing, description optimization
│ ├── anti-fabrication.md # Skill-creation-specific anti-fab guidance
│ ├── context-engineering-claude-5.md # What changed for Claude 5 generation models
│ ├── frontmatter-fields.md # Full upstream frontmatter reference
│ ├── verifying-skill-content.md # Verify by loading; the session-snapshot trap
│ └── examples.md # Annotated skill examples and common pitfalls
└── templates/
├── evaluation-checklist.md # Copyable eval checklist
├── level1.md # Example skill metadata
├── level2.md # Example skill body
├── level3.md # Example skill folder structure
└── skill.md # Example basic skill
For more information:
- Agent Skills Blog: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- Building Skills Guide (PDF): https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- Improving Skill Creator Blog: https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills
- Example Skills: https://github.com/anthropics/skills
- Skills Cookbook: https://github.com/anthropics/claude-cookbooks/tree/main/skills
- Skill Creator Guide: https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md
- Agent Skills Specification: https://agentskills.io/specification
Your Skill Name
Instructions
[Clear, step-by-step guidance for Claude to follow]
Examples
[Concrete examples of using this Skill]
Claude Code Status Line
Guide for designing, configuring, and debugging the Claude Code status line — a customizable bar rendered at the bottom of the UI that runs a user-supplied shell script on each session update.
Per core:anti-fabrication: test status-line scripts against the real stdin payload (see Testing Locally) before claiming a field renders — never assert output you have not observed.
What Is the Status Line?
The status line is a shell command that Claude Code executes locally on each session update. Claude Code pipes a JSON payload (model, workspace, context-window, cost, etc.) to the script's stdin and renders the script's stdout verbatim as the bar at the bottom of the UI. It runs on the user's machine, consumes no API tokens, and is temporarily hidden during autocomplete, help menus, and permission prompts.
The status line is gated by the same workspace-trust acceptance as hooks. Setting disableAllHooks: true in settings also disables the status line.
Configuration
Add a statusLine block to ~/.claude/settings.json (user) or .claude/settings.json (project):
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2,
"refreshInterval": 5
}
}
Fields:
type— must be"command"command— path to a script, or an inline shell commandpadding(optional) — extra horizontal spacing in characters (default0)refreshInterval(optional, seconds, min1) — re-runs on a fixed timer in addition to event-driven updates; set this when displaying time-based data or when state changes during idle (e.g. subagent progress). Omit for event-only updates.
The /statusline slash command
Claude Code ships a built-in /statusline <description> command that generates a script and updates settings for you (e.g. /statusline show model name and context percentage with a progress bar). Use /statusline delete to remove the configuration.
Prebuilt status-line tools
Writing a script gives full control with zero dependencies. For a turnkey bar without scripting, community tools render the same stdin payload. The most widely used is ccstatusline (sirmalloc/ccstatusline, MIT) — a Node CLI with an interactive config TUI, powerline themes, gradients, Nerd-Font icons, and widgets for token speed, git PR status, block timers, and more. It needs no install and wires itself into settings.json:
{ "statusLine": { "type": "command", "command": "npx -y ccstatusline@latest" } }
It requires Node/Bun on PATH and runs npx on each update (slower cold-start than a local script). The rest of this skill covers the hand-rolled path, which stays the right choice when you want no runtime dependency, deterministic latency, or behavior the tool does not expose.
Stdin JSON Payload
Every invocation receives a JSON object on stdin containing session metadata. Key top-level fields:
| Need | Field path |
|---|---|
| Model label | model.display_name (human) or model.id (stable) |
| Current folder | workspace.current_dir (basename for display) |
| Project root | workspace.project_dir |
| Context % | context_window.used_percentage (null-guard with // 0) |
| Cumulative tokens | context_window.total_input_tokens, .total_output_tokens |
| Cost USD | cost.total_cost_usd |
| Wall time ms | cost.total_duration_ms |
| Lines changed | cost.total_lines_added, .total_lines_removed |
| Cache key | session_id |
| Transcript file | transcript_path |
| Rate limits | rate_limits.five_hour.used_percentage (Pro/Max only) |
| Output style | output_style.name |
| Vim mode | vim.mode (absent when vim off) |
| Worktree | worktree.* / workspace.git_worktree |
See references/input-schema.md for the full JSON schema, nullable fields, and per-field semantics.
Note on context_window.used_percentage: pre-calculated by Claude Code as (input + cache_creation + cache_read) / context_window_size — output tokens are not included. Use this field rather than computing from current_usage or total_input_tokens (which is cumulative and can exceed the window size).
Default Example
The default script shipped in assets/statusline-default.sh surfaces model, folder, context %, and git branch:
#!/usr/bin/env bash
input=$(cat)
MODEL=$(jq -r '.model.display_name // "Claude"' <<<"$input")
DIR=$(jq -r '.workspace.current_dir // .cwd' <<<"$input")
PCT=$(jq -r '.context_window.used_percentage // 0' <<<"$input" | cut -d. -f1)
BRANCH=""
if git -C "$DIR" rev-parse --git-dir >/dev/null 2>&1; then
B=$(git -C "$DIR" branch --show-current 2>/dev/null)
[ -n "$B" ] && BRANCH=" | 🌿 $B"
fi
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% ctx${BRANCH}"
Install it:
cp assets/statusline-default.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh
Then add to ~/.claude/settings.json:
{ "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" } }
Renders e.g. [Opus] 📁 my-project | 42% ctx | 🌿 main.
Output Rules
- Stdout is rendered verbatim; each
echo/printline becomes a separate row (multi-line supported). - ANSI color escape codes work:
\033[32mgreen,\033[33myellow,\033[31mred,\033[0mreset. - OSC 8 sequences produce clickable hyperlinks in supporting terminals (iTerm2, Kitty, WezTerm). Set
FORCE_HYPERLINK=1for terminals that aren't auto-detected. - Keep lines short — long output truncates or wraps in narrow terminals.
- Write to stdout only. A non-zero exit code or empty stdout blanks the row. Writes to stderr are not rendered.
Colored context-bar example
PCT=$(jq -r '.context_window.used_percentage // 0' <<<"$input" | cut -d. -f1)
if [ "$PCT" -lt 70 ]; then COLOR="\033[32m" # green
elif [ "$PCT" -lt 90 ]; then COLOR="\033[33m" # yellow
else COLOR="\033[31m"; fi # red
printf "${COLOR}%d%% ctx\033[0m\n" "$PCT"
Update Cadence
- The script runs after each new assistant message, on permission-mode change, and on vim-mode toggle.
- Events are debounced at 300ms.
- If a new trigger fires while a previous run is still executing, the in-flight run is cancelled.
- Edits to the script apply on the next trigger, not retroactively.
- During idle (e.g. waiting on subagents) events stop firing — set
refreshIntervalto keep time-based data live.
Caching & Performance
Expensive operations (git branch lookups, network calls, file reads) should be cached because the script runs on every update.
- Key the cache on
session_id— stable per session. Do not use$$/ pid; those change on every invocation. - Cache under
/tmpor$XDG_CACHE_HOMEwith the session id in the filename. - Skip the cache on miss by returning fast-path defaults; populate it in the background when safe.
SID=$(jq -r '.session_id' <<<"$input")
CACHE="/tmp/statusline-${SID}.branch"
if [ ! -f "$CACHE" ] || [ $(($(date +%s) - $(stat -f %m "$CACHE" 2>/dev/null || stat -c %Y "$CACHE"))) -gt 30 ]; then
git -C "$DIR" branch --show-current 2>/dev/null > "$CACHE"
fi
BRANCH=$(cat "$CACHE" 2>/dev/null)
Subagent Status Line
A parallel subagentStatusLine setting customizes the row rendered inside the subagent panel. Input adds a tasks array with {id, name, tokenCount, ...}. Output expects NDJSON — one JSON object per line:
{"id":"task-abc","content":"analyzing schema..."}
{"id":"task-def","content":"✓ done"}
Use this to project per-subagent progress into the UI.
Testing Locally
Pipe canned JSON to the script:
echo '{
"model": {"display_name": "Opus"},
"workspace": {"current_dir": "/tmp/x"},
"context_window": {"used_percentage": 42},
"session_id": "test"
}' | ~/.claude/statusline.sh
Iterate until the output looks right, then trigger an assistant message in Claude Code to see it rendered.
Common Pitfalls
used_percentageis null before the first API call — always// 0or similar fallback.total_input_tokensis cumulative across the session and can exceed the window size. Never divide it bycontext_window_sizefor a percentage — useused_percentage.rate_limitsis Pro/Max only and absent before the first API response.- Non-zero exit or stderr writes blank the line. Redirect diagnostics:
git ... 2>/dev/null. - Nullable / absent fields:
session_name,workspace.git_worktree,vim,agent,worktree,rate_limits. Default them with// "fallback"injq. - Script edits apply on the next trigger, not instantly — send a message to re-run.
- Windows runs scripts via Git Bash. Invoke PowerShell explicitly:
powershell -NoProfile -File %USERPROFILE%\.claude\statusline.ps1. disableAllHooks: truealso disables the status line.- Autocomplete / help menus / permission prompts hide the status line temporarily — this is expected behavior, not a script failure.
Claude Teams
Coordinate multiple Claude Code agents working together on shared tasks.
When forming a team
Invoke /core:agent-loop for the 4-phase / 6-tier execution model.
Invoke /extras-claude-code:claude-agents for agent file format, tool allowlists, and model selection.
Invoke /core:anti-fabrication always — every claim about a tool, file, or test result requires tool execution.
Require each teammate to quote one sentence from each loaded skill in its first message as proof of loading. Do not proceed with the teammate's work until proof is received.
Glob patterns like /core:* do not expand in Agent prompts. List skill names explicitly.
Approaches
Three approaches exist for multi-agent coordination, each with different trade-offs:
| Approach | Communication | Coordination | Best For |
|---|---|---|---|
| Agent Teams | Peer-to-peer messaging + shared task list | Team lead + self-coordination | Collaborative work requiring discussion |
| Subagents | Report back to parent only | Parent manages all | Focused delegated tasks |
| Agent SDK | Programmatic message streaming | Developer-controlled | CI/CD, automation, custom apps |
Agent Teams (Experimental)
First-party multi-agent coordination. A team lead spawns teammates that work independently with peer-to-peer messaging and a shared task list.
Enable with: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
For setup, configuration, and usage details, see references/agent-teams.md.
Subagents (Task Tool)
Lightweight delegation within a single session. Subagents run in their own context window, complete a task, and return results to the parent.
For subagent types, custom agents, and isolation patterns, see references/subagents.md.
Agent SDK
Programmatic multi-agent orchestration in Python and TypeScript using the same tools that power Claude Code.
For SDK setup, agent definitions, and session management, see references/agent-sdk.md.
Multi-Agent Patterns
Proven patterns for file ownership, task decomposition, scaling, and quality gates.
For architecture guidance and case studies, see references/patterns.md.
Orchestration primitives
/core:agent-loop defines the decomposition + delegation flow. Four Claude Code primitives compose with it for long-running or recurring work:
| Primitive | Use when |
|---|---|
/loop <prompt> | You want a self-pacing tick: monitor agents, poll the tracker, advance the queue. Auto-paces via ScheduleWakeup. |
| Routines | Cron-style scheduled remote agents. Use for daily/weekly autonomous runs. |
| Channels | Event-driven (webhook/integration) entry points. Use when an external system kicks the loop. |
| Workflows | Fan-out exceeds one turn, the orchestration itself must be repeatable, or results need independent verification passes — see /extras-claude-code:claude-workflows. |
Workflows require explicit opt-in and run in the background; /core:agent-loop "Optional: workflow execution substrate" defines how the five-tier pipeline maps onto them.
/loop example — shepherd a running epic
After dispatching a team for an epic, the operator session runs:
/loop /shepherd
where /shepherd is a project-defined command (not shipped with this plugin — define it in your project's .claude/commands/) that, each tick:
- Reads bees/tracker state for the epic's issues
- Promotes ready issues to in_progress
- Notifies the operator if any agent transitioned to a review or needs_help state
- Halts and pings via PushNotification when the cohort is complete
The /loop harness auto-paces via ScheduleWakeup (default 270s — stays inside the prompt-cache TTL). The operator session is hands-off until the loop fires a notification.
This is the recommended composition for long-running multi-agent work: /core:agent-loop does the per-spawn discipline; /loop does the queue advancement.
Claude Code Workflows
A dynamic workflow is a JavaScript script that orchestrates subagents at scale. Claude writes the script for a task you describe, a runtime executes it in the background, and only the final answer returns to your conversation. The script — not Claude's context — holds the loop, the branching, and the intermediate results, so one run coordinates tens to hundreds of agents instead of the few a single turn manages.
Status: research preview, Claude Code v2.1.154+. Available on paid plans (Pro toggle in /config; Max, Team, Enterprise) and via the Anthropic API, Amazon Bedrock, Google Cloud Vertex AI, and Microsoft Foundry.
When to use a workflow
Reach for a workflow when fan-out exceeds one turn, when the orchestration itself must be repeatable, or when work needs independent verification passes before results reach you. Examples: a codebase-wide bug sweep, a 500-file migration, research that cross-checks sources, or a hard plan drafted from several angles before commitment.
Use a single subagent (the Agent tool) for one-off delegated work whose result lands directly in your context. Use a skill for instructions Claude follows inline. Use a workflow when neither scales.
| Aspect | Subagents | Skills | Workflows |
|---|---|---|---|
| Scale | A few tasks per turn | Same as subagents | Dozens to hundreds of agents per run |
| Intermediate results live in | Claude's context | Claude's context | Script variables |
| What's repeatable | Worker definition | Instructions | The orchestration itself |
| Interruption | Restarts the turn | Restarts the turn | Resumable in the same session |
How to trigger a workflow
Workflows require explicit opt-in. Three paths:
- Include the word "workflow" in the prompt. Claude writes and runs a workflow script for the task — e.g.
Run a workflow to audit every endpoint under src/routes/ for missing auth checks. /effort ultracode. Combinesxhighreasoning with automatic orchestration; Claude decides per task when a workflow is warranted. One request can spawn several workflows (understand → change → verify).- Run a saved or bundled workflow as
/<name>./deep-researchis the built-in workflow; scripts saved to.claude/workflows/become their own commands.
Script anatomy
Every script begins with a pure-literal export const meta = {...} block, then a body that uses the orchestration hooks. The body runs in an async context — await directly.
export const meta = {
name: 'audit-endpoints',
description: 'Find endpoints missing auth checks and propose fixes',
phases: [
{ title: 'Scan', detail: 'list route files' },
{ title: 'Review', detail: 'one agent per route file' },
],
}
phase('Scan')
const files = await agent('List every route file under src/routes/.', { schema: FILES_SCHEMA })
phase('Review')
const findings = await parallel(files.paths.map(p => () =>
agent(`Check ${p} for endpoints missing auth middleware.`, { schema: FINDING_SCHEMA })))
return findings.filter(Boolean)
meta must be a pure literal — no variables, function calls, spreads, or template interpolation. Required fields: name, description. Reuse the same phase() titles in meta.phases so progress groups match.
Core hooks at a glance
agent(prompt, opts?)— spawn one subagent; returns its final text, or a validated object whenopts.schemais set. Options:label,phase,schema,model,isolation,agentType.pipeline(items, ...stages)— run each item through all stages independently, no barrier between stages. The default for multi-stage work.parallel(thunks)— run thunks concurrently and await all (a barrier). A thunk that throws resolves tonull;.filter(Boolean)before use.phase(title)— start a progress group; lateragent()calls fall under it.log(message)— emit a narrator line to the user.workflow(nameOrRef, args?)— run another saved workflow inline as a sub-step (one level of nesting only).args— the value passed as the workflow's input.budget— the turn's token target (budget.total,budget.spent(),budget.remaining()).
Full signatures, return values, schema usage, worktree isolation, model overrides, and resume in references/script-api.md.
pipeline() vs parallel()
Default to pipeline(). It streams each item through every stage with no synchronization point, so item A reaches stage 3 while item B is still in stage 1 — wall-clock equals the slowest single chain, not the sum of slowest-per-stage.
Use parallel() only when stage N genuinely needs every result of stage N-1 at once: dedup or merge across the full set, early-exit on a zero count, or a prompt that compares against "the other findings." Needing to flatten, map, or filter is not a barrier reason — do that inside a pipeline stage.
// pipeline — review and verify stream per-item, no wasted wall-clock
const results = await pipeline(
dimensions,
d => agent(d.prompt, { phase: 'Review', schema: FINDINGS }),
review => parallel(review.findings.map(f => () =>
agent(`Adversarially verify: ${f.title}`, { phase: 'Verify', schema: VERDICT })
.then(v => ({ ...f, verdict: v })))),
)
Orchestration patterns (adversarial verify, judge panel, loop-until-dry, multi-modal sweep, completeness critic) are in references/patterns.md.
Constraints
- JavaScript only — no TypeScript type annotations, interfaces, or generics.
Date.now(),Math.random(), and arglessnew Date()throw (they break resume). Pass timestamps viaargs; vary randomness by index.- The script has no filesystem or shell access — agents do that work; the script coordinates them.
- Concurrent
agent()calls cap atmin(16, cpu_cores - 2)per workflow; excess queues. Lifetime cap is 1000 agents per run. - Spawned agents run in
acceptEditsmode and inherit the session's tool allowlist regardless of session mode. - No mid-run user input — only an agent's own permission prompt can pause a run.
Managing runs
Run /workflows to list and monitor runs — each phase shows agent count, token total, and elapsed time. Press Ctrl+G to view or edit the raw script before approval. A run pauses and resumes within the same session (completed agents replay from cache); exiting Claude Code restarts it fresh on relaunch.
Keybindings, the approval flow, save locations, and disabling workflows are in references/managing-runs.md.
Anti-fabrication
A workflow's final return value is only as trustworthy as the agent results it synthesizes. Return what agents actually reported — never invent findings, counts, or verdicts to fill a schema. When a workflow bounds coverage (top-N, sampling, no-retry), log() what was dropped so partial coverage never reads as complete. Apply /core:anti-fabrication to every claim the workflow surfaces.
References
references/script-api.md— full hook signatures, schema, isolation, model overrides, budget, resume/runIdreferences/patterns.md— orchestration patterns and scale guidancereferences/managing-runs.md—/workflowsTUI, triggering, save locations, config toggles, availability
Claude Code Plugin Marketplace
Guide for creating, validating, and managing plugin marketplaces for Claude Code.
Per core:anti-fabrication: verify schema fields and source paths with the validation scripts before claiming an entry is valid — never assert validation results without running them. The validator names the offending field and value; that output is the authority, not this page.
Marketplace schema
A marketplace lives at .claude-plugin/marketplace.json in the repository root.
Required: name (kebab-case), owner (object; name required, email optional), plugins (array, may be empty).
Optional metadata: description, version, and pluginRoot — a base directory that relative plugin source paths resolve against.
Optional renames: a map from a former plugin name to its current name, or to null for a removed plugin. See "Renaming a plugin".
Plugin entry schema
Plugin entries use the plugin manifest schema with every field optional, plus the marketplace-only fields source, strict, category, and tags. Any field valid in a plugin.json is therefore valid in an entry — see /extras-claude-code:claude-plugins for the manifest schema and for which fields must never appear in a plugin.json.
Each entry requires name (kebab-case) and source. Beyond those:
- Metadata:
description,version,author,homepage,repository,license(SPDX),keywords,category,tags - Component paths:
commands,agents,hooks,mcpServers,skills - Dependencies:
dependencies, an array of"namespace:plugin-name"strings
Strict mode
strict defaults to true.
true— the plugin must ship its ownplugin.json; marketplace fields supplement it.false— the marketplace entry is the complete manifest; noplugin.jsonneeded.
Choose strict: false for simple self-contained plugins whose configuration all lives in marketplace.json, when centralized management is the goal and the plugin is unlikely to be distributed independently.
Choose strict: true when the plugin has complex configuration, may be distributed separately, has its own versioning lifecycle, or when the marketplace is only adding metadata to a manifest that already exists.
This is the one genuine judgment call in a marketplace entry; everything else is schema.
Source formats
"source": "./plugins/my-plugin"
With "metadata": { "pluginRoot": "./plugins" }, a bare "source": "my-plugin" resolves to ./plugins/my-plugin.
"source": { "source": "github", "repo": "owner/plugin-repo", "path": "optional/subdir", "branch": "main" }
"source": { "source": "url", "url": "https://gitlab.com/team/plugin.git", "branch": "main" }
Path variables — a load-time trap
Two different variables, and mixing them up breaks the file:
CLAUDE_PLUGIN_ROOTresolves to the plugin's installation directory. Use it as a brace expansion insideskills/commands/agents/hooks/mcpServersvalues in marketplace.json and plugin.json, so paths survive relocation.CLAUDE_SKILL_DIRresolves to an individual skill's directory — not the plugin root. Bundled scripts live under it.
Both names are written bare on this page on purpose. The braced form expands when a skill loads, so a braced variable inside a skill body is replaced with one machine's absolute path before any reader sees it. That is correct behavior for a JSON config value the harness expands at runtime, and wrong for a command written in a skill body. Copyable braced examples live in references/marketplace-examples.md, where Read returns raw bytes.
Advanced entries
- Inline definitions —
strict: falsewith a full manifest in the entry. Seereferences/marketplace-examples.md("Inline Plugin Definitions"). - Component path override — point
commands/agents/hooks/mcpServersat custom locations. Same reference ("Component Path Override"). - Metadata supplementation — with
strict: true, addcategory,keywords, orhomepagethat the plugin's own manifest omits:
{
"name": "existing-plugin",
"source": "./plugins/existing",
"strict": true,
"category": "development",
"keywords": ["added", "from", "marketplace"]
}
Validation
Scripts are bundled with this skill, under its own directory:
nu <CLAUDE_SKILL_DIR>/scripts/validate-marketplace.nu .claude-plugin/marketplace.json
nu <CLAUDE_SKILL_DIR>/scripts/validate-dependencies.nu .claude-plugin/marketplace.json
validate-marketplace.nu checks JSON syntax, required fields, kebab-case naming, field types, and relative-source accessibility. validate-dependencies.nu checks the dependency graph for cycles and missing entries. Add --verbose for per-field output.
Read the script's message rather than guessing: it names the field and the value. What each message means, plus the install-time and load-time failures no script detects, is in references/validation-and-troubleshooting.md.
Creating a marketplace
mkdir -p .claude-plugin, then generate a skeleton withnu <CLAUDE_SKILL_DIR>/scripts/init-marketplace.nu.- Add an entry per plugin, deciding strict mode for each. A complete entry with a
CLAUDE_PLUGIN_ROOTskills path is inreferences/marketplace-examples.md("Creating a marketplace — Step 3"). - Validate, then install from it:
/plugin marketplace add <owner>/<repo>followed by/plugin install <plugin-name>@<marketplace-name>.
Converting an existing set of plugins into a marketplace is a different procedure — see references/validation-and-troubleshooting.md ("Migrating existing plugins").
Conventions
- Marketplace name — a GitHub username or organization.
- Plugin names — descriptive kebab-case (
elixir-phoenix,rust-tools). Never use a reserved name:claude plugin validaterejectsclaude-codeand any name that starts withclaude-,anthropic-,anthropics-, orcc-plugin-. The check applies to every entry name, whatever the marketplace. Rule and sources:/extras-claude-code:claude-plugins("Reserved names"). This repository checks it offline withmise run test:plugin-names(test/validate-plugin-names.nu). - Categories — standardize across the marketplace rather than inventing per entry:
development,language,tools,frontend,backend,meta. - Versions — semver for both marketplace and plugins. Bump the marketplace when adding or removing a plugin, a plugin when its skills or configuration change, and note breaking changes in the plugin's description. Keep a plugin's version in step between its
plugin.jsonand its marketplace entry. The bundled validator does not check this — it validates semver format only. Enforce agreement in the marketplace repository's CI. - Dependencies — declare them, keep chains shallow, prefix with the namespace, and consider a meta-plugin that bundles a related set.
Renaming a plugin
Renaming a plugin breaks existing installs, because users reference the name in /plugin install and in settings keys. Add a top-level renames map so Claude Code migrates them.
{ "renames": { "old-name": "new-name", "retired-plugin": null } }
- Treat the map as append-only history. Add a new entry for each later rename.
- Map a removed plugin to
null. - Run
claude plugin validate .after each edit. It rejects a chain that does not resolve tonullor a name inplugins. - Keep
sourcepaths unchanged when only thenamechanges.
Procedure, user-visible results, and source: references/validation-and-troubleshooting.md ("Renaming or removing a plugin").
Scripts
Bundled in this skill's scripts/ directory, run as nu <CLAUDE_SKILL_DIR>/scripts/<name>.nu [args]:
| Script | Purpose |
|---|---|
validate-marketplace.nu | Full marketplace validation |
validate-dependencies.nu | Dependency graph validation |
init-marketplace.nu | Generate a marketplace template |
analyze-plugins.nu | Analyze an existing plugin structure |
format-marketplace.nu | Format and sort marketplace.json |
References
references/schema-specification.md— the complete JSON schemareferences/marketplace-examples.md— copyableCLAUDE_PLUGIN_ROOTpath examples for skills, commands, agents, hooks, and mcpServers entriesreferences/validation-and-troubleshooting.md— what each validator message means, migration procedure, and runtime failures
Skill Update
Structured workflow for keeping skills current with upstream sources. Execute all phases in order.
Quick Reference
| Command | Purpose |
|---|---|
mise sources:check | Compare current vs latest for all plugins; eol column flags an end-of-life release line for endoflife-date sources (claude-skills-237) |
mise sources:stale | List only stale sources |
mise sources:validate [plugin] [line|json|table] | Validate that all source URLs resolve (HTTP HEAD, GET fallback on 405); default line format is one grep-able row per URL, json pipes straight to jq |
mise test:sources | Validate sources.toml schema + plugin.json/sources.md agreement |
mise sources:report | Full freshness report with priorities |
mise sources:init <plugin> | Print a DRAFT sources.toml for a plugin (never trusted; --write to save) |
mise sources:fence-check | Freshness report for version literals pinned INSIDE code fences (claude-skills-176) |
mise test:fenced-literals | Validate fenced-literals.toml schema + doc-content agreement (network-free) |
sources.toml Schema
Each plugin's skills/sources.toml tracks upstream dependencies. See templates/sources.toml for the complete annotated template.
[meta] — three required keys: plugin (must equal plugin.json name), reviewed_at_plugin_version (the plugin.json version at the last ACTUAL sources review, or "unknown" — never advanced by a version-bump commit, only by a review), last_full_check (YYYY-MM-DD or "unknown").
| Field | Values | Required | Description |
|---|---|---|---|
skills | list<string> | yes | Skill DIRECTORY names covered by this source — a non-empty list, not a scalar |
name | string | yes | Human-readable source identifier |
url | string | yes unless check_method = "none" | Primary source URL |
releases_url | string | no | Release tracking URL |
check_method | see table below | yes | How to query latest version |
github_repo | owner/repo | conditional | Required for github-releases |
hex_package | string | conditional | Required for hex-pm |
crate_name | string | conditional | Required for crates-io |
npm_package | string | conditional | Required for npm (registry package name, @scope/name included) |
docker_image | namespace/repository | conditional | Required for docker-hub (e.g. library/node) |
docker_tag | string | conditional | Optional for docker-hub (e.g. 13-slim) — when set, switches the check to the per-tag content digest of that exact pin instead of the newest tag's name (claude-skills-225); current_version then holds a sha256:<64 hex> digest, accepted by b3_version_shape only for entries that set this field |
eol_product | string | conditional | Required for endoflife-date (the endoflife.date product slug, e.g. nodejs) |
current_version | QUOTED shape-checked version string | unknown | yes unless none | The upstream version this skill content was last verified/documented against |
version_constraint | pre-1.0 | semver | rolling | stable | yes unless none | Version stability model — NOT valid values for current_version itself; a rolling/stable source with no discrete version records current_version = "unknown" (the convention 117 of 119 rolling entries and 8 of 12 stable entries already follow) |
last_checked | YYYY-MM-DD | unknown | yes | Date of last check |
update_priority | high | medium | low | yes unless none | Update urgency |
breaking_changes_likely | bool | no | Minor bumps may break (default: false) |
private | bool | no | true marks a source whose upstream repo is not publicly readable, so mise sources:validate reports its URLs as private instead of dead (default: false). See Private upstream repositories |
notes | string | no in general, yes when check_method = "none" | Free-form context |
Record unknown for current_version or last_checked when the real value can't be established — a guessed date or version is fabrication; unknown is the sanctioned way to say so. The two are established differently: last_checked is the date the check ran, so a live upstream query settles it. current_version is the version the skill content was verified against, which a live query does not establish — finding 0.9.31 upstream tells you the pin has drifted, not that the content matches 0.9.31. Record the drift in notes and leave the pin where verification actually happened. Both are format-checked: last_checked by test/validate-sources.nu rule b3_date (YYYY-MM-DD or the literal unknown, rejecting anything else); current_version by rule b3_version_shape (unknown, or a shape-based match — not strict semver — of an optional short alpha prefix like v or OTP with an optional -/. separator, one to five dot-separated numeric groups, and an optional -prerelease or +build suffix: ^[A-Za-z]{0,10}[-.]?\d+((\.\d+){1,4}([-+][0-9A-Za-z.-]+)?|([-+][0-9A-Za-z.]+)?)$). A hyphenated suffix (-alpha-1, -rc-2) is legal only when the base has at least one dot-group — semver itself requires a dotted numeric base before a prerelease/build suffix, so a bare-integer base has no business carrying one. This accepts CalVer (v2026.3.15), OTP-style (OTP-29.0.4), bare majors (3), and pre-release/build suffixes including a hyphenated segment like 1.0.0-alpha-1 (claude-skills-196), while rejecting bare calendar dates and hyphenated junk like 2024-01-01, 10-11-2025, and 1-800-flowers (claude-skills-196/197, PR #188 Gate 3), plus embedded whitespace, pasted URLs, and prose like banana or see changelog.
current_version must be a quoted TOML string, not a bare number — test/validate-sources.nu rejects any non-string type before the shape check runs (claude-skills-197). An unquoted current_version = 1.10 parses as a TOML float and silently records "1.1", a different version than what was typed, with no diagnostic; quoting it (current_version = "1.10") is unaffected by TOML's numeric coercion and passes.
Two version shapes are deliberately rejected, not merely unsupported yet (claude-skills-196):
- PEP 440 separator-less suffixes (
3.13.0rc1,2.0b1,1.0.post1) — widening the shape regex to accept these also admits 6 of 31 measured adversarial junk strings, the sharpest being1.x(a version constraint, not a version — exactly what this rule exists to block). No tracked upstream in this repo uses PEP 440: there is nopypicheck_method, and 0 corpus entries name a Python/CPython upstream. - Dual
-prerelease++buildsuffixes (1.0.0-rc.1+build.5) — rejected by strictSEMVER_REitself, which permits only one suffix group. Accepting it in the shape-basedcurrent_versioncheck alone would make that check wider than strict semver in a direction semver itself forbids.
If either need becomes real (a tracked PyPI upstream, a source that genuinely emits dual suffixes), widen both regexes together as its own decision — don't reopen this quietly.
check_method = "none" is for skills with no external upstream (first-party doctrine authored in this repo): notes is required (state why there is no upstream), and url / current_version / version_constraint / update_priority are forbidden.
sources.md index convention
Every sources.toml entry name must appear in sources.md prose — test:sources rule c2_md_no_mention strips scheme-prefixed URLs before matching, so a name sitting only inside its own - **URL**: field does not count. Naming an entry after what the prose already calls it needs no extra text — that is the default and what mise sources:init produces. When prose doesn't already name it, append one Entries: sentence to the Structured tracking: pointer line (same line, not a new one), backticked names, comma-separated:
Structured tracking: [sources.toml](sources.toml) — versions, check methods, and skill coverage live there. Entries: `name-one`, `name-two` (the Foo Skill section below).
Check Method API Endpoints
check_method | Endpoint | Auth | Rate Limit |
|---|---|---|---|
github-releases | https://api.github.com/repos/{owner}/{repo}/releases/latest | Optional GITHUB_TOKEN | 60/hr unauth, 5000/hr auth |
hex-pm | https://hex.pm/api/packages/{package} | None | 100/min |
crates-io | https://crates.io/api/v1/crates/{crate} | User-Agent header required | 1/sec |
npm | https://registry.npmjs.org/{package} — reads .dist-tags.latest | None | No published anonymous limit found |
docker-hub | https://hub.docker.com/v2/repositories/{namespace}/{repository}/tags?page_size=1&ordering=last_updated — reads the newest tag's name | None (public repos) | Not documented for Hub API reads (distinct from the image-pull rate limit) |
endoflife-date | https://endoflife.date/api/{product}.json — reads the first (newest) cycle's latest | None | Not documented |
manual | N/A | N/A | N/A — check releases_url manually |
none | N/A | N/A | N/A — no external upstream exists |
Docker Hub tags are not semver in general — check-docker-hub reports "is a newer tag available" (string equality against the most-recently-updated tag name), not "is there a newer semver release." A specific pinned tag that isn't itself version-shaped (e.g. 16-buster-slim) belongs in notes, not current_version — current_version = "unknown" with version_constraint = "rolling" is the schema-compliant way to track it (see templates/sources.toml).
Setting docker_tag switches the check to check-docker-hub-tag, which queries the per-tag endpoint (https://hub.docker.com/v2/repositories/{namespace}/{repository}/tags/{tag}/ — reads that tag's own digest field) instead of the newest-tag-name endpoint above. This answers a narrower, genuinely answerable question for a realistically pinned image: has THIS exact tag been re-pushed since I last checked, not merely does a differently-named tag exist. current_version stores the last-observed digest; drift means the base image was rebuilt (security patch, layer update) under the same tag name. See plugins/tools/agent-sandboxing/skills/sources.toml's debian-13-slim-base-image entry for a worked, live example (claude-skills-225).
check-endoflife-status (in scripts/sources-lib.nu) is the EOL-aware counterpart to the endoflife-date check_method above: one call to the same https://endoflife.date/api/{product}.json endpoint returns the newest cycle's latest patch, that cycle's own eol state, and its cycle identifier, rather than only the string fetch-latest/classify-staleness consume. check-endoflife-date (the schema-facing function) calls it and returns just .latest, preserving current_version/stale semantics unchanged (claude-skills-226). mise sources:check now surfaces the sentinel automatically as a separate eol column (yes/no/unknown/n/a), kept distinct from stale per claude-skills-174's "behind latest is not itself a finding" policy — no manual call needed (claude-skills-237).
See references/version-check-methods.md for Nushell parsing examples.
Phase 1: Discovery
Run mise sources:check to produce a staleness table. Live run against this repo's own corpus, 2026-08-01 — plugin/skill/source/current/latest/stale/priority are copied verbatim from the run; notes is a short paraphrase, not a literal quote (real notes values run 700–1100+ characters):
plugin | skill | source | current | latest | stale | priority | notes (paraphrased)
core | mise | mise | v2026.3.15 | 2026.7.18 | yes | medium | pinned version is months behind upstream
core | nushell | nushell | 0.113.1 | 0.114.1 | yes | high | pinned version is one minor behind upstream
github | act | nektos-act | unknown | 0.2.89 | no-pin | medium | current_version was never pinned — not drift
sources:check / sources:stale / sources:report are on-demand, network-dependent operator tools — deliberately NOT part of mise test/mise run ci (CI has zero external dependencies). stale is one of: yes (real drift), no (current), no-pin (current_version = "unknown" — nothing recorded to compare, not drift), manual/internal (check_method doesn't query an API), no-releases (upstream has no GitHub Releases feed — a 404, not an error; six sources.toml entries across five plugins document a live 404 today, e.g. actions-toolkit, and all six sit on check_method = "manual" for exactly that reason, so this state currently only fires if an entry is later flipped to github-releases without re-checking the feed first), rate-limited (403/unauthenticated GitHub response — retry with GITHUB_TOKEN set), unknown (hex-pm/crates-io package exists with zero published releases), unset (no current_version recorded at all), error (fetch failed for another reason). The notes column surfaces whatever free-text rationale a toml entry already carries — if an entry existed to track an upstream-documented default as intentionally pinned, that rationale would live in notes rather than a new schema field; see the coverage gap below for why act's own such case has no entry to carry one yet.
Known gap — this tool answers "is a tracked pin stale", not "is every version literal in skill content stale". sources.toml tracks freshness per SKILL, not per literal — a fenced Docker tag or CLI version pin inside a doc has no connection to current_version unless someone deliberately wires one. claude-skills-210 closed the SCHEMA half of this (added npm, docker-hub, and endoflife-date check_methods so a fenced literal like a Docker image tag CAN be expressed), but extending sources.toml's coverage to every fenced literal was explicitly rejected as the fix — see claude-skills-176 below for why, and for the tool that actually closes it.
Resolved (claude-skills-176): a version literal inside a markdown code fence (or a non-markdown template like a Dockerfile) is invisible to BOTH version_pin (test/validate-skills-quality.nu check 17, which only parses "Current stable: X" PROSE claims) and sources.toml (which tracks one upstream per skill, not per literal). Extending version_pin's sources.md-agreement check to also cover fences was considered and rejected: agreement is not freshness — the corpus already proves it, since the mise skill's own prose pin passes version_pin via sources.md agreement while sitting months behind upstream. The fix is a separate, explicitly-manual tool: fenced-literals.toml registers each literal (file, exact pinned string, upstream identity, and a policy of track or intentional-pin), and mise sources:fence-check queries upstream live and reports drift — honest about the network dependency, never wired into mise test/mise run ci. See "fenced-literals.toml Schema" below.
The three scripts' comparison/classification logic (classify-staleness, classify-fetch-error) is pure and self-tested independent of the network boundary: nu <script> --self-test. This proves the parsing/comparison logic; a live run against the real corpus is the only way to exercise the HTTP calls themselves.
If sources.toml does not exist for a plugin, run mise sources:init <plugin> first.
fenced-literals.toml Schema
plugins/tools/claude-code/skills/skill-update/fenced-literals.toml registers version literals pinned INSIDE markdown code fences and non-markdown templates (claude-skills-176) — the class of pin version_pin and sources.toml cannot see.
| Field | Values | Required | Description |
|---|---|---|---|
file | repo-relative path | yes | The file containing the pin |
literal | string | yes | The EXACT pinned string, verbatim — must appear in file's content (checked by mise test:fenced-literals) |
context | string | no | One-line description of what the pin is for |
check_method | github-releases | docker-hub | manual | yes | How to check whether the exact pin still resolves upstream |
github_repo | owner/repo | conditional | Required for github-releases |
docker_image | namespace/repository | conditional | Required for docker-hub |
pinned_tag | string | conditional | Required for github-releases/docker-hub — the exact tag to check existence of (NOT "latest") |
eol_product | string | no | endoflife.date product slug, for EOL cross-check |
eol_cycle | string | no | The cycle string to look up (e.g. "16", "3.24") — required if eol_product is set |
policy | track | intentional-pin | yes | See policy below |
notes | string | no in general, yes when policy = "intentional-pin" | Rationale for the exemption — same convention as sources.toml's check_method = "none" requiring notes; no new schema field is reserved for "intentionally pinned" (claude-skills-180's explicit instruction) |
occurrences | positive integer | no (default: 1) | How many times literal is expected to appear verbatim in file. See "Occurrence count" below. |
Occurrence count (claude-skills-233): the drift check is a substring match, so it only proves literal exists SOMEWHERE in file — a real pin can drift while an unrelated mention of the old string (a comment, a second unrelated example) survives elsewhere and keeps the bare-contains check green. occurrences closes this: mise test:fenced-literals counts the literal's actual occurrences in the file and fails if the count doesn't match. Most entries pin a single example and never set the field (default expectation: exactly 1). Set occurrences explicitly when a literal is legitimately repeated in one file — e.g. wasi:io/streams@0.2.0 recurs across several examples in wit/SKILL.md (occurrences = 4). A mismatch (found count != expected) reports c2_occurrence_mismatch; a literal missing entirely still reports the original c1_literal_drift.
Encoded policy (claude-skills-176, carrying forward claude-skills-174's rule explicitly): a literal needs a fix when EITHER it is past its documented end-of-life, OR it no longer resolves upstream at all (the doc's own example would fail). A literal that is simply not the newest available, while still supported and still resolving, is deliberately left alone — "in-support-but-not-latest" is not a fix. policy = "intentional-pin" suppresses the EOL half of that rule (with notes explaining why) but NOT the broken half — a deleted upstream target produces code that cannot run no matter how deliberately the pin was chosen. mise sources:fence-check implements this via classify-fence-status, self-tested at nu fence-freshness.nu --self-test (network-free — the policy logic is pure; only the existence/EOL lookups touch the network).
Named exception, encoded not narrated: github/skills/act/references/setup-and-config.md's node:16-buster-slim is policy = "intentional-pin" — act's own current docs still present that exact image as the micro-image example, so it stays pinned even though Node 16 is EOL (2023-09-11, confirmed live). This is claude-skills-176's own named case.
Known limitation, not silently covered over: for node:16-buster-slim specifically, docker-hub's per-tag existence check is the only signal this tool can give — claude-skills-225 established that the "newest tag" comparator sources-lib.nu's check-docker-hub provides is degenerate for a deliberately-pinned tag (schema-compliant current_version = "unknown" usage reads no-pin forever; a version-shaped pin reads stale forever against a high-churn alias). fence-freshness.nu therefore checks existence via the Hub API's per-tag endpoint (/v2/repositories/{image}/tags/{tag}/) rather than reusing check-docker-hub — existence and EOL-status context are answerable today; genuine drift detection for a pinned Docker tag is not, until claude-skills-225 lands.
Run mise test:fenced-literals (network-free: schema + does the literal still appear in file) before every commit that touches this registry. Run mise sources:fence-check (network, manual) to see live drift.
Anti-fabrication: Do not report version numbers without executing mise sources:check or querying the upstream API directly. Mark unknown versions as "unknown".
Phase 2: Triage
Classify each stale source before updating:
| Condition | Classification | Action |
|---|---|---|
pre-1.0 + breaking_changes_likely = true + major bump | Critical | Full migration checklist |
semver + major version bump | Breaking | Breaking changes review required |
semver + minor/patch bump | Standard | Light-touch update |
rolling or stable | Docs | Documentation refresh only |
Priority order: high → medium → low. Within same priority: breaking changes first.
Phase 3: Research
For each update target, collect before writing any changes:
- Fetch release notes from
releases_url - Identify: breaking changes, new features, deprecations, bug fixes
- Compare against skill's currently documented features
- Determine if a versioned template is needed (a
templates/<version>/snapshot of that version's commands)
Anti-fabrication requirements:
- Read actual release notes before claiming any feature exists in a new version
- Use
WebFetchor equivalent to retrieve changelog content - Mark any feature as "requires verification" if release notes are unavailable
- Never assume a command or flag exists — verify against official docs or release notes
Phase 4: Update
Apply changes following the type-specific checklist in references/update-checklist.md.
Skill Type Lookup
| Skill type | Examples | Checklist section |
|---|---|---|
| CLI tool | container, bees, beads | CLI Tools |
| Library package | tidewave, wasmex, phoenix | Library Packages |
| Language/runtime | rust, zig | Language/Runtime |
| Documentation-based | git, accessibility, twelve-factor | Documentation-Based |
Versioned Templates
When a CLI tool has breaking command changes across versions, create a versioned template:
skills/<skill-name>/
└── templates/
└── <new-version>/
└── commands.md # Commands snapshot for this version
Reference the old version template in the migration section of SKILL.md.
Phase 5: Bookkeeping
Complete in this order after every update:
- Update
sources.toml: setcurrent_versionandlast_checked. If this update constitutes an actual sources review, also setmeta.reviewed_at_plugin_versionandmeta.last_full_check. - Extend the narrative entry in
sources.md— never re-add version or date fields there;test:sourcesinvariant C3 rejects a- **Version**:bullet. - Bump plugin version in
<plugin>/.claude-plugin/plugin.json - Bump matching version in
.claude-plugin/marketplace.json - Run
mise update-all-skills - Run
mise test
Use patch bumps (e.g., 0.5.6 → 0.5.7) unless the skill itself has breaking changes.
Phase 6: Validation
| Check | Command | Pass Criteria |
|---|---|---|
| Schema | mise test | All plugins pass |
| SKILL.md length | wc -l SKILL.md | Under 500 lines (the lines check in test/validate-skills-quality.nu) |
| Sources schema | mise test:sources | No invariant failures |
| Source URLs | mise sources:validate | No dead links |
| Commit format | — | Conventional commit, no attribution |
Commit format: chore(<plugin>): update <skill> to <version>
Example: chore(claude-code): update container to 0.11.0
Create PR with minimal format (title + bullet list, no attribution, no boilerplate sections).
Agent Team Pattern
For batch updates across multiple plugins, spawn agents per plugin:
Orchestrator (sonnet)
├── Plugin checker (haiku) — runs mise sources:check for one plugin
├── Plugin checker (haiku) — runs mise sources:check for another plugin
└── ...
For each stale source:
├── Standard update (haiku) — minor/patch semver, docs-based
└── Breaking update (sonnet) — major semver, pre-1.0 breaking, CLI tools
Promote model if an agent fails the same task twice: haiku → sonnet → opus.
Bootstrapping a New Plugin
When a plugin has no sources.toml:
- Run
mise sources:init <plugin>to print a DRAFT (it only prints — pass--writeto save). The draft is NOT trusted: it emitsNEEDS-JUDGMENTmarkers on everyskills = [...]entry that must be resolved by hand against the plugin's real skill directories. - Resolve every
NEEDS-JUDGMENTmarker and fill in all[[sources]]entries for each skill - Set
current_versionby reading the skill's current SKILL.md - Set
last_checkedto today's date - Run
mise test:sourcesto confirm schema - Commit:
chore(<plugin>): add sources.toml for version tracking
Commands 2
Benchmark all Agent Skills in the marketplace, producing a quality scorecard with static analysis and category classification.
What it does:
- Discovers all skills across all plugins (reads marketplace.json + plugin.json files)
- Runs static analysis checks per skill (description, naming, line count, examples, anti-fabrication)
- Classifies each skill (Capability Uplift vs Encoded Preference)
- Assesses progressive disclosure usage (references, depth)
- Produces a scorecard table with pass/fail per check and overall score
Output: A scorecard table showing quality metrics for each skill:
Skill | Plugin | Desc | Lines | Refs | Examples | Score
─────────────────┼──────────┼──────┼───────┼──────┼──────────┼──────
git | core | Pass | X/Y | Pass | Pass | X/N
claude-skills | cl-code | Pass | X/Y | Pass | Pass | X/N
X/Y and X/N above are placeholders — copy the real line count and score from the mise run test:skills-quality scorecard. Y is the validator's line cap and N is its check_count; neither is a fixed number restated here, so this table will not go stale as either changes. The validator takes no --plugin filter, so run the full suite and read the rows you need.
Examples:
/benchmark-skills
# Benchmark all skills across all plugins
/benchmark-skills --plugin=core
# Benchmark only skills in the core plugin
Task Instructions: Use Agent tool with subagent_type: "general-purpose" to:
- Read
.claude-plugin/marketplace.jsonto discover all plugins - For each local plugin, read its
.claude-plugin/plugin.jsonto get skill paths - For each skill, read
SKILL.mdand note, as a reading aid for the narrative — not the authoritative check list (see step 5) — the trigger-quality of the description, name compliance, bounded body size, presence of examples, one-level reference depth, and anti-fabrication rules. Skill-to-sources.tomlcoverage is a separate check, owned bytest/validate-sources.nu, not this validator. - Classify each skill as Capability Uplift or Encoded Preference
- Read each skill's score from
mise run test:skills-qualityrather than computing one —test/validate-skills-quality.nuis the single source of truth for both the check list andcheck_count. Copy the printed value verbatim; do not hand-count checks or write a fixed denominator - Present results as a formatted scorecard table
- Summarize: total skills, average score, skills needing attention
If --plugin=<name> is provided, only benchmark skills in that plugin.
Important:
- Read actual SKILL.md files — do not fabricate content or results
- Report actual line counts and check results
- Mark any checks that cannot be performed as "N/A" with explanation
- Use the
claude-skills-benchmarkskill for methodology reference - The anti-fabrication check is SKILL.md-only by design (claude-skills-202): it does not scan
references/, so a skill routing unverified, version-gated claims through a reference file is not flagged by this check. A wider scan was tried and reverted — it let a reference file merely mentioning "fabrication" satisfy the check for a SKILL.md carrying zero anti-fabrication content, which is more lenient, not stricter. Per-file reference scrutiny is tracked separately as claude-skills-141; until it lands, treat a skill's reference files as outside this check's coverage when narrating results
Research a topic and create a properly structured Agent Skill following the Agent Skills Specification.
Skill Creation:
- Directory Structure: Creates
skills/<skill-name>/SKILL.mdwith proper frontmatter - Progressive Disclosure: Generates reference files in
references/for deep context - Source Documentation: Updates
promptlog/sources.mdwith all research sources - Specification Compliance: Follows Agent Skills Specification v1.0
Features:
- Automatic Complexity Assessment: Evaluates topic complexity (1-10 scale)
- Thinking Mode Selection: Standard/Extended/Deep based on complexity
- Manual Override: Use
--complexity=<level>to force thinking depth - YAML Frontmatter: Auto-generates name, description, license, metadata
- Reference Management: Creates separate files for detailed documentation
- Source Tracking: Maintains traceability in promptlog/sources.md
Examples:
/research-skill elixir-genserver
# Creates: skills/elixir-genserver/SKILL.md
# Updates: promptlog/sources.md
/research-skill kubernetes-operators --complexity=high
# Creates: skills/kubernetes-operators/SKILL.md
# skills/kubernetes-operators/references/
# Updates: promptlog/sources.md
/research-skill react-hooks --complexity=medium
# Creates: skills/react-hooks/SKILL.md with enhanced analysis
SKILL.md Structure:
---
name: skill-name
description: What the skill does and when to use it — this is the ONLY text
Claude sees during discovery, so every activation trigger belongs here, not
in a body section.
license: MIT
---
# Skill Name
## Core Concepts
[Essential knowledge]
## Best Practices
[Guidelines and patterns]
## Examples
[Concrete usage examples]
## References
[Links to reference files if needed]
Workflow:
- Research: Gather authoritative sources and best practices
- Structure: Create skill directory following spec
- Generate SKILL.md: Write frontmatter and core content
- Create References: Add detailed docs in references/ for progressive disclosure
- Document Sources: Update promptlog/sources.md with all sources used
- Validate: Ensure spec compliance and activation clarity
Task Instructions: Use Agent tool with subagent_type: "general-purpose" to:
- Research the topic thoroughly using web search and authoritative sources
- Create the skill directory:
skills/<skill-name>/ - Generate SKILL.md with:
- Proper YAML frontmatter (name, description, license)
- Clear activation criteria in description
- Core procedural knowledge in markdown body
- Concrete examples and patterns
- Create
skills/<skill-name>/references/if detailed documentation is needed - Update
promptlog/sources.mdwith:- All URLs and documentation sources used
- Purpose of each source
- Key concepts extracted
- Date accessed
- Follow the 7-step skill creation workflow from CLAUDE.md
- Use imperative/infinitive language (not second-person)
- Keep commonly-used context in SKILL.md, detailed references separate
The agent should produce a complete, spec-compliant skill ready for use.
Hooks 1
Sponsors
Details
- Marketplace
- vinnie357/claude-skills
- Source
- plugins/tools/claude-code
- Category
- Tools
- Keywords
- claude-code, marketplace, validation, teams, benchmark, skill-update