Claude Code-specific skills: plugin marketplace management and validation

version
0.1.11
GitHub stars
27

Install

/plugin install claude-code@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 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

FeatureAgentsSkills
ActivationExplicitly launched via Agent toolAuto-activated based on context
Tool AccessConfigurable, can be restrictedInherit from parent context
StateIndependent, isolatedShare parent context
Use CaseComplex multi-step tasksKnowledge and guidelines
PersistenceSingle executionAlways 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):

FieldRequiredMeaning
nameyesUnique identifier, lowercase letters and hyphens. Hooks receive this value as agent_type. The filename does not need to match.
descriptionyesWhen Claude delegates to this subagent.
toolsnoTool allowlist. Omit to inherit all tools. To preload skill content use skills — never list Skill here.
disallowedToolsnoDenylist removed from the inherited or specified tool set.
modelnosonnet, opus, haiku, fable, a full model ID (e.g. claude-opus-4-8), or inherit. Defaults to inherit.
permissionModenodefault, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual (alias of default, v2.1.200+). Ignored for plugin subagents.
maxTurnsnoMaximum agentic turns before the subagent stops.
skillsnoSkills preloaded into context at startup. See Preloading Skills below.
mcpServersnoMCP servers available to this subagent (name reference or inline config). Ignored for plugin subagents.
hooksnoLifecycle hooks scoped to this subagent. Ignored for plugin subagents.
memorynoPersistent memory scope: user, project, or local.
backgroundnotrue forces background execution. Unset lets Claude choose; defaults to background as of v2.1.198.
effortnolow, medium, high, xhigh, or max (model-dependent).
isolationnoworktree runs the subagent in a temporary git worktree, auto-cleaned if the subagent makes no changes.
colornored, blue, green, yellow, purple, orange, pink, cyan.
initialPromptnoAuto-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.

SegmentWhat 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-1
  • 318-impl-sonnet-2
  • 318-ci-haiku-3
  • 317-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 tools to Read, Grep, Glob. Template: templates/read-only-analyzer.md. Reviewer agents: no Bash; a separate execution-hands agent runs commands (/core:agent-loop references/reviewer.md); findings per /extras-claude-code:claude-output-styles assets/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 tools entirely 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 example
  • templates/read-only-analyzer.md — security analysis pattern
  • templates/write-capable-agent.md — test generation pattern
  • templates/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 examples
  • references/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

LocationPathCommand 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 skillapps/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 name field replaces the last segment of the command (my-plugin/skills/review/SKILL.md with name: fancy → /my-plugin:fancy). In personal and project skills, name is 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.

FieldType / valuesDefaultEffect
namestringdirectory nameDisplay name; sets the command's last segment for plugin skills only
descriptionstringfirst paragraph of bodyWhat it does and when to use it; drives automatic invocation
when_to_usestring—Extra trigger phrases, appended to description in the listing
argument-hintstring—Autocomplete hint, e.g. [issue-number] or [filename] [format]
argumentsspace-separated string or YAML list—Declares named positional arguments for $name substitution; names map to positions in order
disable-model-invocationbooleanfalseOnly the user can invoke; Claude cannot trigger it automatically
user-invocablebooleantruefalse hides it from the / menu; only Claude can invoke
allowed-toolsspace/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-toolsspace/comma-separated string or YAML list—Tools removed from the pool while the command is active; clears on the next message
modelmodel name or inheritsession modelModel override for the rest of the current turn
effortlow | medium | high | xhigh | maxsession effortEffort override while active
contextforkinlineRuns the command in a forked subagent; the body becomes the subagent's prompt
agentagent typegeneral-purposeWhich subagent type executes when context: fork is set
backgroundbooleantrueWith context: fork, false waits for the result in the invoking turn
hookshook config—Registered on invocation; keeps running for the rest of the session, not scoped to just that turn
pathsglob patterns (string or list)—Auto-load only when working with matching files
shellbash | powershellbashShell 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:

  • \$ARGUMENTS forms 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 $name need no marker: with no arguments passed at load time they render unchanged, which is why they appear undecorated throughout this page.
PlaceholderExpands to
\$ARGUMENTSThe full argument string as typed
\$ARGUMENTS[N]The argument at 0-based index N
$NShorthand for \$ARGUMENTS[N]
$nameThe named argument declared in arguments: frontmatter
CLAUDE_SESSION_IDThe current session ID
CLAUDE_EFFORTThe current effort level
CLAUDE_SKILL_DIRThe directory containing the command's SKILL.md
CLAUDE_PROJECT_DIRThe 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" second gives $0 = hello world, $1 = second. \$ARGUMENTS always gets the full string as typed.
  • Missing arguments differ by kind. An indexed placeholder with no corresponding argument ($2 when 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 no arguments: 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], $issue expands to the first argument and $branch to 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 $1 still expands. A backslash before any other $ is left unchanged. This same backslash is the marker used throughout this page's \$ARGUMENTS placeholders so they stay literal while this doc itself loads. The CLAUDE_* names in the table above are shown bare instead, because the backslash does not escape the braced form.
  • No \$ARGUMENTS in the body? When a command is invoked with arguments but contains no \$ARGUMENTS, Claude Code appends ARGUMENTS: <input> to the end of the content so Claude still sees what was typed.
  • Stacked invocations: typing /write-tests /fix-issue 123 at the start of one message loads both commands and passes the trailing text 123 as \$ARGUMENTS to each.
  • CLAUDE_SKILL_DIR and CLAUDE_PROJECT_DIR also substitute inside Bash rules in allowed-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.json skills array. Invoked as /<plugin>:<name>.
  • Command files: the plugin.json commands field — a single path string or an array of .md file and directory paths; a directory entry loads every .md file 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` (drop KEY=) lines as executable code in review: they run on invocation, before anyone reads the output. Audit third-party skills and plugins for injection lines and allowed-tools grants before installing; project-level allowed-tools takes effect only after the workspace trust dialog is accepted.
  • Use disable-model-invocation: true for commands with side effects (deploy, commit, send-message) so Claude cannot trigger them on its own.
  • In managed environments, enforce disableSkillShellExecution through 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-skills skill — full skill-authoring guide (structure, supporting files, evaluation)
  • claude-plugins skill — plugin.json schema for shipping commands in plugins
  • core:anti-fabrication skill — 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

ScopePathUse case
User~/.claude/settings.json under hooksPersonal automation across all projects
Project<project>/.claude/settings.json under hooksRepo-shared automation
Plugin<plugin-root>/hooks/hooks.jsonDistribute hooks via plugin install
Skill/SubagentSkill or subagent frontmatter hooks: fieldHooks 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 metadata
  • hooks — required wrapper containing event arrays
  • matcher — 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 — see references/hook-examples.md for the real brace-expansion usage.

Hook Events

EventWhen it firesCommon use
SessionStartSession start, resume, clearInject binding context to turn 1
SessionEndSession endsCleanup, telemetry
UserPromptSubmitUser submits a promptAugment prompt, log interaction
PreToolUseBefore a tool executesBlock dangerous calls, validate input
PostToolUseAfter a tool completesFormat, lint, sync, log
StopAgent finishes respondingEnforce completion standards
SubagentStopSpawned subagent finishesSubagent-specific cleanup
PreCompactBefore context compactionInject context to preserve
NotificationA notification firesCustom 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 explicit timeout values.
  • Use CLAUDE_PLUGIN_ROOT (as a brace expansion in real hook commands — see references/hook-examples.md). Never hardcode plugin paths.
  • Validate stdin. Hook input is JSON; use jq and exit cleanly on parse failure.
  • Scope matchers narrowly. Match Write|Edit over matching all tools.
  • Mark scripts executable. chmod +x after creating shell scripts; the hook will fail silently otherwise.
  • Test scripts standalone. Run echo '{...}' | bash hooks/script.sh before relying on the hook to fire.

Security

  • Treat all stdin fields as untrusted input. Use jq to parse, never eval.
  • Block destructive patterns in PreToolUse Bash hooks (rm -rf /, dd if=, force-push to protected branches).
  • Sanitize file paths with realpath and 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 — plugin hooks/hooks.json configuration with PostToolUse, Write|Edit matcher, and CLAUDE_PLUGIN_ROOT
  • templates/skill-hook.md — skill/subagent frontmatter hook example for PreToolUse, PostToolUse, Stop

References

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

  1. The Claude Code feature: a session-level system prompt modification selected via /config, shipped as Markdown files, optionally bundled in plugins.
  2. 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

StyleBehavior
DefaultStandard software-engineering system prompt
ProactiveExecutes 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
ConciseLeads 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+
ExplanatoryAdds educational "Insights" during task completion
LearningCollaborative 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

FieldPurposeDefault
nameDisplay name (inherits from filename if omitted)filename
descriptionShown in /config pickernone
keep-coding-instructionsRetain Claude Code's coding-specific system prompt sectionsfalse
force-for-pluginPlugin 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

ScopePath
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 outputStyle in .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 Agent tool
  • 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

TargetWhere 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 workerPrompt template passed to the worker when spawned
SkillDedicated section in SKILL.md, or a referenced file in assets/
Plugin-wideShared 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

NeedUse
Session-level persona for the human userOutput style
Consistent shape from a specific agent roleContract in the agent definition
Parseable reports from N parallel workersShared contract referenced by each worker
Reusable response shape across a pluginContract in assets/contracts/
One-off format for a single promptInline instructions, no contract needed

Output Styles vs. Related Features

FeatureScopeLoaded WhenModifies
Output styleMain agent loop onlySession start (after /config)System prompt (replaces coding sections)
CLAUDE.mdMain agent loopSession startAppended as user message after system prompt
--append-system-promptMain agent loopSession startAppended to system prompt
SkillMain loop and subagentsOn-demand (invoke or auto)Adds procedural knowledge
AgentSpawned subagentWhen Agent tool invokedIndependent system prompt
Response contract (pattern)Wherever embeddedWhen the host component loadsThe 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 outputStyle and 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 to true.

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 agents
  • assets/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 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

FieldRule
namekebab-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
versionsemver, ^[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
licenseSPDX identifier — MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, ISC. See https://spdx.org/licenses/
keywordsarray 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.

NameResult
Starts with claude-, anthropic-, anthropics-, or cc-plugin-Error
Equals claude, anthropic, anthropics, claude-code, or claude-modsError
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 init and claude plugin tag refuse a name that draws the error.
  • A marketplace entry does not exempt the name: plugin@marketplace is still checked.
  • Name the plugin for what it does. Example: claude-code (error) became extras-claude-code in this repository, which draws only the warning.
  • Run mise run test:plugin-names in 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 a SKILL.md, ADDING to (not replacing) the default skills/ scan — except for a marketplace entry whose source resolves to the marketplace root (e.g. "./"), where it REPLACES the default scan instead (see claude-skills)
  • commands — string or array of .md files or directories, replacing the default commands/ scan (see claude-commands)
  • agents — string or array of files, replacing the default agents/ scan (see claude-agents)
  • workflows — string or array of workflow script files or directories, replacing the default workflows/ scan
  • hooks — string path to a hooks.json, or an inline hooks object (see claude-hooks)
  • mcpServers — string path to an MCP config, or an inline object
  • outputStyles — string or array of output-style files/directories, replacing the default output-styles/ scan (see claude-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.json file 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 /plugin picker and other UI surfaces. Falls back to name when omitted. Unlike name, 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 to true. Set false to ship a plugin that installs disabled (e.g. one that adds cost or connects to an external service) until the user opts in with claude plugin enable <plugin>.
  • userConfig — object declaring values Claude Code prompts the user for at enable time (type, title, description required per key; sensitive, required, default, multiple, min/max optional). 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's server field must match a key in the plugin's mcpServers.
  • dependencies — array of other plugins this plugin requires. Each entry is either a bare plugin-name string, or an object with a required name and optional semver version constraint:
{
  "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 metadata
  • strict — controls marketplace behavior, not the plugin definition
  • source — a plugin's location is declared by the marketplace, not by itself
  • tags — use keywords

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

  1. mkdir -p my-plugin/.claude-plugin my-plugin/skills
  2. From the plugin directory, run nu <CLAUDE_SKILL_DIR>/scripts/init-plugin.nu — or write the manifest by hand with name, version, description, author, license, keywords, and an empty skills array.
  3. Add each skill as a directory containing SKILL.md, and list its path in skills.
  4. 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]:

ScriptPurpose
validate-plugin.nuComplete plugin.json validation
init-plugin.nuGenerate a plugin.json template
format-plugin.nuFormat and sort plugin.json
mutation-probe.nuOn-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 specification
  • references/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:

  1. Agent A runs with the skill loaded
  2. Agent B runs without the skill
  3. A comparator judges outputs blindly
  4. Track: pass rate, token usage, execution time

Multi-Model Testing

Test across model tiers to verify consistency:

ModelTarget Pass Rate
Haiku70%+
Sonnet85%+
Opus95%+

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's templates/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 name and description reach the system prompt. Claude decides relevance from these alone.
  • Level 2 — activation. The full SKILL.md body 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 combined description + when_to_use at 1,536 characters in the skill listing — put the key use case first — and this marketplace enforces a stricter 1024-character cap on description in test/validate-skills-quality.nu.
  • when_to_use: Additional trigger phrases or example requests, appended to description in 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 description is 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.

ItemEnforced by
Description uses third person and includes a Use when ... trigger patternthird_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 exceededlines 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 verifiableanti_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 boundaryjudgment — 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: true to 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. Drop KEY= for the real syntax.
  • A leading backslash before a bare \$ARGUMENTS placeholder — 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 when arguments: declared in frontmatter
  • CLAUDE_SESSION_ID — current session ID
  • CLAUDE_EFFORT — current effort level
  • CLAUDE_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 standalone hooks.json/.mcp.json files — 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

  1. Collect real use cases first. Concrete examples reveal what the skill must support; theoretical requirements do not.
  2. 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.
  3. Create the directory, with its name matching the name property exactly.
  4. Write the body in imperative form. Keep procedure in SKILL.md, detail in references.
  5. 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.
  6. 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.
  7. 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:

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 command
  • padding (optional) — extra horizontal spacing in characters (default 0)
  • refreshInterval (optional, seconds, min 1) — 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:

NeedField path
Model labelmodel.display_name (human) or model.id (stable)
Current folderworkspace.current_dir (basename for display)
Project rootworkspace.project_dir
Context %context_window.used_percentage (null-guard with // 0)
Cumulative tokenscontext_window.total_input_tokens, .total_output_tokens
Cost USDcost.total_cost_usd
Wall time mscost.total_duration_ms
Lines changedcost.total_lines_added, .total_lines_removed
Cache keysession_id
Transcript filetranscript_path
Rate limitsrate_limits.five_hour.used_percentage (Pro/Max only)
Output styleoutput_style.name
Vim modevim.mode (absent when vim off)
Worktreeworktree.* / 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/print line becomes a separate row (multi-line supported).
  • ANSI color escape codes work: \033[32m green, \033[33m yellow, \033[31m red, \033[0m reset.
  • OSC 8 sequences produce clickable hyperlinks in supporting terminals (iTerm2, Kitty, WezTerm). Set FORCE_HYPERLINK=1 for 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 refreshInterval to 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 /tmp or $XDG_CACHE_HOME with 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_percentage is null before the first API call — always // 0 or similar fallback.
  • total_input_tokens is cumulative across the session and can exceed the window size. Never divide it by context_window_size for a percentage — use used_percentage.
  • rate_limits is 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" in jq.
  • 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: true also 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:

ApproachCommunicationCoordinationBest For
Agent TeamsPeer-to-peer messaging + shared task listTeam lead + self-coordinationCollaborative work requiring discussion
SubagentsReport back to parent onlyParent manages allFocused delegated tasks
Agent SDKProgrammatic message streamingDeveloper-controlledCI/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:

PrimitiveUse when
/loop <prompt>You want a self-pacing tick: monitor agents, poll the tracker, advance the queue. Auto-paces via ScheduleWakeup.
RoutinesCron-style scheduled remote agents. Use for daily/weekly autonomous runs.
ChannelsEvent-driven (webhook/integration) entry points. Use when an external system kicks the loop.
WorkflowsFan-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:

  1. Reads bees/tracker state for the epic's issues
  2. Promotes ready issues to in_progress
  3. Notifies the operator if any agent transitioned to a review or needs_help state
  4. 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.

AspectSubagentsSkillsWorkflows
ScaleA few tasks per turnSame as subagentsDozens to hundreds of agents per run
Intermediate results live inClaude's contextClaude's contextScript variables
What's repeatableWorker definitionInstructionsThe orchestration itself
InterruptionRestarts the turnRestarts the turnResumable in the same session

How to trigger a workflow

Workflows require explicit opt-in. Three paths:

  1. 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.
  2. /effort ultracode. Combines xhigh reasoning with automatic orchestration; Claude decides per task when a workflow is warranted. One request can spawn several workflows (understand → change → verify).
  3. Run a saved or bundled workflow as /<name>. /deep-research is 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 when opts.schema is 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 to null; .filter(Boolean) before use.
  • phase(title) — start a progress group; later agent() 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 argless new Date() throw (they break resume). Pass timestamps via args; vary randomness by index.
  • The script has no filesystem or shell access — agents do that work; the script coordinates them.
  • Concurrent agent() calls cap at min(16, cpu_cores - 2) per workflow; excess queues. Lifetime cap is 1000 agents per run.
  • Spawned agents run in acceptEdits mode 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/runId
  • references/patterns.md — orchestration patterns and scale guidance
  • references/managing-runs.md — /workflows TUI, 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 own plugin.json; marketplace fields supplement it.
  • false — the marketplace entry is the complete manifest; no plugin.json needed.

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_ROOT resolves to the plugin's installation directory. Use it as a brace expansion inside skills/commands/agents/hooks/mcpServers values in marketplace.json and plugin.json, so paths survive relocation.
  • CLAUDE_SKILL_DIR resolves 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: false with a full manifest in the entry. See references/marketplace-examples.md ("Inline Plugin Definitions").
  • Component path override — point commands/agents/hooks/mcpServers at custom locations. Same reference ("Component Path Override").
  • Metadata supplementation — with strict: true, add category, keywords, or homepage that 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

  1. mkdir -p .claude-plugin, then generate a skeleton with nu <CLAUDE_SKILL_DIR>/scripts/init-marketplace.nu.
  2. Add an entry per plugin, deciding strict mode for each. A complete entry with a CLAUDE_PLUGIN_ROOT skills path is in references/marketplace-examples.md ("Creating a marketplace — Step 3").
  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 validate rejects claude-code and any name that starts with claude-, anthropic-, anthropics-, or cc-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 with mise 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.json and 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 to null or a name in plugins.
  • Keep source paths unchanged when only the name changes.

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]:

ScriptPurpose
validate-marketplace.nuFull marketplace validation
validate-dependencies.nuDependency graph validation
init-marketplace.nuGenerate a marketplace template
analyze-plugins.nuAnalyze an existing plugin structure
format-marketplace.nuFormat and sort marketplace.json

References

  • references/schema-specification.md — the complete JSON schema
  • references/marketplace-examples.md — copyable CLAUDE_PLUGIN_ROOT path examples for skills, commands, agents, hooks, and mcpServers entries
  • references/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

CommandPurpose
mise sources:checkCompare current vs latest for all plugins; eol column flags an end-of-life release line for endoflife-date sources (claude-skills-237)
mise sources:staleList 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:sourcesValidate sources.toml schema + plugin.json/sources.md agreement
mise sources:reportFull freshness report with priorities
mise sources:init <plugin>Print a DRAFT sources.toml for a plugin (never trusted; --write to save)
mise sources:fence-checkFreshness report for version literals pinned INSIDE code fences (claude-skills-176)
mise test:fenced-literalsValidate 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").

FieldValuesRequiredDescription
skillslist<string>yesSkill DIRECTORY names covered by this source — a non-empty list, not a scalar
namestringyesHuman-readable source identifier
urlstringyes unless check_method = "none"Primary source URL
releases_urlstringnoRelease tracking URL
check_methodsee table belowyesHow to query latest version
github_repoowner/repoconditionalRequired for github-releases
hex_packagestringconditionalRequired for hex-pm
crate_namestringconditionalRequired for crates-io
npm_packagestringconditionalRequired for npm (registry package name, @scope/name included)
docker_imagenamespace/repositoryconditionalRequired for docker-hub (e.g. library/node)
docker_tagstringconditionalOptional 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_productstringconditionalRequired for endoflife-date (the endoflife.date product slug, e.g. nodejs)
current_versionQUOTED shape-checked version string | unknownyes unless noneThe upstream version this skill content was last verified/documented against
version_constraintpre-1.0 | semver | rolling | stableyes unless noneVersion 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_checkedYYYY-MM-DD | unknownyesDate of last check
update_priorityhigh | medium | lowyes unless noneUpdate urgency
breaking_changes_likelyboolnoMinor bumps may break (default: false)
privateboolnotrue 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
notesstringno 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 being 1.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 no pypi check_method, and 0 corpus entries name a Python/CPython upstream.
  • Dual -prerelease++build suffixes (1.0.0-rc.1+build.5) — rejected by strict SEMVER_RE itself, which permits only one suffix group. Accepting it in the shape-based current_version check 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_methodEndpointAuthRate Limit
github-releaseshttps://api.github.com/repos/{owner}/{repo}/releases/latestOptional GITHUB_TOKEN60/hr unauth, 5000/hr auth
hex-pmhttps://hex.pm/api/packages/{package}None100/min
crates-iohttps://crates.io/api/v1/crates/{crate}User-Agent header required1/sec
npmhttps://registry.npmjs.org/{package} — reads .dist-tags.latestNoneNo published anonymous limit found
docker-hubhttps://hub.docker.com/v2/repositories/{namespace}/{repository}/tags?page_size=1&ordering=last_updated — reads the newest tag's nameNone (public repos)Not documented for Hub API reads (distinct from the image-pull rate limit)
endoflife-datehttps://endoflife.date/api/{product}.json — reads the first (newest) cycle's latestNoneNot documented
manualN/AN/AN/A — check releases_url manually
noneN/AN/AN/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.

FieldValuesRequiredDescription
filerepo-relative pathyesThe file containing the pin
literalstringyesThe EXACT pinned string, verbatim — must appear in file's content (checked by mise test:fenced-literals)
contextstringnoOne-line description of what the pin is for
check_methodgithub-releases | docker-hub | manualyesHow to check whether the exact pin still resolves upstream
github_repoowner/repoconditionalRequired for github-releases
docker_imagenamespace/repositoryconditionalRequired for docker-hub
pinned_tagstringconditionalRequired for github-releases/docker-hub — the exact tag to check existence of (NOT "latest")
eol_productstringnoendoflife.date product slug, for EOL cross-check
eol_cyclestringnoThe cycle string to look up (e.g. "16", "3.24") — required if eol_product is set
policytrack | intentional-pinyesSee policy below
notesstringno 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)
occurrencespositive integerno (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:

ConditionClassificationAction
pre-1.0 + breaking_changes_likely = true + major bumpCriticalFull migration checklist
semver + major version bumpBreakingBreaking changes review required
semver + minor/patch bumpStandardLight-touch update
rolling or stableDocsDocumentation 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:

  1. Fetch release notes from releases_url
  2. Identify: breaking changes, new features, deprecations, bug fixes
  3. Compare against skill's currently documented features
  4. 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 WebFetch or 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 typeExamplesChecklist section
CLI toolcontainer, bees, beadsCLI Tools
Library packagetidewave, wasmex, phoenixLibrary Packages
Language/runtimerust, zigLanguage/Runtime
Documentation-basedgit, accessibility, twelve-factorDocumentation-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:

  1. Update sources.toml: set current_version and last_checked. If this update constitutes an actual sources review, also set meta.reviewed_at_plugin_version and meta.last_full_check.
  2. Extend the narrative entry in sources.md — never re-add version or date fields there; test:sources invariant C3 rejects a - **Version**: bullet.
  3. Bump plugin version in <plugin>/.claude-plugin/plugin.json
  4. Bump matching version in .claude-plugin/marketplace.json
  5. Run mise update-all-skills
  6. Run mise test

Use patch bumps (e.g., 0.5.6 → 0.5.7) unless the skill itself has breaking changes.


Phase 6: Validation

CheckCommandPass Criteria
Schemamise testAll plugins pass
SKILL.md lengthwc -l SKILL.mdUnder 500 lines (the lines check in test/validate-skills-quality.nu)
Sources schemamise test:sourcesNo invariant failures
Source URLsmise sources:validateNo 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:

  1. Run mise sources:init <plugin> to print a DRAFT (it only prints — pass --write to save). The draft is NOT trusted: it emits NEEDS-JUDGMENT markers on every skills = [...] entry that must be resolved by hand against the plugin's real skill directories.
  2. Resolve every NEEDS-JUDGMENT marker and fill in all [[sources]] entries for each skill
  3. Set current_version by reading the skill's current SKILL.md
  4. Set last_checked to today's date
  5. Run mise test:sources to confirm schema
  6. 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:

  1. Read .claude-plugin/marketplace.json to discover all plugins
  2. For each local plugin, read its .claude-plugin/plugin.json to get skill paths
  3. For each skill, read SKILL.md and 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.toml coverage is a separate check, owned by test/validate-sources.nu, not this validator.
  4. Classify each skill as Capability Uplift or Encoded Preference
  5. Read each skill's score from mise run test:skills-quality rather than computing one — test/validate-skills-quality.nu is the single source of truth for both the check list and check_count. Copy the printed value verbatim; do not hand-count checks or write a fixed denominator
  6. Present results as a formatted scorecard table
  7. 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-benchmark skill 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.md with proper frontmatter
  • Progressive Disclosure: Generates reference files in references/ for deep context
  • Source Documentation: Updates promptlog/sources.md with 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:

  1. Research: Gather authoritative sources and best practices
  2. Structure: Create skill directory following spec
  3. Generate SKILL.md: Write frontmatter and core content
  4. Create References: Add detailed docs in references/ for progressive disclosure
  5. Document Sources: Update promptlog/sources.md with all sources used
  6. Validate: Ensure spec compliance and activation clarity

Task Instructions: Use Agent tool with subagent_type: "general-purpose" to:

  1. Research the topic thoroughly using web search and authoritative sources
  2. Create the skill directory: skills/<skill-name>/
  3. 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
  4. Create skills/<skill-name>/references/ if detailed documentation is needed
  5. Update promptlog/sources.md with:
    • All URLs and documentation sources used
    • Purpose of each source
    • Key concepts extracted
    • Date accessed
  6. Follow the 7-step skill creation workflow from CLAUDE.md
  7. Use imperative/infinitive language (not second-person)
  8. Keep commonly-used context in SKILL.md, detailed references separate

The agent should produce a complete, spec-compliant skill ready for use.

Sponsors

Details

Marketplace
vinnie357/claude-skills
Source
plugins/tools/claude-code
Category
Tools
Keywords
claude-code, marketplace, validation, teams, benchmark, skill-update

More from vinnie357/claude-skills

All 33