{"owner":"anthropics","repo":"claude-code","hasSkills":true,"totalSkillsCount":83,"totalTokensCount":142514,"categories":["marketplace","command-prompt","claude-rule","plugin-manifest","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".claude-plugin/marketplace.json",".claude/commands/commit-push-pr.md",".claude/commands/dedupe.md",".claude/commands/triage-issue.md","CLAUDE.md","mods/agents-md/.claude-plugin/plugin.json","mods/diff/.claude-plugin/plugin.json","mods/sec-default/.claude-plugin/plugin.json","mods/telemetry/.claude-plugin/plugin.json","plugins/README.md","plugins/agent-sdk-dev/.claude-plugin/plugin.json","plugins/agent-sdk-dev/README.md","plugins/claude-opus-4-5-migration/.claude-plugin/plugin.json","plugins/claude-opus-4-5-migration/README.md","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/SKILL.md","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/effort.md","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/prompt-snippets.md","plugins/code-review/.claude-plugin/plugin.json","plugins/code-review/README.md","plugins/commit-commands/.claude-plugin/plugin.json","plugins/commit-commands/README.md","plugins/explanatory-output-style/.claude-plugin/plugin.json","plugins/explanatory-output-style/README.md","plugins/feature-dev/.claude-plugin/plugin.json","plugins/feature-dev/README.md","plugins/frontend-design/.claude-plugin/plugin.json","plugins/frontend-design/README.md","plugins/frontend-design/skills/frontend-design/SKILL.md","plugins/hookify/.claude-plugin/plugin.json","plugins/hookify/README.md","plugins/hookify/skills/writing-rules/SKILL.md","plugins/learning-output-style/.claude-plugin/plugin.json","plugins/learning-output-style/README.md","plugins/plugin-dev/README.md","plugins/plugin-dev/skills/agent-development/SKILL.md","plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md","plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md","plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md","plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md","plugins/plugin-dev/skills/agent-development/references/triggering-examples.md","plugins/plugin-dev/skills/command-development/README.md","plugins/plugin-dev/skills/command-development/SKILL.md","plugins/plugin-dev/skills/command-development/examples/plugin-commands.md","plugins/plugin-dev/skills/command-development/examples/simple-commands.md","plugins/plugin-dev/skills/command-development/references/advanced-workflows.md","plugins/plugin-dev/skills/command-development/references/documentation-patterns.md","plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md","plugins/plugin-dev/skills/command-development/references/interactive-commands.md","plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md","plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md","plugins/plugin-dev/skills/command-development/references/testing-strategies.md","plugins/plugin-dev/skills/hook-development/SKILL.md","plugins/plugin-dev/skills/hook-development/references/advanced.md","plugins/plugin-dev/skills/hook-development/references/migration.md","plugins/plugin-dev/skills/hook-development/references/patterns.md","plugins/plugin-dev/skills/hook-development/scripts/README.md","plugins/plugin-dev/skills/mcp-integration/SKILL.md","plugins/plugin-dev/skills/mcp-integration/examples/http-server.json","plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json","plugins/plugin-dev/skills/mcp-integration/examples/stdio-server.json","plugins/plugin-dev/skills/mcp-integration/references/authentication.md","plugins/plugin-dev/skills/mcp-integration/references/server-types.md","plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md","plugins/plugin-dev/skills/plugin-settings/SKILL.md","plugins/plugin-dev/skills/plugin-settings/examples/create-settings-command.md","plugins/plugin-dev/skills/plugin-settings/examples/example-settings.md","plugins/plugin-dev/skills/plugin-settings/references/parsing-techniques.md","plugins/plugin-dev/skills/plugin-settings/references/real-world-examples.md","plugins/plugin-dev/skills/plugin-structure/README.md","plugins/plugin-dev/skills/plugin-structure/SKILL.md","plugins/plugin-dev/skills/plugin-structure/examples/advanced-plugin.md","plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md","plugins/plugin-dev/skills/plugin-structure/examples/standard-plugin.md","plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md","plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md","plugins/plugin-dev/skills/skill-development/SKILL.md","plugins/plugin-dev/skills/skill-development/references/skill-creator-original.md","plugins/pr-review-toolkit/.claude-plugin/plugin.json","plugins/pr-review-toolkit/README.md","plugins/ralph-wiggum/.claude-plugin/plugin.json","plugins/ralph-wiggum/README.md","plugins/security-guidance/.claude-plugin/plugin.json","plugins/security-guidance/README.md"],"skills":{".claude-plugin/marketplace.json":"{\n \"$schema\": \"https://json.schemastore.org/claude-code-marketplace.json\",\n \"name\": \"claude-code-plugins\",\n \"version\": \"1.0.0\",\n \"description\": \"Bundled plugins for Claude Code including Agent SDK development tools, PR review toolkit, and commit workflows\",\n \"owner\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"plugins\": [\n {\n \"name\": \"agent-sdk-dev\",\n \"description\": \"Development kit for working with the Claude Agent SDK\",\n \"source\": \"./plugins/agent-sdk-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"claude-opus-4-5-migration\",\n \"description\": \"Migrate your code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"William Hu\",\n \"email\": \"whu@anthropic.com\"\n },\n \"source\": \"./plugins/claude-opus-4-5-migration\",\n \"category\": \"development\"\n },\n {\n \"name\": \"code-review\",\n \"description\": \"Automated code review for pull requests using multiple specialized agents with confidence-based scoring to filter false positives\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Boris Cherny\",\n \"email\": \"boris@anthropic.com\"\n },\n \"source\": \"./plugins/code-review\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"commit-commands\",\n \"description\": \"Commands for git commit workflows including commit, push, and PR creation\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"source\": \"./plugins/commit-commands\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"explanatory-output-style\",\n \"description\": \"Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Dickson Tsai\",\n \"email\": \"dickson@anthropic.com\"\n },\n \"source\": \"./plugins/explanatory-output-style\",\n \"category\": \"learning\"\n },\n {\n \"name\": \"feature-dev\",\n \"description\": \"Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Siddharth Bidasaria\",\n \"email\": \"sbidasaria@anthropic.com\"\n },\n \"source\": \"./plugins/feature-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"frontend-design\",\n \"description\": \"Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics.\",\n \"version\": \"1.1.0\",\n \"author\": {\n \"name\": \"Prithvi Rajasekaran & Alexander Bricken\",\n \"email\": \"prithvi@anthropic.com\"\n },\n \"source\": \"./plugins/frontend-design\",\n \"category\": \"development\"\n },\n {\n \"name\": \"hookify\",\n \"description\": \"Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. Define rules via simple markdown files.\",\n \"version\": \"0.1.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/hookify\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"learning-output-style\",\n \"description\": \"Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style)\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Boris Cherny\",\n \"email\": \"boris@anthropic.com\"\n },\n \"source\": \"./plugins/learning-output-style\",\n \"category\": \"learning\"\n },\n {\n \"name\": \"plugin-dev\",\n \"description\": \"Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.\",\n \"version\": \"0.1.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/plugin-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"pr-review-toolkit\",\n \"description\": \"Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"source\": \"./plugins/pr-review-toolkit\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"ralph-wiggum\",\n \"description\": \"Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly, seeing its previous work, until completion.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/ralph-wiggum\",\n \"category\": \"development\"\n },\n {\n \"name\": \"security-guidance\",\n \"description\": \"Security reminder hook that warns about potential security issues when editing files, including command injection, XSS, and unsafe code patterns\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"David Dworken\",\n \"email\": \"dworken@anthropic.com\"\n },\n \"source\": \"./plugins/security-guidance\",\n \"category\": \"security\"\n }\n ]\n}\n",".claude/commands/commit-push-pr.md":"---\nallowed-tools: Bash(git checkout --branch:*), Bash(git add:*), Bash(git status:*), Bash(git push:*), Bash(git commit:*), Bash(gh pr create:*)\ndescription: Commit, push, and open a PR\n---\n\n## Context\n\n- Current git status: !`git status`\n- Current git diff (staged and unstaged changes): !`git diff HEAD`\n- Current branch: !`git branch --show-current`\n\n## Your task\n\nBased on the above changes:\n1. Create a new branch if on main\n2. Create a single commit with an appropriate message\n3. Push the branch to origin\n4. Create a pull request using `gh pr create`\n5. You have the capability to call multiple tools in a single response. You MUST do all of the above in a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls.\n",".claude/commands/dedupe.md":"---\nallowed-tools: Bash(./scripts/gh.sh:*), Bash(./scripts/comment-on-duplicates.sh:*)\ndescription: Find duplicate GitHub issues\n---\n\nFind up to 3 likely duplicate issues for a given GitHub issue.\n\nTo do this, follow these steps precisely:\n\n1. Use an agent to check if the Github issue (a) is closed, (b) does not need to be deduped (eg. because it is broad product feedback without a specific solution, or positive feedback), or (c) already has a duplicates comment that you made earlier. If so, do not proceed.\n2. Use an agent to view a Github issue, and ask the agent to return a summary of the issue\n3. Then, launch 5 parallel agents to search Github for duplicates of this issue, using diverse keywords and search approaches, using the summary from #1\n4. Next, feed the results from #1 and #2 into another agent, so that it can filter out false positives, that are likely not actually duplicates of the original issue. If there are no duplicates remaining, do not proceed.\n5. Finally, use the comment script to post duplicates:\n ```\n ./scripts/comment-on-duplicates.sh --potential-duplicates \n ```\n\nNotes (be sure to tell this to your agents, too):\n\n- Use `./scripts/gh.sh` to interact with Github, rather than web fetch or raw `gh`. Examples:\n - `./scripts/gh.sh issue view 123` — view an issue\n - `./scripts/gh.sh issue view 123 --comments` — view with comments\n - `./scripts/gh.sh issue list --state open --limit 20` — list issues\n - `./scripts/gh.sh search issues \"query\" --limit 10` — search for issues\n- Do not use other tools, beyond `./scripts/gh.sh` and the comment script (eg. don't use other MCP servers, file edit, etc.)\n- Make a todo list first\n",".claude/commands/triage-issue.md":"---\nallowed-tools: Bash(./scripts/gh.sh:*),Bash(./scripts/edit-issue-labels.sh:*)\ndescription: Triage GitHub issues by analyzing and applying labels\n---\n\nYou're an issue triage assistant. Analyze the issue and manage labels.\n\nIMPORTANT: Don't post any comments or messages to the issue. Your only actions are adding or removing labels.\n\nContext:\n\n$ARGUMENTS\n\nTOOLS:\n- `./scripts/gh.sh` — wrapper for `gh` CLI. Only supports these subcommands and flags:\n - `./scripts/gh.sh label list` — fetch all available labels\n - `./scripts/gh.sh label list --limit 100` — fetch with limit\n - `./scripts/gh.sh issue view 123` — read issue title, body, and labels\n - `./scripts/gh.sh issue view 123 --comments` — read the conversation\n - `./scripts/gh.sh issue list --state open --limit 20` — list issues\n - `./scripts/gh.sh search issues \"query\"` — find similar or duplicate issues\n - `./scripts/gh.sh search issues \"query\" --limit 10` — search with limit\n- `./scripts/edit-issue-labels.sh --add-label LABEL --remove-label LABEL` — add or remove labels (issue number is read from the workflow event)\n\nTASK:\n\n1. Run `./scripts/gh.sh label list` to fetch the available labels. You may ONLY use labels from this list. Never invent new labels.\n2. Run `./scripts/gh.sh issue view ISSUE_NUMBER` to read the issue details.\n3. Run `./scripts/gh.sh issue view ISSUE_NUMBER --comments` to read the conversation.\n\n**If EVENT is \"issues\" (new issue):**\n\n4. First, check if this issue is actually about Claude Code.\n - Look for Claude Code signals in the issue BODY: a `Claude Code Version` field or `claude --version` output, references to the `claude` CLI command, terminal sessions, the VS Code/JetBrains extensions, `CLAUDE.md` files, `.claude/` directories, MCP servers, Cowork, Remote Control, or the web UI at claude.ai/code. If ANY such signal is present, this IS a Claude Code issue — proceed to step 5.\n - Only if NO Claude Code signals are present: check whether a different Anthropic product (claude.ai chat, Claude Desktop/Mobile apps, the raw Anthropic API/SDK, or account billing with no CLI involvement) is the *subject* of the complaint, not merely mentioned for context. If so, apply `invalid` and stop. If ambiguous, proceed to step 5 WITHOUT applying `invalid`.\n - The body text is authoritative. If a form dropdown (e.g. Platform) contradicts evidence in the body, trust the body — dropdowns are often mis-selected.\n\n5. Analyze and apply category labels:\n - Type (bug, enhancement, question, etc.)\n - Technical areas and platform\n - Check for duplicates with `./scripts/gh.sh search issues`. Only mark as duplicate of OPEN issues.\n\n6. Evaluate lifecycle labels:\n - `needs-repro` (bugs only, 7 days): Bug reports without clear steps to reproduce. A good repro has specific, followable steps that someone else could use to see the same issue.\n Do NOT apply if the user already provided error messages, logs, file paths, or a description of what they did. Don't require a specific format — narrative descriptions count.\n For model behavior issues (e.g. \"Claude does X when it should do Y\"), don't require traditional repro steps — examples and patterns are sufficient.\n - `needs-info` (bugs only, 7 days): The issue needs something from the community before it can progress — e.g. error messages, versions, environment details, or answers to follow-up questions. Don't apply to questions or enhancements.\n Do NOT apply if the user already provided version, environment, and error details. If the issue just needs engineering investigation, that's not `needs-info`.\n\n Issues with these labels are automatically closed after the timeout if there's no response.\n The goal is to avoid issues lingering without a clear next step.\n\n7. Apply all selected labels:\n `./scripts/edit-issue-labels.sh --add-label \"label1\" --add-label \"label2\"`\n\n**If EVENT is \"issue_comment\" (comment on existing issue):**\n\n4. Evaluate lifecycle labels based on the full conversation:\n - If the issue has `stale` or `autoclose`, remove the label — a new human comment means the issue is still active:\n `./scripts/edit-issue-labels.sh --remove-label \"stale\" --remove-label \"autoclose\"`\n - If the issue has `needs-repro` or `needs-info` and the missing information has now been provided, remove the label:\n `./scripts/edit-issue-labels.sh --remove-label \"needs-repro\"`\n - If the issue doesn't have lifecycle labels but clearly needs them (e.g., a maintainer asked for repro steps or more details), add the appropriate label.\n - Comments like \"+1\", \"me too\", \"same here\", or emoji reactions are NOT the missing information. Only remove `needs-repro` or `needs-info` when substantive details are actually provided.\n - Do NOT add or remove category labels (bug, enhancement, etc.) on comment events.\n\nGUIDELINES:\n- ONLY use labels from `./scripts/gh.sh label list` — never create or guess label names\n- DO NOT post any comments to the issue\n- Be conservative with lifecycle labels — only apply when clearly warranted\n- Only apply lifecycle labels (`needs-repro`, `needs-info`) to bugs — never to questions or enhancements\n- When in doubt, don't apply a lifecycle label — false positives are worse than missing labels\n- On new issues (EVENT \"issues\"), always apply exactly one of `bug`, `enhancement`, `question`, `invalid`, or `duplicate`. If unsure, pick the closest fit — an imperfect category label is better than none.\n- On comment events, it's okay to make no changes if nothing applies.\n","CLAUDE.md":"# CLAUDE.md\n\nGuidance for Claude Code and other coding agents working in this repository.\n\n## Security hardening for GitHub Actions\n\nWorkflow jobs in this repository that call Claude run with three protections.\nKeep them when you add or edit a workflow.\n\n1. **Egress-firewall runner.** The job has `runs-on: ubuntu-24.04-firewall`,\n a GitHub-hosted runner that filters the job's outbound network traffic. Do\n not move a job that calls Claude to another runner.\n2. **Network allow list.** `.github/egress-firewall.yaml` lists the hosts\n those jobs may reach, besides any that GitHub's firewall allows by default.\n Keep `mode: enforce`, which is what makes the firewall block the rest. Follow\n that file's header when you add a host.\n3. **Auto permission mode.** Every step that runs the Claude Code action\n (`uses: anthropics/claude-code-action`, or a local action with a\n `claude_args` input) passes `--permission-mode auto` in `claude_args`. A tool\n call that needs permission and that the allowed tools do not cover then runs\n only if Claude Code's safety review passes it. Allow only the tools the job\n needs, and keep any `--disallowedTools` list a step has. Use `claude-opus-4-6`\n or a newer model: on an older one Claude Code falls back to its default\n permission mode.\n\n`claude.yml` answers `@claude` mentions. The Claude Code action sets\n`--permission-mode acceptEdits` for those, and the `--permission-mode auto` in\nthe workflow's `claude_args`, which comes after it, replaces it.\n\n`.github/workflows/workflow-hardening.yml` fails when a job that runs the Claude\nCode action or mentions `ANTHROPIC_FEDERATION_RULE_ID` breaks protection 1 or 3,\nor when the allow list is missing, empty, not `mode: enforce`, or names a host\nwith `*`. It cannot see a job that calls Claude another way, so check new\nworkflows by hand too. If a job cannot meet protection 1 or 3, add it with the\nreason to the matching exemption table in\n`.github/scripts/check_workflow_hardening.py`. A job in `EXEMPT_FROM_AUTO_MODE`\nmust set no permission mode at all. Do not skip or weaken the check.\n\nKeep each workflow's `permissions:` block minimal, and never print tokens or\nenvironment variables in workflow logs.\n","mods/agents-md/.claude-plugin/plugin.json":"","mods/diff/.claude-plugin/plugin.json":"","mods/sec-default/.claude-plugin/plugin.json":"","mods/telemetry/.claude-plugin/plugin.json":"","plugins/README.md":"","plugins/agent-sdk-dev/.claude-plugin/plugin.json":"","plugins/agent-sdk-dev/README.md":"","plugins/claude-opus-4-5-migration/.claude-plugin/plugin.json":"","plugins/claude-opus-4-5-migration/README.md":"","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/SKILL.md":"---\nname: claude-opus-4-5-migration\ndescription: Migrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5. Use when the user wants to update their codebase, prompts, or API calls to use Opus 4.5. Handles model string updates and prompt adjustments for known Opus 4.5 behavioral differences. Does NOT migrate Haiku 4.5.\n---\n\n# Opus 4.5 Migration Guide\n\nOne-shot migration from Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5.\n\n## Migration Workflow\n\n1. Search codebase for model strings and API calls\n2. Update model strings to Opus 4.5 (see platform-specific strings below)\n3. Remove unsupported beta headers\n4. Add effort parameter set to `\"high\"` (see `references/effort.md`)\n5. Summarize all changes made\n6. Tell the user: \"If you encounter any issues with Opus 4.5, let me know and I can help adjust your prompts.\"\n\n## Model String Updates\n\nIdentify which platform the codebase uses, then replace model strings accordingly.\n\n### Unsupported Beta Headers\n\nRemove the `context-1m-2025-08-07` beta header if present—it is not yet supported with Opus 4.5. Leave a comment noting this:\n\n```python\n# Note: 1M context beta (context-1m-2025-08-07) not yet supported with Opus 4.5\n```\n\n### Target Model Strings (Opus 4.5)\n\n| Platform | Opus 4.5 Model String |\n|----------|----------------------|\n| Anthropic API (1P) | `claude-opus-4-5-20251101` |\n| AWS Bedrock | `anthropic.claude-opus-4-5-20251101-v1:0` |\n| Google Vertex AI | `claude-opus-4-5@20251101` |\n| Azure AI Foundry | `claude-opus-4-5-20251101` |\n\n### Source Model Strings to Replace\n\n| Source Model | Anthropic API (1P) | AWS Bedrock | Google Vertex AI |\n|--------------|-------------------|-------------|------------------|\n| Sonnet 4.0 | `claude-sonnet-4-20250514` | `anthropic.claude-sonnet-4-20250514-v1:0` | `claude-sonnet-4@20250514` |\n| Sonnet 4.5 | `claude-sonnet-4-5-20250929` | `anthropic.claude-sonnet-4-5-20250929-v1:0` | `claude-sonnet-4-5@20250929` |\n| Opus 4.1 | `claude-opus-4-1-20250422` | `anthropic.claude-opus-4-1-20250422-v1:0` | `claude-opus-4-1@20250422` |\n\n**Do NOT migrate**: Any Haiku models (e.g., `claude-haiku-4-5-20251001`).\n\n## Prompt Adjustments\n\nOpus 4.5 has known behavioral differences from previous models. **Only apply these fixes if the user explicitly requests them or reports a specific issue.** By default, just update model strings.\n\n**Integration guidelines**: When adding snippets, don't just append them to prompts. Integrate them thoughtfully:\n- Use XML tags (e.g., ``, ``) to organize additions\n- Match the style and structure of the existing prompt\n- Place snippets in logical locations (e.g., coding guidelines near other coding instructions)\n- If the prompt already uses XML tags, add new content within appropriate existing tags or create consistent new ones\n\n### 1. Tool Overtriggering\n\nOpus 4.5 is more responsive to system prompts. Aggressive language that prevented undertriggering on previous models may now cause overtriggering.\n\n**Apply if**: User reports tools being called too frequently or unnecessarily.\n\n**Find and soften**:\n- `CRITICAL:` → remove or soften\n- `You MUST...` → `You should...`\n- `ALWAYS do X` → `Do X`\n- `NEVER skip...` → `Don't skip...`\n- `REQUIRED` → remove or soften\n\nOnly apply to tool-triggering instructions. Leave other uses of emphasis alone.\n\n### 2. Over-Engineering Prevention\n\nOpus 4.5 tends to create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**Apply if**: User reports unwanted files, excessive abstraction, or unrequested features. Add the snippet from `references/prompt-snippets.md`.\n\n### 3. Code Exploration\n\nOpus 4.5 can be overly conservative about exploring code, proposing solutions without reading files.\n\n**Apply if**: User reports the model proposing fixes without inspecting relevant code. Add the snippet from `references/prompt-snippets.md`.\n\n### 4. Frontend Design\n\n**Apply if**: User requests improved frontend design quality or reports generic-looking outputs.\n\nAdd the frontend aesthetics snippet from `references/prompt-snippets.md`.\n\n### 5. Thinking Sensitivity\n\nWhen extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants. Extended thinking is enabled only if the API request contains a `thinking` parameter.\n\n**Apply if**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in request).\n\nReplace \"think\" with alternatives like \"consider,\" \"believe,\" or \"evaluate.\"\n\n## Reference\n\nSee `references/prompt-snippets.md` for the full text of each snippet to add.\n\nSee `references/effort.md` for configuring the effort parameter (only if user requests it).\n","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/effort.md":"# Effort Parameter (Beta)\n\n**Add effort set to `\"high\"` during migration.** This is the default configuration for best performance with Opus 4.5.\n\n## Overview\n\nEffort controls how eagerly Claude spends tokens. It affects all tokens: thinking, text responses, and function calls.\n\n| Effort | Use Case |\n|--------|----------|\n| `high` | Best performance, deep reasoning (default) |\n| `medium` | Balance of cost/latency vs. performance |\n| `low` | Simple, high-volume queries; significant token savings |\n\n## Implementation\n\nRequires beta flag `effort-2025-11-24` in API calls.\n\n**Python SDK:**\n```python\nresponse = client.messages.create(\n model=\"claude-opus-4-5-20251101\",\n max_tokens=1024,\n betas=[\"effort-2025-11-24\"],\n output_config={\n \"effort\": \"high\" # or \"medium\" or \"low\"\n },\n messages=[...]\n)\n```\n\n**TypeScript SDK:**\n```typescript\nconst response = await client.messages.create({\n model: \"claude-opus-4-5-20251101\",\n max_tokens: 1024,\n betas: [\"effort-2025-11-24\"],\n output_config: {\n effort: \"high\" // or \"medium\" or \"low\"\n },\n messages: [...]\n});\n```\n\n**Raw API:**\n```json\n{\n \"model\": \"claude-opus-4-5-20251101\",\n \"max_tokens\": 1024,\n \"anthropic-beta\": \"effort-2025-11-24\",\n \"output_config\": {\n \"effort\": \"high\"\n },\n \"messages\": [...]\n}\n```\n\n## Effort vs. Thinking Budget\n\nEffort is independent of thinking budget:\n\n- High effort + no thinking = more tokens, but no thinking tokens\n- High effort + 32k thinking = more tokens, but thinking capped at 32k\n\n## Recommendations\n\n1. First determine effort level, then set thinking budget\n2. Best performance: high effort + high thinking budget\n3. Cost/latency optimization: medium effort\n4. Simple high-volume queries: low effort\n","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/prompt-snippets.md":"# Prompt Snippets for Opus 4.5\n\nOnly apply these snippets if the user explicitly requests them or reports a specific issue. By default, the migration should only update model strings.\n\n## 1. Tool Overtriggering\n\n**Problem**: Prompts designed to reduce undertriggering on previous models may cause Opus 4.5 to overtrigger.\n\n**When to add**: User reports tools being called too frequently or unnecessarily.\n\n**Solution**: Replace aggressive language with normal phrasing.\n\n| Before | After |\n|--------|-------|\n| `CRITICAL: You MUST use this tool when...` | `Use this tool when...` |\n| `ALWAYS call the search function before...` | `Call the search function before...` |\n| `You are REQUIRED to...` | `You should...` |\n| `NEVER skip this step` | `Don't skip this step` |\n\n## 2. Over-Engineering Prevention\n\n**Problem**: Opus 4.5 may create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**When to add**: User reports unwanted files, excessive abstraction, or unrequested features.\n\n**Snippet to add to system prompt**:\n\n```\n- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.\n- Don't add features, refactor code, or make \"improvements\" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.\n- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.\n- Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.\n```\n\n## 3. Code Exploration\n\n**Problem**: Opus 4.5 may propose solutions without reading code or make assumptions about unread files.\n\n**When to add**: User reports the model proposing fixes without inspecting relevant code.\n\n**Snippet to add to system prompt**:\n\n```\nALWAYS read and understand relevant files before proposing code edits. Do not speculate about code you have not inspected. If the user references a specific file/path, you MUST open and inspect it before explaining or proposing fixes. Be rigorous and persistent in searching code for key facts. Thoroughly review the style, conventions, and abstractions of the codebase before implementing new features or abstractions.\n```\n\n## 4. Frontend Design Quality\n\n**Problem**: Default frontend outputs may look generic (\"AI slop\" aesthetic).\n\n**When to add**: User requests improved frontend design quality or reports generic-looking outputs.\n\n**Snippet to add to system prompt**:\n\n```xml\n\nYou tend to converge toward generic, \"on distribution\" outputs. In frontend design, this creates what users call the \"AI slop\" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight.\n\nFocus on:\n- Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.\n- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.\n- Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.\n- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.\n\nAvoid generic AI-generated aesthetics:\n- Overused font families (Inter, Roboto, Arial, system fonts)\n- Clichéd color schemes (particularly purple gradients on white backgrounds)\n- Predictable layouts and component patterns\n- Cookie-cutter design that lacks context-specific character\n\nInterpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!\n\n```\n\n## 5. Thinking Sensitivity\n\n**Problem**: When extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants.\n\nExtended thinking is not enabled by default. It is only enabled if the API request contains a `thinking` parameter:\n```json\n\"thinking\": {\n \"type\": \"enabled\",\n \"budget_tokens\": 10000\n}\n```\n\n**When to apply**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in their request).\n\n**Solution**: Replace \"think\" with alternative words.\n\n| Before | After |\n|--------|-------|\n| `think about` | `consider` |\n| `think through` | `evaluate` |\n| `I think` | `I believe` |\n| `think carefully` | `consider carefully` |\n| `thinking` | `reasoning` / `considering` |\n\n## Usage Guidelines\n\n1. **Integrate thoughtfully** - Don't just append snippets; weave them into the existing prompt structure\n2. **Use XML tags** - Wrap additions in descriptive tags (e.g., ``, ``) that match or complement existing prompt structure\n3. **Match prompt style** - If the prompt is concise, trim the snippet; if verbose, keep full detail\n4. **Place logically** - Put coding snippets near other coding instructions, tool guidance near tool definitions, etc.\n5. **Preserve existing content** - Insert snippets without removing functional content\n6. **Summarize changes** - After migration, list all model string updates and prompt modifications made\n","plugins/code-review/.claude-plugin/plugin.json":"","plugins/code-review/README.md":"","plugins/commit-commands/.claude-plugin/plugin.json":"","plugins/commit-commands/README.md":"","plugins/explanatory-output-style/.claude-plugin/plugin.json":"","plugins/explanatory-output-style/README.md":"","plugins/feature-dev/.claude-plugin/plugin.json":"","plugins/feature-dev/README.md":"","plugins/frontend-design/.claude-plugin/plugin.json":"","plugins/frontend-design/README.md":"","plugins/frontend-design/skills/frontend-design/SKILL.md":"---\nname: frontend-design\ndescription: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.\nlicense: Complete terms in LICENSE.txt\n---\n\n# Frontend Design\n\nApproach this as the design lead at a design studio known for giving every client a distinct visual identity that is not mistaken for anyone else's. This client has already rejected proposals that felt cliché or templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take aesthetic risk if justified.\n\n## Ground your designs in the subject matter\n\nIf the brief does not identify what the product or subject matter is, identify it yourself before designing, and confirm with the client. You can come up with one concrete subject, the design's audience, and the design's primary job, as a proposal. If there's any information in your memory about the client's preferences or context about what they're building, use that as a hint. The subject's industry, subject matter, materials, and vernacular are where distinctive visual choices come from — a design for a toy for girls aged 8–11 will be very aesthetically different from a dashboard for financial analysts. Build with the brief's real content and subject matter throughout.\n\n## Design principles\n\nFor web designs, the hero is the first thing viewers will see. Open with the most characteristic thing in the subject's world, in the form that is most appropriate: a headline, an image, an animation, a live demo, an interactive moment, or other treatments. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the default treatment, so only use it if that's truly the best option.\n\nTypography carries the personality of the page. You don't need a different typeface for display or headline text and body content: use one family or two, and if two, make them clearly distinct.\n\nChoose your typefaces deliberately, not the default families you would reach for on any other project, and set a clear type scale following the default guidance of The Elements of Typographic Style with intentional weights, widths, and spacing. When type is used as a headline or visual element, use the type treatment itself as an active part of the design, not a neutral delivery vehicle for the content.\n\nDefault to line lengths of less than 80 characters. Serif typefaces can have slightly longer line lengths; give serif body text slightly more line-height than a sans-serif.\n\nAvoid these default typographic treatments; they are the commonest tells of a generated page:\n- Accenting just a single word or phrase in a headline, like putting one word in italic/bold or a different color.\n- Using all caps for labels.\n- Adding unnecessary typographic labels above content.\n\nVisual structure is information. Structural devices like outlines, borders, numbering, eyebrows, dividers, labels, etc., encode useful information about the content rather than decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence — like a stepped process or a timeline. Before adding numbered markers, check the content really is a sequence.\n\nUse non-user-triggered motion sparingly and deliberately, only to draw attention. A single orchestrated moment — one page-load sequence or one reveal — lands better than scattered effects; fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as AI-generated. Motion that answers a person's action (opening, expanding, confirming) is welcome when it shows what changed.\n\nConsider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy and placeholder content. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.\n\n## Process: plan, review against the brief, build, critique\n\nFor calibration, AI-generated design right now clusters around some traits:\n1. a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta or warm-clay accent (often near #D97757 — Anthropic's own Claude-interaction accent, so on a user's brief it reads as a tell);\n2. a near-black background with a single bright acid-green or vermilion accent;\n3. a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns;\n4. the SaaS-card kit: content chopped into identical rounded cards, one border-radius on everything regardless of hierarchy, the same soft grey shadow (rgba(0,0,0,.1)) under each, and gradient washes as decoration;\n5. template chrome that appears whatever the subject: a tracked-out ALL-CAPS eyebrow label above every heading; meta strings joined with middle dots ('A · B · C'); labels built as 'WORD — fragment' with a spaced em dash; tinted near-black (#0B0B0B, #111) standing in for black; a monospace face for small data labels; a '→' appended to link and button text.\n\nAll traits are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. As with a hired human designer, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.\n\nWork in two passes. First, brainstorm a short design plan based on the client's design brief: create a compact token system with color, type, layout, and principles.\n- Color: describe the core base palette as 4–6 named hex values.\n- Type: the typefaces and their roles.\n- Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Include alignment guidance; should the content be left aligned, center aligned, justified?\n- Principles: the high-level guidance for what makes this page unique.\n\nThen review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan.\n\nWhen writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and an element-based selector like .cta). This can happen often with padding/margin between sections.\n\n## Restraint and self-critique\n\nSpend your boldness in one place. Let one element be the memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected, visually accessible, harmonious color palettes. Critique your own work as you build, taking screenshots to review if your environment supports it — a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creatives have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.\n\n## More on writing in design\n\nWords appear in a design for one reason: to make it easier to understand and use. They are design content, not decoration. Bring the same intentionality and minimalism to copywriting that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.\n\nWrite from the end user's perspective. Name things by what users will understand in simple language, not by how the system is built. A user manages notifications, not webhook config. Describe what something is or does in plain terms rather than selling it. Being specific and legible to new users is always better than being clever.\n\nUse active voice as default. A CTA says exactly what happens when it is used: \"Save changes,\" not \"Submit.\" An action keeps the same name through the whole flow, so the button that says \"Publish\" produces a toast that says \"Published.\" The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.\n\nTreat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.\n\nKeep the tone conversational: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each written element do exactly one job.\n","plugins/hookify/.claude-plugin/plugin.json":"","plugins/hookify/README.md":"","plugins/hookify/skills/writing-rules/SKILL.md":"---\nname: Writing Hookify Rules\ndescription: This skill should be used when the user asks to \"create a hookify rule\", \"write a hook rule\", \"configure hookify\", \"add a hookify rule\", or needs guidance on hookify rule syntax and patterns.\nversion: 0.1.0\n---\n\n# Writing Hookify Rules\n\n## Overview\n\nHookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to show when those patterns match. Rules are stored in `.claude/hookify.{rule-name}.local.md` files.\n\n## Rule File Format\n\n### Basic Structure\n\n```markdown\n---\nname: rule-identifier\nenabled: true\nevent: bash|file|stop|prompt|all\npattern: regex-pattern-here\n---\n\nMessage to show Claude when this rule triggers.\nCan include markdown formatting, warnings, suggestions, etc.\n```\n\n### Frontmatter Fields\n\n**name** (required): Unique identifier for the rule\n- Use kebab-case: `warn-dangerous-rm`, `block-console-log`\n- Be descriptive and action-oriented\n- Start with verb: warn, prevent, block, require, check\n\n**enabled** (required): Boolean to activate/deactivate\n- `true`: Rule is active\n- `false`: Rule is disabled (won't trigger)\n- Can toggle without deleting rule\n\n**event** (required): Which hook event to trigger on\n- `bash`: Bash tool commands\n- `file`: Edit, Write, MultiEdit tools\n- `stop`: When agent wants to stop\n- `prompt`: When user submits a prompt\n- `all`: All events\n\n**action** (optional): What to do when rule matches\n- `warn`: Show message but allow operation (default)\n- `block`: Prevent operation (PreToolUse) or stop session (Stop events)\n- If omitted, defaults to `warn`\n\n**pattern** (simple format): Regex pattern to match\n- Used for simple single-condition rules\n- Matches against command (bash) or new_text (file)\n- Python regex syntax\n\n**Example:**\n```yaml\nevent: bash\npattern: rm\\s+-rf\n```\n\n### Advanced Format (Multiple Conditions)\n\nFor complex rules with multiple conditions:\n\n```markdown\n---\nname: warn-env-file-edits\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.env$\n - field: new_text\n operator: contains\n pattern: API_KEY\n---\n\nYou're adding an API key to a .env file. Ensure this file is in .gitignore!\n```\n\n**Condition fields:**\n- `field`: Which field to check\n - For bash: `command`\n - For file: `file_path`, `new_text`, `old_text`, `content`\n- `operator`: How to match\n - `regex_match`: Regex pattern matching\n - `contains`: Substring check\n - `equals`: Exact match\n - `not_contains`: Substring must NOT be present\n - `starts_with`: Prefix check\n - `ends_with`: Suffix check\n- `pattern`: Pattern or string to match\n\n**All conditions must match for rule to trigger.**\n\n## Message Body\n\nThe markdown content after frontmatter is shown to Claude when the rule triggers.\n\n**Good messages:**\n- Explain what was detected\n- Explain why it's problematic\n- Suggest alternatives or best practices\n- Use formatting for clarity (bold, lists, etc.)\n\n**Example:**\n```markdown\n⚠️ **Console.log detected!**\n\nYou're adding console.log to production code.\n\n**Why this matters:**\n- Debug logs shouldn't ship to production\n- Console.log can expose sensitive data\n- Impacts browser performance\n\n**Alternatives:**\n- Use a proper logging library\n- Remove before committing\n- Use conditional debug builds\n```\n\n## Event Type Guide\n\n### bash Events\n\nMatch Bash command patterns:\n\n```markdown\n---\nevent: bash\npattern: sudo\\s+|rm\\s+-rf|chmod\\s+777\n---\n\nDangerous command detected!\n```\n\n**Common patterns:**\n- Dangerous commands: `rm\\s+-rf`, `dd\\s+if=`, `mkfs`\n- Privilege escalation: `sudo\\s+`, `su\\s+`\n- Permission issues: `chmod\\s+777`, `chown\\s+root`\n\n### file Events\n\nMatch Edit/Write/MultiEdit operations:\n\n```markdown\n---\nevent: file\npattern: console\\.log\\(|eval\\(|innerHTML\\s*=\n---\n\nPotentially problematic code pattern detected!\n```\n\n**Match on different fields:**\n```markdown\n---\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.tsx?$\n - field: new_text\n operator: regex_match\n pattern: console\\.log\\(\n---\n\nConsole.log in TypeScript file!\n```\n\n**Common patterns:**\n- Debug code: `console\\.log\\(`, `debugger`, `print\\(`\n- Security risks: `eval\\(`, `innerHTML\\s*=`, `dangerouslySetInnerHTML`\n- Sensitive files: `\\.env$`, `credentials`, `\\.pem$`\n- Generated files: `node_modules/`, `dist/`, `build/`\n\n### stop Events\n\nMatch when agent wants to stop (completion checks):\n\n```markdown\n---\nevent: stop\npattern: .*\n---\n\nBefore stopping, verify:\n- [ ] Tests were run\n- [ ] Build succeeded\n- [ ] Documentation updated\n```\n\n**Use for:**\n- Reminders about required steps\n- Completion checklists\n- Process enforcement\n\n### prompt Events\n\nMatch user prompt content (advanced):\n\n```markdown\n---\nevent: prompt\nconditions:\n - field: user_prompt\n operator: contains\n pattern: deploy to production\n---\n\nProduction deployment checklist:\n- [ ] Tests passing?\n- [ ] Reviewed by team?\n- [ ] Monitoring ready?\n```\n\n## Pattern Writing Tips\n\n### Regex Basics\n\n**Literal characters:** Most characters match themselves\n- `rm` matches \"rm\"\n- `console.log` matches \"console.log\"\n\n**Special characters need escaping:**\n- `.` (any char) → `\\.` (literal dot)\n- `(` `)` → `\\(` `\\)` (literal parens)\n- `[` `]` → `\\[` `\\]` (literal brackets)\n\n**Common metacharacters:**\n- `\\s` - whitespace (space, tab, newline)\n- `\\d` - digit (0-9)\n- `\\w` - word character (a-z, A-Z, 0-9, _)\n- `.` - any character\n- `+` - one or more\n- `*` - zero or more\n- `?` - zero or one\n- `|` - OR\n\n**Examples:**\n```\nrm\\s+-rf Matches: rm -rf, rm -rf\nconsole\\.log\\( Matches: console.log(\n(eval|exec)\\( Matches: eval( or exec(\nchmod\\s+777 Matches: chmod 777, chmod 777\nAPI_KEY\\s*= Matches: API_KEY=, API_KEY =\n```\n\n### Testing Patterns\n\nTest regex patterns before using:\n\n```bash\npython3 -c \"import re; print(re.search(r'your_pattern', 'test text'))\"\n```\n\nOr use online regex testers (regex101.com with Python flavor).\n\n### Common Pitfalls\n\n**Too broad:**\n```yaml\npattern: log # Matches \"log\", \"login\", \"dialog\", \"catalog\"\n```\nBetter: `console\\.log\\(|logger\\.`\n\n**Too specific:**\n```yaml\npattern: rm -rf /tmp # Only matches exact path\n```\nBetter: `rm\\s+-rf`\n\n**Escaping issues:**\n- YAML quoted strings: `\"pattern\"` requires double backslashes `\\\\s`\n- YAML unquoted: `pattern: \\s` works as-is\n- **Recommendation**: Use unquoted patterns in YAML\n\n## File Organization\n\n**Location:** All rules in `.claude/` directory\n**Naming:** `.claude/hookify.{descriptive-name}.local.md`\n**Gitignore:** Add `.claude/*.local.md` to `.gitignore`\n\n**Good names:**\n- `hookify.dangerous-rm.local.md`\n- `hookify.console-log.local.md`\n- `hookify.require-tests.local.md`\n- `hookify.sensitive-files.local.md`\n\n**Bad names:**\n- `hookify.rule1.local.md` (not descriptive)\n- `hookify.md` (missing .local)\n- `danger.local.md` (missing hookify prefix)\n\n## Workflow\n\n### Creating a Rule\n\n1. Identify unwanted behavior\n2. Determine which tool is involved (Bash, Edit, etc.)\n3. Choose event type (bash, file, stop, etc.)\n4. Write regex pattern\n5. Create `.claude/hookify.{name}.local.md` file in project root\n6. Test immediately - rules are read dynamically on next tool use\n\n### Refining a Rule\n\n1. Edit the `.local.md` file\n2. Adjust pattern or message\n3. Test immediately - changes take effect on next tool use\n\n### Disabling a Rule\n\n**Temporary:** Set `enabled: false` in frontmatter\n**Permanent:** Delete the `.local.md` file\n\n## Examples\n\nSee `${CLAUDE_PLUGIN_ROOT}/examples/` for complete examples:\n- `dangerous-rm.local.md` - Block dangerous rm commands\n- `console-log-warning.local.md` - Warn about console.log\n- `sensitive-files-warning.local.md` - Warn about editing .env files\n\n## Quick Reference\n\n**Minimum viable rule:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: bash\npattern: dangerous_command\n---\n\nWarning message here\n```\n\n**Rule with conditions:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.ts$\n - field: new_text\n operator: contains\n pattern: any\n---\n\nWarning message\n```\n\n**Event types:**\n- `bash` - Bash commands\n- `file` - File edits\n- `stop` - Completion checks\n- `prompt` - User input\n- `all` - All events\n\n**Field options:**\n- Bash: `command`\n- File: `file_path`, `new_text`, `old_text`, `content`\n- Prompt: `user_prompt`\n\n**Operators:**\n- `regex_match`, `contains`, `equals`, `not_contains`, `starts_with`, `ends_with`\n","plugins/learning-output-style/.claude-plugin/plugin.json":"","plugins/learning-output-style/README.md":"","plugins/plugin-dev/README.md":"","plugins/plugin-dev/skills/agent-development/SKILL.md":"---\nname: Agent Development\ndescription: This skill should be used when the user asks to \"create an agent\", \"add an agent\", \"write a subagent\", \"agent frontmatter\", \"when to use description\", \"agent examples\", \"agent tools\", \"agent colors\", \"autonomous agent\", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.\nversion: 0.1.0\n---\n\n# Agent Development for Claude Code Plugins\n\n## Overview\n\nAgents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.\n\n**Key concepts:**\n- Agents are FOR autonomous work, commands are FOR user-initiated actions\n- Markdown file format with YAML frontmatter\n- Triggering via description field with examples\n- System prompt defines agent behavior\n- Model and color customization\n\n## Agent File Structure\n\n### Complete Format\n\n```markdown\n---\nname: agent-identifier\ndescription: Use this agent when [triggering conditions]. Examples:\n\n\nContext: [Situation description]\nuser: \"[User request]\"\nassistant: \"[How assistant should respond and use this agent]\"\n\n[Why this agent should be triggered]\n\n\n\n\n[Additional example...]\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Write\", \"Grep\"]\n---\n\nYou are [agent role description]...\n\n**Your Core Responsibilities:**\n1. [Responsibility 1]\n2. [Responsibility 2]\n\n**Analysis Process:**\n[Step-by-step workflow]\n\n**Output Format:**\n[What to return]\n```\n\n## Frontmatter Fields\n\n### name (required)\n\nAgent identifier used for namespacing and invocation.\n\n**Format:** lowercase, numbers, hyphens only\n**Length:** 3-50 characters\n**Pattern:** Must start and end with alphanumeric\n\n**Good examples:**\n- `code-reviewer`\n- `test-generator`\n- `api-docs-writer`\n- `security-analyzer`\n\n**Bad examples:**\n- `helper` (too generic)\n- `-agent-` (starts/ends with hyphen)\n- `my_agent` (underscores not allowed)\n- `ag` (too short, < 3 chars)\n\n### description (required)\n\nDefines when Claude should trigger this agent. **This is the most critical field.**\n\n**Must include:**\n1. Triggering conditions (\"Use this agent when...\")\n2. Multiple `` blocks showing usage\n3. Context, user request, and assistant response in each example\n4. `` explaining why agent triggers\n\n**Format:**\n```\nUse this agent when [conditions]. Examples:\n\n\nContext: [Scenario description]\nuser: \"[What user says]\"\nassistant: \"[How Claude should respond]\"\n\n[Why this agent is appropriate]\n\n\n\n[More examples...]\n```\n\n**Best practices:**\n- Include 2-4 concrete examples\n- Show proactive and reactive triggering\n- Cover different phrasings of same intent\n- Explain reasoning in commentary\n- Be specific about when NOT to use the agent\n\n### model (required)\n\nWhich model the agent should use.\n\n**Options:**\n- `inherit` - Use same model as parent (recommended)\n- `sonnet` - Claude Sonnet (balanced)\n- `opus` - Claude Opus (most capable, expensive)\n- `haiku` - Claude Haiku (fast, cheap)\n\n**Recommendation:** Use `inherit` unless agent needs specific model capabilities.\n\n### color (required)\n\nVisual identifier for agent in UI.\n\n**Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`\n\n**Guidelines:**\n- Choose distinct colors for different agents in same plugin\n- Use consistent colors for similar agent types\n- Blue/cyan: Analysis, review\n- Green: Success-oriented tasks\n- Yellow: Caution, validation\n- Red: Critical, security\n- Magenta: Creative, generation\n\n### tools (optional)\n\nRestrict agent to specific tools.\n\n**Format:** Array of tool names\n\n```yaml\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n```\n\n**Default:** If omitted, agent has access to all tools\n\n**Best practice:** Limit tools to minimum needed (principle of least privilege)\n\n**Common tool sets:**\n- Read-only analysis: `[\"Read\", \"Grep\", \"Glob\"]`\n- Code generation: `[\"Read\", \"Write\", \"Grep\"]`\n- Testing: `[\"Read\", \"Bash\", \"Grep\"]`\n- Full access: Omit field or use `[\"*\"]`\n\n## System Prompt Design\n\nThe markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.\n\n### Structure\n\n**Standard template:**\n```markdown\nYou are [role] specializing in [domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility]\n2. [Secondary responsibility]\n3. [Additional responsibilities...]\n\n**Analysis Process:**\n1. [Step one]\n2. [Step two]\n3. [Step three]\n[...]\n\n**Quality Standards:**\n- [Standard 1]\n- [Standard 2]\n\n**Output Format:**\nProvide results in this format:\n- [What to include]\n- [How to structure]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [How to handle]\n- [Edge case 2]: [How to handle]\n```\n\n### Best Practices\n\n✅ **DO:**\n- Write in second person (\"You are...\", \"You will...\")\n- Be specific about responsibilities\n- Provide step-by-step process\n- Define output format\n- Include quality standards\n- Address edge cases\n- Keep under 10,000 characters\n\n❌ **DON'T:**\n- Write in first person (\"I am...\", \"I will...\")\n- Be vague or generic\n- Omit process steps\n- Leave output format undefined\n- Skip quality guidance\n- Ignore error cases\n\n## Creating Agents\n\n### Method 1: AI-Assisted Generation\n\nUse this prompt pattern (extracted from Claude Code):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nRequirements:\n1. Extract core intent and responsibilities\n2. Design expert persona for the domain\n3. Create comprehensive system prompt with:\n - Clear behavioral boundaries\n - Specific methodologies\n - Edge case handling\n - Output format\n4. Create identifier (lowercase, hyphens, 3-50 chars)\n5. Write description with triggering conditions\n6. Include 2-3 blocks showing when to use\n\nReturn JSON with:\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are...\"\n}\n```\n\nThen convert to agent file format with frontmatter.\n\nSee `examples/agent-creation-prompt.md` for complete template.\n\n### Method 2: Manual Creation\n\n1. Choose agent identifier (3-50 chars, lowercase, hyphens)\n2. Write description with examples\n3. Select model (usually `inherit`)\n4. Choose color for visual identification\n5. Define tools (if restricting access)\n6. Write system prompt with structure above\n7. Save as `agents/agent-name.md`\n\n## Validation Rules\n\n### Identifier Validation\n\n```\n✅ Valid: code-reviewer, test-gen, api-analyzer-v2\n❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)\n```\n\n**Rules:**\n- 3-50 characters\n- Lowercase letters, numbers, hyphens only\n- Must start and end with alphanumeric\n- No underscores, spaces, or special characters\n\n### Description Validation\n\n**Length:** 10-5,000 characters\n**Must include:** Triggering conditions and examples\n**Best:** 200-1,000 characters with 2-4 examples\n\n### System Prompt Validation\n\n**Length:** 20-10,000 characters\n**Best:** 500-3,000 characters\n**Structure:** Clear responsibilities, process, output format\n\n## Agent Organization\n\n### Plugin Agents Directory\n\n```\nplugin-name/\n└── agents/\n ├── analyzer.md\n ├── reviewer.md\n └── generator.md\n```\n\nAll `.md` files in `agents/` are auto-discovered.\n\n### Namespacing\n\nAgents are namespaced automatically:\n- Single plugin: `agent-name`\n- With subdirectories: `plugin:subdir:agent-name`\n\n## Testing Agents\n\n### Test Triggering\n\nCreate test scenarios to verify agent triggers correctly:\n\n1. Write agent with specific triggering examples\n2. Use similar phrasing to examples in test\n3. Check Claude loads the agent\n4. Verify agent provides expected functionality\n\n### Test System Prompt\n\nEnsure system prompt is complete:\n\n1. Give agent typical task\n2. Check it follows process steps\n3. Verify output format is correct\n4. Test edge cases mentioned in prompt\n5. Confirm quality standards are met\n\n## Quick Reference\n\n### Minimal Agent\n\n```markdown\n---\nname: simple-agent\ndescription: Use this agent when... Examples: ...\nmodel: inherit\ncolor: blue\n---\n\nYou are an agent that [does X].\n\nProcess:\n1. [Step 1]\n2. [Step 2]\n\nOutput: [What to provide]\n```\n\n### Frontmatter Fields Summary\n\n| Field | Required | Format | Example |\n|-------|----------|--------|---------|\n| name | Yes | lowercase-hyphens | code-reviewer |\n| description | Yes | Text + examples | Use when... ... |\n| model | Yes | inherit/sonnet/opus/haiku | inherit |\n| color | Yes | Color name | blue |\n| tools | No | Array of tool names | [\"Read\", \"Grep\"] |\n\n### Best Practices\n\n**DO:**\n- ✅ Include 2-4 concrete examples in description\n- ✅ Write specific triggering conditions\n- ✅ Use `inherit` for model unless specific need\n- ✅ Choose appropriate tools (least privilege)\n- ✅ Write clear, structured system prompts\n- ✅ Test agent triggering thoroughly\n\n**DON'T:**\n- ❌ Use generic descriptions without examples\n- ❌ Omit triggering conditions\n- ❌ Give all agents same color\n- ❌ Grant unnecessary tool access\n- ❌ Write vague system prompts\n- ❌ Skip testing\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed guidance, consult:\n\n- **`references/system-prompt-design.md`** - Complete system prompt patterns\n- **`references/triggering-examples.md`** - Example formats and best practices\n- **`references/agent-creation-system-prompt.md`** - The exact prompt from Claude Code\n\n### Example Files\n\nWorking examples in `examples/`:\n\n- **`agent-creation-prompt.md`** - AI-assisted agent generation template\n- **`complete-agent-examples.md`** - Full agent examples for different use cases\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-agent.sh`** - Validate agent file structure\n- **`test-agent-trigger.sh`** - Test if agent triggers correctly\n\n## Implementation Workflow\n\nTo create an agent for a plugin:\n\n1. Define agent purpose and triggering conditions\n2. Choose creation method (AI-assisted or manual)\n3. Create `agents/agent-name.md` file\n4. Write frontmatter with all required fields\n5. Write system prompt following best practices\n6. Include 2-4 triggering examples in description\n7. Validate with `scripts/validate-agent.sh`\n8. Test triggering with real scenarios\n9. Document agent in plugin README\n\nFocus on clear triggering conditions and comprehensive system prompts for autonomous operation.\n","plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md":"# AI-Assisted Agent Generation Template\n\nUse this template to generate agents using Claude with the agent creation system prompt.\n\n## Usage Pattern\n\n### Step 1: Describe Your Agent Need\n\nThink about:\n- What task should the agent handle?\n- When should it be triggered?\n- Should it be proactive or reactive?\n- What are the key responsibilities?\n\n### Step 2: Use the Generation Prompt\n\nSend this to Claude (with the agent-creation-system-prompt loaded):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nReturn ONLY the JSON object, no other text.\n```\n\n**Replace [YOUR DESCRIPTION] with your agent requirements.**\n\n### Step 3: Claude Returns JSON\n\nClaude will return:\n\n```json\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are... **Your Core Responsibilities:**...\"\n}\n```\n\n### Step 4: Convert to Agent File\n\nCreate `agents/[identifier].md`:\n\n```markdown\n---\nname: [identifier from JSON]\ndescription: [whenToUse from JSON]\nmodel: inherit\ncolor: [choose: blue/cyan/green/yellow/magenta/red]\ntools: [\"Read\", \"Write\", \"Grep\"] # Optional: restrict tools\n---\n\n[systemPrompt from JSON]\n```\n\n## Example 1: Code Review Agent\n\n**Your request:**\n```\nI need an agent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be called after code is written and provide specific feedback.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"code-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\\n\\n\\nContext: User just implemented a new feature\\nuser: \\\"I've added the authentication feature\\\"\\nassistant: \\\"Great! Let me review the code quality.\\\"\\n\\nCode was written, trigger code-quality-reviewer agent for review.\\n\\nassistant: \\\"I'll use the code-quality-reviewer agent to analyze the changes.\\\"\\n\\n\\n\\nContext: User explicitly requests review\\nuser: \\\"Can you review my code for issues?\\\"\\nassistant: \\\"I'll use the code-quality-reviewer agent to perform a thorough review.\\\"\\n\\nExplicit review request triggers the agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer specializing in identifying issues in software implementations.\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues (readability, maintainability, performance)\\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\\n3. Check adherence to project best practices and coding standards\\n4. Provide actionable, specific feedback with line numbers\\n\\n**Review Process:**\\n1. Read the code changes using available tools\\n2. Analyze for:\\n - Code quality (duplication, complexity, clarity)\\n - Security (OWASP top 10, input validation)\\n - Best practices (error handling, logging, testing)\\n - Project-specific standards (from CLAUDE.md)\\n3. Identify issues with severity (critical/major/minor)\\n4. Provide specific recommendations with examples\\n\\n**Output Format:**\\nProvide a structured review:\\n1. Summary (2-3 sentences)\\n2. Critical Issues (must fix)\\n3. Major Issues (should fix)\\n4. Minor Issues (nice to fix)\\n5. Positive observations\\n6. Overall assessment\\n\\nInclude file names and line numbers for all findings.\"\n}\n```\n\n**You create:**\n\nFile: `agents/code-quality-reviewer.md`\n\n```markdown\n---\nname: code-quality-reviewer\ndescription: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode was written, trigger code-quality-reviewer agent for review.\n\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n - Code quality (duplication, complexity, clarity)\n - Security (OWASP top 10, input validation)\n - Best practices (error handling, logging, testing)\n - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings.\n```\n\n## Example 2: Test Generation Agent\n\n**Your request:**\n```\nCreate an agent that generates unit tests for code. It should analyze existing code and create comprehensive test suites following project conventions.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"test-generator\",\n \"whenToUse\": \"Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\\n\\n\\nContext: User wrote new functions without tests\\nuser: \\\"I've implemented the user authentication functions\\\"\\nassistant: \\\"Great! Let me generate tests for these functions.\\\"\\n\\nNew code without tests, proactively trigger test-generator.\\n\\nassistant: \\\"I'll use the test-generator agent to create comprehensive tests.\\\"\\n\",\n \"systemPrompt\": \"You are an expert test engineer specializing in creating comprehensive unit tests...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code to understand behavior\\n2. Generate test cases covering happy paths and edge cases\\n3. Follow project testing conventions\\n4. Ensure high code coverage\\n\\n**Test Generation Process:**\\n1. Read target code\\n2. Identify testable units (functions, classes, methods)\\n3. Design test cases (inputs, expected outputs, edge cases)\\n4. Generate tests following project patterns\\n5. Add assertions and error cases\\n\\n**Output Format:**\\nGenerate complete test files with:\\n- Test suite structure\\n- Setup/teardown if needed\\n- Descriptive test names\\n- Comprehensive assertions\"\n}\n```\n\n**You create:** `agents/test-generator.md` with the structure above.\n\n## Example 3: Documentation Agent\n\n**Your request:**\n```\nBuild an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs.\n```\n\n**Result:** Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation.\n\n## Tips for Effective Agent Generation\n\n### Be Specific in Your Request\n\n**Vague:**\n```\n\"I need an agent that helps with code\"\n```\n\n**Specific:**\n```\n\"I need an agent that reviews pull requests for type safety issues in TypeScript, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage\"\n```\n\n### Include Triggering Preferences\n\nTell Claude when the agent should activate:\n\n```\n\"Create an agent that generates tests. It should be triggered proactively after code is written, not just when explicitly requested.\"\n```\n\n### Mention Project Context\n\n```\n\"Create a code review agent. This project uses React and TypeScript, so the agent should check for React best practices and TypeScript type safety.\"\n```\n\n### Define Output Expectations\n\n```\n\"Create an agent that analyzes performance. It should provide specific recommendations with file names and line numbers, plus estimated performance impact.\"\n```\n\n## Validation After Generation\n\nAlways validate generated agents:\n\n```bash\n# Validate structure\n./scripts/validate-agent.sh agents/your-agent.md\n\n# Check triggering works\n# Test with scenarios from examples\n```\n\n## Iterating on Generated Agents\n\nIf generated agent needs improvement:\n\n1. Identify what's missing or wrong\n2. Manually edit the agent file\n3. Focus on:\n - Better examples in description\n - More specific system prompt\n - Clearer process steps\n - Better output format definition\n4. Re-validate\n5. Test again\n\n## Advantages of AI-Assisted Generation\n\n- **Comprehensive**: Claude includes edge cases and quality checks\n- **Consistent**: Follows proven patterns\n- **Fast**: Seconds vs manual writing\n- **Examples**: Auto-generates triggering examples\n- **Complete**: Provides full system prompt structure\n\n## When to Edit Manually\n\nEdit generated agents when:\n- Need very specific project patterns\n- Require custom tool combinations\n- Want unique persona or style\n- Integrating with existing agents\n- Need precise triggering conditions\n\nStart with generation, then refine manually for best results.\n","plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md":"# Complete Agent Examples\n\nFull, production-ready agent examples for common use cases. Use these as templates for your own agents.\n\n## Example 1: Code Review Agent\n\n**File:** `agents/code-reviewer.md`\n\n```markdown\n---\nname: code-reviewer\ndescription: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the payment processing feature\"\nassistant: \"Great! Let me review the implementation.\"\n\nCode written for payment processing (security-critical). Proactively trigger\ncode-reviewer agent to check for security issues and best practices.\n\nassistant: \"I'll use the code-reviewer agent to analyze the payment code.\"\n\n\n\nContext: User explicitly requests code review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a comprehensive review.\"\n\nExplicit code review request triggers the agent.\n\n\n\n\nContext: Before committing code\nuser: \"I'm ready to commit these changes\"\nassistant: \"Let me review them first.\"\n\nBefore commit, proactively review code quality.\n\nassistant: \"I'll use the code-reviewer agent to validate the changes.\"\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, complexity)\n2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.)\n3. Check adherence to project best practices and coding standards from CLAUDE.md\n4. Provide specific, actionable feedback with file and line number references\n5. Recognize and commend good practices\n\n**Code Review Process:**\n1. **Gather Context**: Use Glob to find recently modified files (git diff, git status)\n2. **Read Code**: Use Read tool to examine changed files\n3. **Analyze Quality**:\n - Check for code duplication (DRY principle)\n - Assess complexity and readability\n - Verify error handling\n - Check for proper logging\n4. **Security Analysis**:\n - Scan for injection vulnerabilities (SQL, command, XSS)\n - Check authentication and authorization\n - Verify input validation and sanitization\n - Look for hardcoded secrets or credentials\n5. **Best Practices**:\n - Follow project-specific standards from CLAUDE.md\n - Check naming conventions\n - Verify test coverage\n - Assess documentation\n6. **Categorize Issues**: Group by severity (critical/major/minor)\n7. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every issue includes file path and line number (e.g., `src/auth.ts:42`)\n- Issues categorized by severity with clear criteria\n- Recommendations are specific and actionable (not vague)\n- Include code examples in recommendations when helpful\n- Balance criticism with recognition of good practices\n\n**Output Format:**\n## Code Review Summary\n[2-3 sentence overview of changes and overall quality]\n\n## Critical Issues (Must Fix)\n- `src/file.ts:42` - [Issue description] - [Why critical] - [How to fix]\n\n## Major Issues (Should Fix)\n- `src/file.ts:15` - [Issue description] - [Impact] - [Recommendation]\n\n## Minor Issues (Consider Fixing)\n- `src/file.ts:88` - [Issue description] - [Suggestion]\n\n## Positive Observations\n- [Good practice 1]\n- [Good practice 2]\n\n## Overall Assessment\n[Final verdict and recommendations]\n\n**Edge Cases:**\n- No issues found: Provide positive validation, mention what was checked\n- Too many issues (>20): Group by type, prioritize top 10 critical/major\n- Unclear code intent: Note ambiguity and request clarification\n- Missing context (no CLAUDE.md): Apply general best practices\n- Large changeset: Focus on most impactful files first\n```\n\n## Example 2: Test Generator Agent\n\n**File:** `agents/test-generator.md`\n\n```markdown\n---\nname: test-generator\ndescription: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples:\n\n\nContext: User implemented functions without tests\nuser: \"I've added the data validation functions\"\nassistant: \"Let me generate tests for these.\"\n\nNew code without tests. Proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly requests tests\nuser: \"Generate unit tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: green\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n---\n\nYou are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.\n\n**Your Core Responsibilities:**\n1. Generate high-quality unit tests with excellent coverage\n2. Follow project testing conventions and patterns\n3. Include happy path, edge cases, and error scenarios\n4. Ensure tests are maintainable and clear\n\n**Test Generation Process:**\n1. **Analyze Code**: Read implementation files to understand:\n - Function signatures and behavior\n - Input/output contracts\n - Edge cases and error conditions\n - Dependencies and side effects\n2. **Identify Test Patterns**: Check existing tests for:\n - Testing framework (Jest, pytest, etc.)\n - File organization (test/ directory, *.test.ts, etc.)\n - Naming conventions\n - Setup/teardown patterns\n3. **Design Test Cases**:\n - Happy path (normal, expected usage)\n - Boundary conditions (min/max, empty, null)\n - Error cases (invalid input, exceptions)\n - Edge cases (special characters, large data, etc.)\n4. **Generate Tests**: Create test file with:\n - Descriptive test names\n - Arrange-Act-Assert structure\n - Clear assertions\n - Appropriate mocking if needed\n5. **Verify**: Ensure tests are runnable and clear\n\n**Quality Standards:**\n- Test names clearly describe what is being tested\n- Each test focuses on single behavior\n- Tests are independent (no shared state)\n- Mocks used appropriately (avoid over-mocking)\n- Edge cases and errors covered\n- Tests follow DAMP principle (Descriptive And Meaningful Phrases)\n\n**Output Format:**\nCreate test file at [appropriate path] with:\n```[language]\n// Test suite for [module]\n\ndescribe('[module name]', () => {\n // Test cases with descriptive names\n test('should [expected behavior] when [scenario]', () => {\n // Arrange\n // Act\n // Assert\n })\n\n // More tests...\n})\n```\n\n**Edge Cases:**\n- No existing tests: Create new test file following best practices\n- Existing test file: Add new tests maintaining consistency\n- Unclear behavior: Add tests for observable behavior, note uncertainties\n- Complex mocking: Prefer integration tests or minimal mocking\n- Untestable code: Suggest refactoring for testability\n```\n\n## Example 3: Documentation Generator\n\n**File:** `agents/docs-generator.md`\n\n```markdown\n---\nname: docs-generator\ndescription: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:\n\n\nContext: User implemented new public API\nuser: \"I've added the user management API endpoints\"\nassistant: \"Let me document these endpoints.\"\n\nNew public API needs documentation. Proactively trigger docs-generator.\n\nassistant: \"I'll use the docs-generator agent to create API documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Generate docs for this module\"\nassistant: \"I'll use the docs-generator agent to create comprehensive documentation.\"\n\nExplicit documentation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: cyan\ntools: [\"Read\", \"Write\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.\n\n**Your Core Responsibilities:**\n1. Generate accurate, clear documentation from code\n2. Follow project documentation standards\n3. Include examples and usage patterns\n4. Ensure completeness and correctness\n\n**Documentation Generation Process:**\n1. **Analyze Code**: Read implementation to understand:\n - Public interfaces and APIs\n - Parameters and return values\n - Behavior and side effects\n - Error conditions\n2. **Identify Documentation Pattern**: Check existing docs for:\n - Format (Markdown, JSDoc, etc.)\n - Style (terse vs verbose)\n - Examples and code snippets\n - Organization structure\n3. **Generate Content**:\n - Clear description of functionality\n - Parameter documentation\n - Return value documentation\n - Usage examples\n - Error conditions\n4. **Format**: Follow project conventions\n5. **Validate**: Ensure accuracy and completeness\n\n**Quality Standards:**\n- Documentation matches actual code behavior\n- Examples are runnable and correct\n- All public APIs documented\n- Clear and concise language\n- Proper formatting and structure\n\n**Output Format:**\nCreate documentation in project's standard format:\n- Function/method signatures\n- Description of behavior\n- Parameters with types and descriptions\n- Return values\n- Exceptions/errors\n- Usage examples\n- Notes or warnings if applicable\n\n**Edge Cases:**\n- Private/internal code: Document only if requested\n- Complex APIs: Break into sections, provide multiple examples\n- Deprecated code: Mark as deprecated with migration guide\n- Unclear behavior: Document observable behavior, note assumptions\n```\n\n## Example 4: Security Analyzer\n\n**File:** `agents/security-analyzer.md`\n\n```markdown\n---\nname: security-analyzer\ndescription: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples:\n\n\nContext: User implemented authentication logic\nuser: \"I've added JWT token validation\"\nassistant: \"Let me check the security.\"\n\nAuthentication code is security-critical. Proactively trigger security-analyzer.\n\nassistant: \"I'll use the security-analyzer agent to review for security vulnerabilities.\"\n\n\n\nContext: User requests security check\nuser: \"Check my code for security issues\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nExplicit security review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: red\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Identify security vulnerabilities (OWASP Top 10 and beyond)\n2. Analyze authentication and authorization logic\n3. Check input validation and sanitization\n4. Verify secure data handling and storage\n5. Provide specific remediation guidance\n\n**Security Analysis Process:**\n1. **Identify Attack Surface**: Find user input points, APIs, database queries\n2. **Check Common Vulnerabilities**:\n - Injection (SQL, command, XSS, etc.)\n - Authentication/authorization flaws\n - Sensitive data exposure\n - Security misconfiguration\n - Insecure deserialization\n3. **Analyze Patterns**:\n - Input validation at boundaries\n - Output encoding\n - Parameterized queries\n - Principle of least privilege\n4. **Assess Risk**: Categorize by severity and exploitability\n5. **Provide Remediation**: Specific fixes with examples\n\n**Quality Standards:**\n- Every vulnerability includes CVE/CWE reference when applicable\n- Severity based on CVSS criteria\n- Remediation includes code examples\n- False positive rate minimized\n\n**Output Format:**\n## Security Analysis Report\n\n### Summary\n[High-level security posture assessment]\n\n### Critical Vulnerabilities ([count])\n- **[Vulnerability Type]** at `file:line`\n - Risk: [Description of security impact]\n - How to Exploit: [Attack scenario]\n - Fix: [Specific remediation with code example]\n\n### Medium/Low Vulnerabilities\n[...]\n\n### Security Best Practices Recommendations\n[...]\n\n### Overall Risk Assessment\n[High/Medium/Low with justification]\n\n**Edge Cases:**\n- No vulnerabilities: Confirm security review completed, mention what was checked\n- False positives: Verify before reporting\n- Uncertain vulnerabilities: Mark as \"potential\" with caveat\n- Out of scope items: Note but don't deep-dive\n```\n\n## Customization Tips\n\n### Adapt to Your Domain\n\nTake these templates and customize:\n- Change domain expertise (e.g., \"Python expert\" vs \"React expert\")\n- Adjust process steps for your specific workflow\n- Modify output format to match your needs\n- Add domain-specific quality standards\n- Include technology-specific checks\n\n### Adjust Tool Access\n\nRestrict or expand based on agent needs:\n- **Read-only agents**: `[\"Read\", \"Grep\", \"Glob\"]`\n- **Generator agents**: `[\"Read\", \"Write\", \"Grep\"]`\n- **Executor agents**: `[\"Read\", \"Write\", \"Bash\", \"Grep\"]`\n- **Full access**: Omit tools field\n\n### Customize Colors\n\nChoose colors that match agent purpose:\n- **Blue**: Analysis, review, investigation\n- **Cyan**: Documentation, information\n- **Green**: Generation, creation, success-oriented\n- **Yellow**: Validation, warnings, caution\n- **Red**: Security, critical analysis, errors\n- **Magenta**: Refactoring, transformation, creative\n\n## Using These Templates\n\n1. Copy template that matches your use case\n2. Replace placeholders with your specifics\n3. Customize process steps for your domain\n4. Adjust examples to your triggering scenarios\n5. Validate with `scripts/validate-agent.sh`\n6. Test triggering with real scenarios\n7. Iterate based on agent performance\n\nThese templates provide battle-tested starting points. Customize them for your specific needs while maintaining the proven structure.\n","plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md":"# Agent Creation System Prompt\n\nThis is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.\n\n## The Prompt\n\n```\nYou are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.\n\n**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.\n\nWhen a user describes what they want an agent to do, you will:\n\n1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.\n\n2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.\n\n3. **Architect Comprehensive Instructions**: Develop a system prompt that:\n - Establishes clear behavioral boundaries and operational parameters\n - Provides specific methodologies and best practices for task execution\n - Anticipates edge cases and provides guidance for handling them\n - Incorporates any specific requirements or preferences mentioned by the user\n - Defines output format expectations when relevant\n - Aligns with project-specific coding standards and patterns from CLAUDE.md\n\n4. **Optimize for Performance**: Include:\n - Decision-making frameworks appropriate to the domain\n - Quality control mechanisms and self-verification steps\n - Efficient workflow patterns\n - Clear escalation or fallback strategies\n\n5. **Create Identifier**: Design a concise, descriptive identifier that:\n - Uses lowercase letters, numbers, and hyphens only\n - Is typically 2-4 words joined by hyphens\n - Clearly indicates the agent's primary function\n - Is memorable and easy to type\n - Avoids generic terms like \"helper\" or \"assistant\"\n\n6. **Example agent descriptions**:\n - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.\n - Examples should be of the form:\n \n Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.\n user: \"Please write a function that checks if a number is prime\"\n assistant: \"Here is the relevant function: \"\n \n \n Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.\n \n assistant: \"Now let me use the code-reviewer agent to review the code\"\n \n - If the user mentioned or implied that the agent should be used proactively, you should include examples of this.\n - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.\n\nYour output must be a valid JSON object with exactly these fields:\n{\n \"identifier\": \"A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')\",\n \"whenToUse\": \"A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.\",\n \"systemPrompt\": \"The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness\"\n}\n\nKey principles for your system prompts:\n- Be specific rather than generic - avoid vague instructions\n- Include concrete examples when they would clarify behavior\n- Balance comprehensiveness with clarity - every instruction should add value\n- Ensure the agent has enough context to handle variations of the core task\n- Make the agent proactive in seeking clarification when needed\n- Build in quality assurance and self-correction mechanisms\n\nRemember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.\n```\n\n## Usage Pattern\n\nUse this prompt to generate agent configurations:\n\n```markdown\n**User input:** \"I need an agent that reviews pull requests for code quality issues\"\n\n**You send to Claude with the system prompt above:**\nCreate an agent configuration based on this request: \"I need an agent that reviews pull requests for code quality issues\"\n\n**Claude returns JSON:**\n{\n \"identifier\": \"pr-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\\n\\n\\nContext: User has created a PR and wants quality review\\nuser: \\\"Can you review PR #123 for code quality?\\\"\\nassistant: \\\"I'll use the pr-quality-reviewer agent to analyze the PR.\\\"\\n\\nPR review request triggers the pr-quality-reviewer agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues\\n2. Check adherence to best practices\\n...\"\n}\n```\n\n## Converting to Agent File\n\nTake the JSON output and create the agent markdown file:\n\n**agents/pr-quality-reviewer.md:**\n```markdown\n---\nname: pr-quality-reviewer\ndescription: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n\nPR review request triggers the pr-quality-reviewer agent.\n\n\n\nmodel: inherit\ncolor: blue\n---\n\nYou are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n...\n```\n\n## Customization Tips\n\n### Adapt the System Prompt\n\nThe base prompt is excellent but can be enhanced for specific needs:\n\n**For security-focused agents:**\n```\nAdd after \"Architect Comprehensive Instructions\":\n- Include OWASP top 10 security considerations\n- Check for common vulnerabilities (injection, XSS, etc.)\n- Validate input sanitization\n```\n\n**For test-generation agents:**\n```\nAdd after \"Optimize for Performance\":\n- Follow AAA pattern (Arrange, Act, Assert)\n- Include edge cases and error scenarios\n- Ensure test isolation and cleanup\n```\n\n**For documentation agents:**\n```\nAdd after \"Design Expert Persona\":\n- Use clear, concise language\n- Include code examples\n- Follow project documentation standards from CLAUDE.md\n```\n\n## Best Practices from Internal Implementation\n\n### 1. Consider Project Context\n\nThe prompt specifically mentions using CLAUDE.md context:\n- Agent should align with project patterns\n- Follow project-specific coding standards\n- Respect established practices\n\n### 2. Proactive Agent Design\n\nInclude examples showing proactive usage:\n```\n\nContext: After writing code, agent should review proactively\nuser: \"Please write a function...\"\nassistant: \"[Writes function]\"\n\nCode written, now use review agent proactively.\n\nassistant: \"Now let me review this code with the code-reviewer agent\"\n\n```\n\n### 3. Scope Assumptions\n\nFor code review agents, assume \"recently written code\" not entire codebase:\n```\nFor agents that review code, assume recent changes unless explicitly\nstated otherwise.\n```\n\n### 4. Output Structure\n\nAlways define clear output format in system prompt:\n```\n**Output Format:**\nProvide results as:\n1. Summary (2-3 sentences)\n2. Detailed findings (bullet points)\n3. Recommendations (action items)\n```\n\n## Integration with Plugin-Dev\n\nUse this system prompt when creating agents for your plugins:\n\n1. Take user request for agent functionality\n2. Feed to Claude with this system prompt\n3. Get JSON output (identifier, whenToUse, systemPrompt)\n4. Convert to agent markdown file with frontmatter\n5. Validate with agent validation rules\n6. Test triggering conditions\n7. Add to plugin's `agents/` directory\n\nThis provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.\n","plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md":"# System Prompt Design Patterns\n\nComplete guide to writing effective agent system prompts that enable autonomous, high-quality operation.\n\n## Core Structure\n\nEvery agent system prompt should follow this proven structure:\n\n```markdown\nYou are [specific role] specializing in [specific domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility - the main task]\n2. [Secondary responsibility - supporting task]\n3. [Additional responsibilities as needed]\n\n**[Task Name] Process:**\n1. [First concrete step]\n2. [Second concrete step]\n3. [Continue with clear steps]\n[...]\n\n**Quality Standards:**\n- [Standard 1 with specifics]\n- [Standard 2 with specifics]\n- [Standard 3 with specifics]\n\n**Output Format:**\nProvide results structured as:\n- [Component 1]\n- [Component 2]\n- [Include specific formatting requirements]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [Specific handling approach]\n- [Edge case 2]: [Specific handling approach]\n```\n\n## Pattern 1: Analysis Agents\n\nFor agents that analyze code, PRs, or documentation:\n\n```markdown\nYou are an expert [domain] analyzer specializing in [specific analysis type].\n\n**Your Core Responsibilities:**\n1. Thoroughly analyze [what] for [specific issues]\n2. Identify [patterns/problems/opportunities]\n3. Provide actionable recommendations\n\n**Analysis Process:**\n1. **Gather Context**: Read [what] using available tools\n2. **Initial Scan**: Identify obvious [issues/patterns]\n3. **Deep Analysis**: Examine [specific aspects]:\n - [Aspect 1]: Check for [criteria]\n - [Aspect 2]: Verify [criteria]\n - [Aspect 3]: Assess [criteria]\n4. **Synthesize Findings**: Group related issues\n5. **Prioritize**: Rank by [severity/impact/urgency]\n6. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every finding includes file:line reference\n- Issues categorized by severity (critical/major/minor)\n- Recommendations are specific and actionable\n- Positive observations included for balance\n\n**Output Format:**\n## Summary\n[2-3 sentence overview]\n\n## Critical Issues\n- [file:line] - [Issue description] - [Recommendation]\n\n## Major Issues\n[...]\n\n## Minor Issues\n[...]\n\n## Recommendations\n[...]\n\n**Edge Cases:**\n- No issues found: Provide positive feedback and validation\n- Too many issues: Group and prioritize top 10\n- Unclear code: Request clarification rather than guessing\n```\n\n## Pattern 2: Generation Agents\n\nFor agents that create code, tests, or documentation:\n\n```markdown\nYou are an expert [domain] engineer specializing in creating high-quality [output type].\n\n**Your Core Responsibilities:**\n1. Generate [what] that meets [quality standards]\n2. Follow [specific conventions/patterns]\n3. Ensure [correctness/completeness/clarity]\n\n**Generation Process:**\n1. **Understand Requirements**: Analyze what needs to be created\n2. **Gather Context**: Read existing [code/docs/tests] for patterns\n3. **Design Structure**: Plan [architecture/organization/flow]\n4. **Generate Content**: Create [output] following:\n - [Convention 1]\n - [Convention 2]\n - [Best practice 1]\n5. **Validate**: Verify [correctness/completeness]\n6. **Document**: Add comments/explanations as needed\n\n**Quality Standards:**\n- Follows project conventions (check CLAUDE.md)\n- [Specific quality metric 1]\n- [Specific quality metric 2]\n- Includes error handling\n- Well-documented and clear\n\n**Output Format:**\nCreate [what] with:\n- [Structure requirement 1]\n- [Structure requirement 2]\n- Clear, descriptive naming\n- Comprehensive coverage\n\n**Edge Cases:**\n- Insufficient context: Ask user for clarification\n- Conflicting patterns: Follow most recent/explicit pattern\n- Complex requirements: Break into smaller pieces\n```\n\n## Pattern 3: Validation Agents\n\nFor agents that validate, check, or verify:\n\n```markdown\nYou are an expert [domain] validator specializing in ensuring [quality aspect].\n\n**Your Core Responsibilities:**\n1. Validate [what] against [criteria]\n2. Identify violations and issues\n3. Provide clear pass/fail determination\n\n**Validation Process:**\n1. **Load Criteria**: Understand validation requirements\n2. **Scan Target**: Read [what] needs validation\n3. **Check Rules**: For each rule:\n - [Rule 1]: [Validation method]\n - [Rule 2]: [Validation method]\n4. **Collect Violations**: Document each failure with details\n5. **Assess Severity**: Categorize issues\n6. **Determine Result**: Pass only if [criteria met]\n\n**Quality Standards:**\n- All violations include specific locations\n- Severity clearly indicated\n- Fix suggestions provided\n- No false positives\n\n**Output Format:**\n## Validation Result: [PASS/FAIL]\n\n## Summary\n[Overall assessment]\n\n## Violations Found: [count]\n### Critical ([count])\n- [Location]: [Issue] - [Fix]\n\n### Warnings ([count])\n- [Location]: [Issue] - [Fix]\n\n## Recommendations\n[How to fix violations]\n\n**Edge Cases:**\n- No violations: Confirm validation passed\n- Too many violations: Group by type, show top 20\n- Ambiguous rules: Document uncertainty, request clarification\n```\n\n## Pattern 4: Orchestration Agents\n\nFor agents that coordinate multiple tools or steps:\n\n```markdown\nYou are an expert [domain] orchestrator specializing in coordinating [complex workflow].\n\n**Your Core Responsibilities:**\n1. Coordinate [multi-step process]\n2. Manage [resources/tools/dependencies]\n3. Ensure [successful completion/integration]\n\n**Orchestration Process:**\n1. **Plan**: Understand full workflow and dependencies\n2. **Prepare**: Set up prerequisites\n3. **Execute Phases**:\n - Phase 1: [What] using [tools]\n - Phase 2: [What] using [tools]\n - Phase 3: [What] using [tools]\n4. **Monitor**: Track progress and handle failures\n5. **Verify**: Confirm successful completion\n6. **Report**: Provide comprehensive summary\n\n**Quality Standards:**\n- Each phase completes successfully\n- Errors handled gracefully\n- Progress reported to user\n- Final state verified\n\n**Output Format:**\n## Workflow Execution Report\n\n### Completed Phases\n- [Phase]: [Result]\n\n### Results\n- [Output 1]\n- [Output 2]\n\n### Next Steps\n[If applicable]\n\n**Edge Cases:**\n- Phase failure: Attempt retry, then report and stop\n- Missing dependencies: Request from user\n- Timeout: Report partial completion\n```\n\n## Writing Style Guidelines\n\n### Tone and Voice\n\n**Use second person (addressing the agent):**\n```\n✅ You are responsible for...\n✅ You will analyze...\n✅ Your process should...\n\n❌ The agent is responsible for...\n❌ This agent will analyze...\n❌ I will analyze...\n```\n\n### Clarity and Specificity\n\n**Be specific, not vague:**\n```\n✅ Check for SQL injection by examining all database queries for parameterization\n❌ Look for security issues\n\n✅ Provide file:line references for each finding\n❌ Show where issues are\n\n✅ Categorize as critical (security), major (bugs), or minor (style)\n❌ Rate the severity of issues\n```\n\n### Actionable Instructions\n\n**Give concrete steps:**\n```\n✅ Read the file using the Read tool, then search for patterns using Grep\n❌ Analyze the code\n\n✅ Generate test file at test/path/to/file.test.ts\n❌ Create tests\n```\n\n## Common Pitfalls\n\n### ❌ Vague Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Help the user with their code\n2. Provide assistance\n3. Be helpful\n```\n\n**Why bad:** Not specific enough to guide behavior.\n\n### ✅ Specific Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Analyze TypeScript code for type safety issues\n2. Identify missing type annotations and improper 'any' usage\n3. Recommend specific type improvements with examples\n```\n\n### ❌ Missing Process Steps\n\n```markdown\nAnalyze the code and provide feedback.\n```\n\n**Why bad:** Agent doesn't know HOW to analyze.\n\n### ✅ Clear Process\n\n```markdown\n**Analysis Process:**\n1. Read code files using Read tool\n2. Scan for type annotations on all functions\n3. Check for 'any' type usage\n4. Verify generic type parameters\n5. List findings with file:line references\n```\n\n### ❌ Undefined Output\n\n```markdown\nProvide a report.\n```\n\n**Why bad:** Agent doesn't know what format to use.\n\n### ✅ Defined Output Format\n\n```markdown\n**Output Format:**\n## Type Safety Report\n\n### Summary\n[Overview of findings]\n\n### Issues Found\n- `file.ts:42` - Missing return type on `processData`\n- `utils.ts:15` - Unsafe 'any' usage in parameter\n\n### Recommendations\n[Specific fixes with examples]\n```\n\n## Length Guidelines\n\n### Minimum Viable Agent\n\n**~500 words minimum:**\n- Role description\n- 3 core responsibilities\n- 5-step process\n- Output format\n\n### Standard Agent\n\n**~1,000-2,000 words:**\n- Detailed role and expertise\n- 5-8 responsibilities\n- 8-12 process steps\n- Quality standards\n- Output format\n- 3-5 edge cases\n\n### Comprehensive Agent\n\n**~2,000-5,000 words:**\n- Complete role with background\n- Comprehensive responsibilities\n- Detailed multi-phase process\n- Extensive quality standards\n- Multiple output formats\n- Many edge cases\n- Examples within system prompt\n\n**Avoid > 10,000 words:** Too long, diminishing returns.\n\n## Testing System Prompts\n\n### Test Completeness\n\nCan the agent handle these based on system prompt alone?\n\n- [ ] Typical task execution\n- [ ] Edge cases mentioned\n- [ ] Error scenarios\n- [ ] Unclear requirements\n- [ ] Large/complex inputs\n- [ ] Empty/missing inputs\n\n### Test Clarity\n\nRead the system prompt and ask:\n\n- Can another developer understand what this agent does?\n- Are process steps clear and actionable?\n- Is output format unambiguous?\n- Are quality standards measurable?\n\n### Iterate Based on Results\n\nAfter testing agent:\n1. Identify where it struggled\n2. Add missing guidance to system prompt\n3. Clarify ambiguous instructions\n4. Add process steps for edge cases\n5. Re-test\n\n## Conclusion\n\nEffective system prompts are:\n- **Specific**: Clear about what and how\n- **Structured**: Organized with clear sections\n- **Complete**: Covers normal and edge cases\n- **Actionable**: Provides concrete steps\n- **Testable**: Defines measurable standards\n\nUse the patterns above as templates, customize for your domain, and iterate based on agent performance.\n","plugins/plugin-dev/skills/agent-development/references/triggering-examples.md":"# Agent Triggering Examples: Best Practices\n\nComplete guide to writing effective `` blocks in agent descriptions for reliable triggering.\n\n## Example Block Format\n\nThe standard format for triggering examples:\n\n```markdown\n\nContext: [Describe the situation - what led to this interaction]\nuser: \"[Exact user message or request]\"\nassistant: \"[How Claude should respond before triggering]\"\n\n[Explanation of why this agent should be triggered in this scenario]\n\nassistant: \"[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']\"\n\n```\n\n## Anatomy of a Good Example\n\n### Context\n\n**Purpose:** Set the scene - what happened before the user's message\n\n**Good contexts:**\n```\nContext: User just implemented a new authentication feature\nContext: User has created a PR and wants it reviewed\nContext: User is debugging a test failure\nContext: After writing several functions without documentation\n```\n\n**Bad contexts:**\n```\nContext: User needs help (too vague)\nContext: Normal usage (not specific)\n```\n\n### User Message\n\n**Purpose:** Show the exact phrasing that should trigger the agent\n\n**Good user messages:**\n```\nuser: \"I've added the OAuth flow, can you check it?\"\nuser: \"Review PR #123\"\nuser: \"Why is this test failing?\"\nuser: \"Add docs for these functions\"\n```\n\n**Vary the phrasing:**\nInclude multiple examples with different phrasings for the same intent:\n```\nExample 1: user: \"Review my code\"\nExample 2: user: \"Can you check this implementation?\"\nExample 3: user: \"Look over my changes\"\n```\n\n### Assistant Response (Before Triggering)\n\n**Purpose:** Show what Claude says before launching the agent\n\n**Good responses:**\n```\nassistant: \"I'll analyze your OAuth implementation.\"\nassistant: \"Let me review that PR for you.\"\nassistant: \"I'll investigate the test failure.\"\n```\n\n**Proactive example:**\n```\nassistant: \"Great! Now let me review the code quality.\"\n\nCode was just written, proactively trigger review agent.\n\n```\n\n### Commentary\n\n**Purpose:** Explain the reasoning - WHY this agent should trigger\n\n**Good commentary:**\n```\n\nUser explicitly requested code review, trigger the code-reviewer agent.\n\n\n\nAfter code implementation, proactively use review agent to check quality.\n\n\n\nPR analysis request matches pr-analyzer agent's expertise.\n\n```\n\n**Include decision logic:**\n```\n\nUser wrote tests (Test tool used). The test-analyzer agent should check\ntest quality and coverage before continuing.\n\n```\n\n### Assistant Response (Triggering)\n\n**Purpose:** Show how Claude invokes the agent\n\n**Standard pattern:**\n```\nassistant: \"I'll use the [agent-name] agent to [what it will do].\"\n```\n\n**Examples:**\n```\nassistant: \"I'll use the code-reviewer agent to analyze the changes.\"\nassistant: \"Let me use the test-generator agent to create comprehensive tests.\"\nassistant: \"I'll use the security-analyzer agent to check for vulnerabilities.\"\n```\n\n## Example Types\n\n### Type 1: Explicit Request\n\nUser directly asks for what the agent does:\n\n```markdown\n\nContext: User explicitly requests security analysis\nuser: \"Check my code for security vulnerabilities\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nDirect security analysis request triggers the security-analyzer agent.\n\n\n```\n\n### Type 2: Proactive Triggering\n\nAgent triggers after relevant work without explicit request:\n\n```markdown\n\nContext: User just implemented database queries\nuser: \"I've added the user search functionality\"\nassistant: \"Great! Let me review it for security.\"\n\nDatabase code written. Proactively trigger security-analyzer to check\nfor SQL injection and other database security issues.\n\nassistant: \"I'll use the security-analyzer agent to check the database code.\"\n\n```\n\n### Type 3: Implicit Request\n\nUser implies need without stating it directly:\n\n```markdown\n\nContext: User mentions code is hard to understand\nuser: \"This code is confusing and hard to follow\"\nassistant: \"I can help improve the code clarity.\"\n\nUser indicates complexity issues. Trigger code-simplifier agent to refactor\nfor better readability.\n\nassistant: \"I'll use the code-simplifier agent to suggest improvements.\"\n\n```\n\n### Type 4: Tool Usage Pattern\n\nAgent triggers based on prior tool usage:\n\n```markdown\n\nContext: User made multiple edits to test files\nuser: \"I've updated all the tests\"\nassistant: \"Great! Let me verify test quality.\"\n\nMultiple Edit tools used on test files. Proactively trigger test-quality-analyzer\nto ensure tests follow best practices.\n\nassistant: \"I'll use the test-quality-analyzer agent to review the tests.\"\n\n```\n\n## Multiple Examples Strategy\n\n### Cover Different Phrasings\n\n```markdown\n\nuser: \"Review my code\"\n[...]\n\n\n\nuser: \"Can you check my implementation?\"\n[...]\n\n\n\nuser: \"Look over these changes\"\n[...]\n\n```\n\n### Cover Proactive and Reactive\n\n```markdown\n\nContext: User explicitly requests review\nuser: \"Review my code for issues\"\n[...]\n\n\n\nContext: After user writes code\nuser: \"I've implemented the feature\"\nassistant: \"Great! Now let me review it.\"\n\nCode written, proactively review.\n\n[...]\n\n```\n\n### Cover Edge Cases\n\n```markdown\n\nContext: Typical usage\nuser: \"Check my PR\"\n[...]\n\n\n\nContext: Large PR that needs thorough analysis\nuser: \"This is a big PR, can you do a deep review?\"\n[...]\n\nLarge PR mentioned, use thorough analysis mode.\n\n\n```\n\n## Common Mistakes\n\n### ❌ Missing Context\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent.\"\n\n```\n\n**Why bad:** No context about what led to this request.\n\n### ✅ With Context\n\n```markdown\n\nContext: User just finished implementing authentication\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to analyze the auth implementation.\"\n\nAuth code written, review for security and best practices.\n\n\n```\n\n### ❌ No Commentary\n\n```markdown\n\nContext: User requests review\nuser: \"Check my changes\"\nassistant: \"I'll use the reviewer agent.\"\n\n```\n\n**Why bad:** Doesn't explain WHY agent triggers.\n\n### ✅ With Commentary\n\n```markdown\n\nContext: User requests review after making changes\nuser: \"Check my changes\"\nassistant: \"I'll use the code-reviewer agent to analyze the modifications.\"\n\nCode review request triggers agent to check quality, security, and adherence to standards.\n\n\n```\n\n### ❌ Agent Responds Directly\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I found the following issues: [lists issues]\"\n\n```\n\n**Why bad:** Shows agent's output, not triggering.\n\n### ✅ Shows Triggering\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to perform the review.\"\n\nReview request triggers the agent.\n\n\n```\n\n## How Many Examples?\n\n### Minimum: 2 Examples\n\nCover at least:\n1. Explicit request\n2. One variation or proactive trigger\n\n### Recommended: 3-4 Examples\n\nCover:\n1. Explicit request (direct ask)\n2. Implicit request (user implies need)\n3. Proactive trigger (after relevant work)\n4. Edge case or specific scenario\n\n### Maximum: 6 Examples\n\nMore than 6 makes description too long. Focus on most important scenarios.\n\n## Template Library\n\n### Code Review Agent\n\n```markdown\n\nContext: User just implemented a new feature\nuser: \"I've added the user registration feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode written, proactively trigger code-reviewer agent.\n\nassistant: \"I'll use the code-reviewer agent to analyze the implementation.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my changes for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n```\n\n### Test Generation Agent\n\n```markdown\n\nContext: User implemented functions without tests\nuser: \"I've added the data processing functions\"\nassistant: \"Great! Let me generate tests for these.\"\n\nNew code without tests, proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly asks for tests\nuser: \"Generate tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n```\n\n### Documentation Agent\n\n```markdown\n\nContext: User added new API endpoints\nuser: \"I've implemented the REST API endpoints\"\nassistant: \"I'll document these endpoints.\"\n\nNew API code, proactively generate documentation.\n\nassistant: \"I'll use the api-docs-writer agent to create comprehensive documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Write docs for this API\"\nassistant: \"I'll use the api-docs-writer agent to generate clear documentation.\"\n\nDocumentation request triggers the agent.\n\n\n```\n\n### Validation Agent\n\n```markdown\n\nContext: User ready to commit changes\nuser: \"I'm ready to commit this code\"\nassistant: \"Let me validate it first.\"\n\nBefore commit, proactively validate with validation-agent.\n\nassistant: \"I'll use the code-validator agent to check for issues.\"\n\n\n\nContext: User asks for validation\nuser: \"Validate my implementation\"\nassistant: \"I'll use the code-validator agent to verify correctness.\"\n\nExplicit validation request triggers the agent.\n\n\n```\n\n## Debugging Triggering Issues\n\n### Agent Not Triggering\n\n**Check:**\n1. Examples include relevant keywords from user message\n2. Context matches actual usage scenarios\n3. Commentary explains triggering logic clearly\n4. Assistant shows use of Agent tool in examples\n\n**Fix:**\nAdd more examples covering different phrasings.\n\n### Agent Triggers Too Often\n\n**Check:**\n1. Examples are too broad or generic\n2. Triggering conditions overlap with other agents\n3. Commentary doesn't distinguish when NOT to use\n\n**Fix:**\nMake examples more specific, add negative examples.\n\n### Agent Triggers in Wrong Scenarios\n\n**Check:**\n1. Examples don't match actual intended use\n2. Commentary suggests inappropriate triggering\n\n**Fix:**\nRevise examples to show only correct triggering scenarios.\n\n## Best Practices Summary\n\n✅ **DO:**\n- Include 2-4 concrete, specific examples\n- Show both explicit and proactive triggering\n- Provide clear context for each example\n- Explain reasoning in commentary\n- Vary user message phrasing\n- Show Claude using Agent tool\n\n❌ **DON'T:**\n- Use generic, vague examples\n- Omit context or commentary\n- Show only one type of triggering\n- Skip the agent invocation step\n- Make examples too similar\n- Forget to explain why agent triggers\n\n## Conclusion\n\nWell-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.\n","plugins/plugin-dev/skills/command-development/README.md":"","plugins/plugin-dev/skills/command-development/SKILL.md":"---\nname: Command Development\ndescription: This skill should be used when the user asks to \"create a slash command\", \"add a command\", \"write a custom command\", \"define command arguments\", \"use command frontmatter\", \"organize commands\", \"create command with file references\", \"interactive command\", \"use AskUserQuestion in command\", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.\nversion: 0.2.0\n---\n\n# Command Development for Claude Code\n\n## Overview\n\nSlash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.\n\n**Key concepts:**\n- Markdown file format for commands\n- YAML frontmatter for configuration\n- Dynamic arguments and file references\n- Bash execution for context\n- Command organization and namespacing\n\n## Command Basics\n\n### What is a Slash Command?\n\nA slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:\n- **Reusability**: Define once, use repeatedly\n- **Consistency**: Standardize common workflows\n- **Sharing**: Distribute across team or projects\n- **Efficiency**: Quick access to complex prompts\n\n### Critical: Commands are Instructions FOR Claude\n\n**Commands are written for agent consumption, not human consumption.**\n\nWhen a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.\n\n**Correct approach (instructions for Claude):**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication issues\n\nProvide specific line numbers and severity ratings.\n```\n\n**Incorrect approach (messages to user):**\n```markdown\nThis command will review your code for security issues.\nYou'll receive a report with vulnerability details.\n```\n\nThe first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.\n\n### Command Locations\n\n**Project commands** (shared with team):\n- Location: `.claude/commands/`\n- Scope: Available in specific project\n- Label: Shown as \"(project)\" in `/help`\n- Use for: Team workflows, project-specific tasks\n\n**Personal commands** (available everywhere):\n- Location: `~/.claude/commands/`\n- Scope: Available in all projects\n- Label: Shown as \"(user)\" in `/help`\n- Use for: Personal workflows, cross-project utilities\n\n**Plugin commands** (bundled with plugins):\n- Location: `plugin-name/commands/`\n- Scope: Available when plugin installed\n- Label: Shown as \"(plugin-name)\" in `/help`\n- Use for: Plugin-specific functionality\n\n## File Format\n\n### Basic Structure\n\nCommands are Markdown files with `.md` extension:\n\n```\n.claude/commands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**Simple command:**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication bypass\n- Insecure data handling\n```\n\nNo frontmatter needed for basic commands.\n\n### With YAML Frontmatter\n\nAdd configuration using YAML frontmatter:\n\n```markdown\n---\ndescription: Review code for security issues\nallowed-tools: Read, Grep, Bash(git:*)\nmodel: sonnet\n---\n\nReview this code for security vulnerabilities...\n```\n\n## YAML Frontmatter Fields\n\n### description\n\n**Purpose:** Brief description shown in `/help`\n**Type:** String\n**Default:** First line of command prompt\n\n```yaml\n---\ndescription: Review pull request for code quality\n---\n```\n\n**Best practice:** Clear, actionable description (under 60 characters)\n\n### allowed-tools\n\n**Purpose:** Specify which tools command can use\n**Type:** String or Array\n**Default:** Inherits from conversation\n\n```yaml\n---\nallowed-tools: Read, Write, Edit, Bash(git:*)\n---\n```\n\n**Patterns:**\n- `Read, Write, Edit` - Specific tools\n- `Bash(git:*)` - Bash with git commands only\n- `*` - All tools (rarely needed)\n\n**Use when:** Command requires specific tool access\n\n### model\n\n**Purpose:** Specify model for command execution\n**Type:** String (sonnet, opus, haiku)\n**Default:** Inherits from conversation\n\n```yaml\n---\nmodel: haiku\n---\n```\n\n**Use cases:**\n- `haiku` - Fast, simple commands\n- `sonnet` - Standard workflows\n- `opus` - Complex analysis\n\n### argument-hint\n\n**Purpose:** Document expected arguments for autocomplete\n**Type:** String\n**Default:** None\n\n```yaml\n---\nargument-hint: [pr-number] [priority] [assignee]\n---\n```\n\n**Benefits:**\n- Helps users understand command arguments\n- Improves command discovery\n- Documents command interface\n\n### disable-model-invocation\n\n**Purpose:** Prevent SlashCommand tool from programmatically calling command\n**Type:** Boolean\n**Default:** false\n\n```yaml\n---\ndisable-model-invocation: true\n---\n```\n\n**Use when:** Command should only be manually invoked\n\n## Dynamic Arguments\n\n### Using $ARGUMENTS\n\nCapture all arguments as single string:\n\n```markdown\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$ARGUMENTS following our coding standards and best practices.\n```\n\n**Usage:**\n```\n> /fix-issue 123\n> /fix-issue 456\n```\n\n**Expands to:**\n```\nFix issue #123 following our coding standards...\nFix issue #456 following our coding standards...\n```\n\n### Using Positional Arguments\n\nCapture individual arguments with `$1`, `$2`, `$3`, etc.:\n\n```markdown\n---\ndescription: Review PR with priority and assignee\nargument-hint: [pr-number] [priority] [assignee]\n---\n\nReview pull request #$1 with priority level $2.\nAfter review, assign to $3 for follow-up.\n```\n\n**Usage:**\n```\n> /review-pr 123 high alice\n```\n\n**Expands to:**\n```\nReview pull request #123 with priority level high.\nAfter review, assign to alice for follow-up.\n```\n\n### Combining Arguments\n\nMix positional and remaining arguments:\n\n```markdown\nDeploy $1 to $2 environment with options: $3\n```\n\n**Usage:**\n```\n> /deploy api staging --force --skip-tests\n```\n\n**Expands to:**\n```\nDeploy api to staging environment with options: --force --skip-tests\n```\n\n## File References\n\n### Using @ Syntax\n\nInclude file contents in command:\n\n```markdown\n---\ndescription: Review specific file\nargument-hint: [file-path]\n---\n\nReview @$1 for:\n- Code quality\n- Best practices\n- Potential bugs\n```\n\n**Usage:**\n```\n> /review-file src/api/users.ts\n```\n\n**Effect:** Claude reads `src/api/users.ts` before processing command\n\n### Multiple File References\n\nReference multiple files:\n\n```markdown\nCompare @src/old-version.js with @src/new-version.js\n\nIdentify:\n- Breaking changes\n- New features\n- Bug fixes\n```\n\n### Static File References\n\nReference known files without arguments:\n\n```markdown\nReview @package.json and @tsconfig.json for consistency\n\nEnsure:\n- TypeScript version matches\n- Dependencies are aligned\n- Build configuration is correct\n```\n\n## Bash Execution in Commands\n\nCommands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.\n\n**When to use:**\n- Include dynamic context (git status, environment vars, etc.)\n- Gather project/repository state\n- Build context-aware workflows\n\n**Implementation details:**\nFor complete syntax, examples, and best practices, see `references/plugin-features-reference.md` section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues\n\n## Command Organization\n\n### Flat Structure\n\nSimple organization for small command sets:\n\n```\n.claude/commands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**Use when:** 5-15 commands, no clear categories\n\n### Namespaced Structure\n\nOrganize commands in subdirectories:\n\n```\n.claude/commands/\n├── ci/\n│ ├── build.md # /build (project:ci)\n│ ├── test.md # /test (project:ci)\n│ └── lint.md # /lint (project:ci)\n├── git/\n│ ├── commit.md # /commit (project:git)\n│ └── pr.md # /pr (project:git)\n└── docs/\n ├── generate.md # /generate (project:docs)\n └── publish.md # /publish (project:docs)\n```\n\n**Benefits:**\n- Logical grouping by category\n- Namespace shown in `/help`\n- Easier to find related commands\n\n**Use when:** 15+ commands, clear categories\n\n## Best Practices\n\n### Command Design\n\n1. **Single responsibility:** One command, one task\n2. **Clear descriptions:** Self-explanatory in `/help`\n3. **Explicit dependencies:** Use `allowed-tools` when needed\n4. **Document arguments:** Always provide `argument-hint`\n5. **Consistent naming:** Use verb-noun pattern (review-pr, fix-issue)\n\n### Argument Handling\n\n1. **Validate arguments:** Check for required arguments in prompt\n2. **Provide defaults:** Suggest defaults when arguments missing\n3. **Document format:** Explain expected argument format\n4. **Handle edge cases:** Consider missing or invalid arguments\n\n```markdown\n---\nargument-hint: [pr-number]\n---\n\n$IF($1,\n Review PR #$1,\n Please provide a PR number. Usage: /review-pr [number]\n)\n```\n\n### File References\n\n1. **Explicit paths:** Use clear file paths\n2. **Check existence:** Handle missing files gracefully\n3. **Relative paths:** Use project-relative paths\n4. **Glob support:** Consider using Glob tool for patterns\n\n### Bash Commands\n\n1. **Limit scope:** Use `Bash(git:*)` not `Bash(*)`\n2. **Safe commands:** Avoid destructive operations\n3. **Handle errors:** Consider command failures\n4. **Keep fast:** Long-running commands slow invocation\n\n### Documentation\n\n1. **Add comments:** Explain complex logic\n2. **Provide examples:** Show usage in comments\n3. **List requirements:** Document dependencies\n4. **Version commands:** Note breaking changes\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment] [version]\n---\n\n\n\nDeploy application to $1 environment using version $2...\n```\n\n## Common Patterns\n\n### Review Pattern\n\n```markdown\n---\ndescription: Review code changes\nallowed-tools: Read, Bash(git:*)\n---\n\nFiles changed: !`git diff --name-only`\n\nReview each file for:\n1. Code quality and style\n2. Potential bugs or issues\n3. Test coverage\n4. Documentation needs\n\nProvide specific feedback for each file.\n```\n\n### Testing Pattern\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*)\n---\n\nRun tests: !`npm test $1`\n\nAnalyze results and suggest fixes for failures.\n```\n\n### Documentation Pattern\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1 including:\n- Function/class descriptions\n- Parameter documentation\n- Return value descriptions\n- Usage examples\n- Edge cases and errors\n```\n\n### Workflow Pattern\n\n```markdown\n---\ndescription: Complete PR workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read\n---\n\nPR #$1 Workflow:\n\n1. Fetch PR: !`gh pr view $1`\n2. Review changes\n3. Run checks\n4. Approve or request changes\n```\n\n## Troubleshooting\n\n**Command not appearing:**\n- Check file is in correct directory\n- Verify `.md` extension present\n- Ensure valid Markdown format\n- Restart Claude Code\n\n**Arguments not working:**\n- Verify `$1`, `$2` syntax correct\n- Check `argument-hint` matches usage\n- Ensure no extra spaces\n\n**Bash execution failing:**\n- Check `allowed-tools` includes Bash\n- Verify command syntax in backticks\n- Test command in terminal first\n- Check for required permissions\n\n**File references not working:**\n- Verify `@` syntax correct\n- Check file path is valid\n- Ensure Read tool allowed\n- Use absolute or project-relative paths\n\n## Plugin-Specific Features\n\n### CLAUDE_PLUGIN_ROOT Variable\n\nPlugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path.\n\n**Purpose:**\n- Reference plugin files portably\n- Execute plugin scripts\n- Load plugin configuration\n- Access plugin templates\n\n**Basic usage:**\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*)\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\nReview results and report findings.\n```\n\n**Common patterns:**\n\n```markdown\n# Execute plugin script\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n\n# Load plugin configuration\n@${CLAUDE_PLUGIN_ROOT}/config/settings.json\n\n# Use plugin template\n@${CLAUDE_PLUGIN_ROOT}/templates/report.md\n\n# Access plugin resources\n@${CLAUDE_PLUGIN_ROOT}/docs/reference.md\n```\n\n**Why use it:**\n- Works across all installations\n- Portable between systems\n- No hardcoded paths needed\n- Essential for multi-file plugins\n\n### Plugin Command Organization\n\nPlugin commands discovered automatically from `commands/` directory:\n\n```\nplugin-name/\n├── commands/\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ ├── bar.md # /bar (plugin:plugin-name)\n│ └── utils/\n│ └── helper.md # /helper (plugin:plugin-name:utils)\n└── plugin.json\n```\n\n**Namespace benefits:**\n- Logical command grouping\n- Shown in `/help` output\n- Avoid name conflicts\n- Organize related commands\n\n**Naming conventions:**\n- Use descriptive action names\n- Avoid generic names (test, run)\n- Consider plugin-specific prefix\n- Use hyphens for multi-word names\n\n### Plugin Command Patterns\n\n**Configuration-based pattern:**\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nDeploy to $1 using configuration settings.\nMonitor deployment and report status.\n```\n\n**Template-based pattern:**\n\n```markdown\n---\ndescription: Generate docs from template\nargument-hint: [component]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md\n\nGenerate documentation for $1 following template structure.\n```\n\n**Multi-script pattern:**\n\n```markdown\n---\ndescription: Complete build workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\nPackage: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`\n\nReview outputs and report workflow status.\n```\n\n**See `references/plugin-features-reference.md` for detailed patterns.**\n\n## Integration with Plugin Components\n\nCommands can integrate with other plugin components for powerful workflows.\n\n### Agent Integration\n\nLaunch plugin agents for complex tasks:\n\n```markdown\n---\ndescription: Deep code review\nargument-hint: [file-path]\n---\n\nInitiate comprehensive review of @$1 using the code-reviewer agent.\n\nThe agent will analyze:\n- Code structure\n- Security issues\n- Performance\n- Best practices\n\nAgent uses plugin resources:\n- ${CLAUDE_PLUGIN_ROOT}/config/rules.json\n- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md\n```\n\n**Key points:**\n- Agent must exist in `plugin/agents/` directory\n- Claude uses Task tool to launch agent\n- Document agent capabilities\n- Reference plugin resources agent uses\n\n### Skill Integration\n\nLeverage plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: Document API with standards\nargument-hint: [api-file]\n---\n\nDocument API in @$1 following plugin standards.\n\nUse the api-docs-standards skill to ensure:\n- Complete endpoint documentation\n- Consistent formatting\n- Example quality\n- Error documentation\n\nGenerate production-ready API docs.\n```\n\n**Key points:**\n- Skill must exist in `plugin/skills/` directory\n- Mention skill name to trigger invocation\n- Document skill purpose\n- Explain what skill provides\n\n### Hook Coordination\n\nDesign commands that work with plugin hooks:\n- Commands can prepare state for hooks to process\n- Hooks execute automatically on tool events\n- Commands should document expected hook behavior\n- Guide Claude on interpreting hook output\n\nSee `references/plugin-features-reference.md` for examples of commands that coordinate with hooks\n\n### Multi-Component Workflows\n\nCombine agents, skills, and scripts:\n\n```markdown\n---\ndescription: Comprehensive review workflow\nargument-hint: [file]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget: @$1\n\nPhase 1 - Static Analysis:\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\nPhase 2 - Deep Review:\nLaunch code-reviewer agent for detailed analysis.\n\nPhase 3 - Standards Check:\nUse coding-standards skill for validation.\n\nPhase 4 - Report:\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review.md\n\nCompile findings into report following template.\n```\n\n**When to use:**\n- Complex multi-step workflows\n- Leverage multiple plugin capabilities\n- Require specialized analysis\n- Need structured outputs\n\n## Validation Patterns\n\nCommands should validate inputs and resources before processing.\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\nIf $1 is valid environment:\n Deploy to $1\nOtherwise:\n Explain valid environments: dev, staging, prod\n Show usage: /deploy [environment]\n```\n\n### File Existence Checks\n\n```markdown\n---\ndescription: Process configuration\nargument-hint: [config-file]\n---\n\nCheck file exists: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nIf file exists:\n Process configuration: @$1\nOtherwise:\n Explain where to place config file\n Show expected format\n Provide example configuration\n```\n\n### Plugin Resource Validation\n\n```markdown\n---\ndescription: Run plugin analyzer\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, run analysis.\nOtherwise, report missing components.\n```\n\n### Error Handling\n\n```markdown\n---\ndescription: Build with error handling\nallowed-tools: Bash(*)\n---\n\nExecute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo \"BUILD_FAILED\"`\n\nIf build succeeded:\n Report success and output location\nIf build failed:\n Analyze error output\n Suggest likely causes\n Provide troubleshooting steps\n```\n\n**Best practices:**\n- Validate early in command\n- Provide helpful error messages\n- Suggest corrective actions\n- Handle edge cases gracefully\n\n---\n\nFor detailed frontmatter field specifications, see `references/frontmatter-reference.md`.\nFor plugin-specific features and patterns, see `references/plugin-features-reference.md`.\nFor command pattern examples, see `examples/` directory.\n","plugins/plugin-dev/skills/command-development/examples/plugin-commands.md":"# Plugin Command Examples\n\nPractical examples of commands designed for Claude Code plugins, demonstrating plugin-specific patterns and features.\n\n## Table of Contents\n\n1. [Simple Plugin Command](#1-simple-plugin-command)\n2. [Script-Based Analysis](#2-script-based-analysis)\n3. [Template-Based Generation](#3-template-based-generation)\n4. [Multi-Script Workflow](#4-multi-script-workflow)\n5. [Configuration-Driven Deployment](#5-configuration-driven-deployment)\n6. [Agent Integration](#6-agent-integration)\n7. [Skill Integration](#7-skill-integration)\n8. [Multi-Component Workflow](#8-multi-component-workflow)\n9. [Validated Input Command](#9-validated-input-command)\n10. [Environment-Aware Command](#10-environment-aware-command)\n\n---\n\n## 1. Simple Plugin Command\n\n**Use case:** Basic command that uses plugin script\n\n**File:** `commands/analyze.md`\n\n```markdown\n---\ndescription: Analyze code quality using plugin tools\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nAnalyze @$1 using plugin's quality checker:\n\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/quality-check.js $1`\n\nReview the analysis output and provide:\n1. Summary of findings\n2. Priority issues to address\n3. Suggested improvements\n4. Code quality score interpretation\n```\n\n**Key features:**\n- Uses `${CLAUDE_PLUGIN_ROOT}` for portable path\n- Combines file reference with script execution\n- Simple single-purpose command\n\n---\n\n## 2. Script-Based Analysis\n\n**Use case:** Run comprehensive analysis using multiple plugin scripts\n\n**File:** `commands/full-audit.md`\n\n```markdown\n---\ndescription: Complete code audit using plugin suite\nargument-hint: [directory]\nallowed-tools: Bash(*)\nmodel: sonnet\n---\n\nRunning complete audit on $1:\n\n**Security scan:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh $1`\n\n**Performance analysis:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-analyze.sh $1`\n\n**Best practices check:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/best-practices.sh $1`\n\nAnalyze all results and create comprehensive report including:\n- Critical issues requiring immediate attention\n- Performance optimization opportunities\n- Security vulnerabilities and fixes\n- Overall health score and recommendations\n```\n\n**Key features:**\n- Multiple script executions\n- Organized output sections\n- Comprehensive workflow\n- Clear reporting structure\n\n---\n\n## 3. Template-Based Generation\n\n**Use case:** Generate documentation following plugin template\n\n**File:** `commands/gen-api-docs.md`\n\n```markdown\n---\ndescription: Generate API documentation from template\nargument-hint: [api-file]\n---\n\nTemplate structure: @${CLAUDE_PLUGIN_ROOT}/templates/api-documentation.md\n\nAPI implementation: @$1\n\nGenerate complete API documentation following the template format above.\n\nEnsure documentation includes:\n- Endpoint descriptions with HTTP methods\n- Request/response schemas\n- Authentication requirements\n- Error codes and handling\n- Usage examples with curl commands\n- Rate limiting information\n\nFormat output as markdown suitable for README or docs site.\n```\n\n**Key features:**\n- Uses plugin template\n- Combines template with source file\n- Standardized output format\n- Clear documentation structure\n\n---\n\n## 4. Multi-Script Workflow\n\n**Use case:** Orchestrate build, test, and deploy workflow\n\n**File:** `commands/release.md`\n\n```markdown\n---\ndescription: Execute complete release workflow\nargument-hint: [version]\nallowed-tools: Bash(*), Read\n---\n\nExecuting release workflow for version $1:\n\n**Step 1 - Pre-release validation:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-release-check.sh $1`\n\n**Step 2 - Build artifacts:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build-release.sh $1`\n\n**Step 3 - Run test suite:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh`\n\n**Step 4 - Package release:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh $1`\n\nReview all step outputs and report:\n1. Any failures or warnings\n2. Build artifacts location\n3. Test results summary\n4. Next steps for deployment\n5. Rollback plan if needed\n```\n\n**Key features:**\n- Multi-step workflow\n- Sequential script execution\n- Clear step numbering\n- Comprehensive reporting\n\n---\n\n## 5. Configuration-Driven Deployment\n\n**Use case:** Deploy using environment-specific plugin configuration\n\n**File:** `commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nDeployment configuration for $1: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nCurrent git state: !`git rev-parse --short HEAD`\n\nBuild info: !`cat package.json | grep -E '(name|version)'`\n\nExecute deployment to $1 environment using configuration above.\n\nDeployment checklist:\n1. Validate configuration settings\n2. Build application for $1\n3. Run pre-deployment tests\n4. Deploy to target environment\n5. Run smoke tests\n6. Verify deployment success\n7. Update deployment log\n\nReport deployment status and any issues encountered.\n```\n\n**Key features:**\n- Environment-specific configuration\n- Dynamic config file loading\n- Pre-deployment validation\n- Structured checklist\n\n---\n\n## 6. Agent Integration\n\n**Use case:** Command that launches plugin agent for complex task\n\n**File:** `commands/deep-review.md`\n\n```markdown\n---\ndescription: Deep code review using plugin agent\nargument-hint: [file-or-directory]\n---\n\nInitiate comprehensive code review of @$1 using the code-reviewer agent.\n\nThe agent will perform:\n1. **Static analysis** - Check for code smells and anti-patterns\n2. **Security audit** - Identify potential vulnerabilities\n3. **Performance review** - Find optimization opportunities\n4. **Best practices** - Ensure code follows standards\n5. **Documentation check** - Verify adequate documentation\n\nThe agent has access to:\n- Plugin's linting rules: ${CLAUDE_PLUGIN_ROOT}/config/lint-rules.json\n- Security checklist: ${CLAUDE_PLUGIN_ROOT}/checklists/security.md\n- Performance guidelines: ${CLAUDE_PLUGIN_ROOT}/docs/performance.md\n\nNote: This uses the Task tool to launch the plugin's code-reviewer agent for thorough analysis.\n```\n\n**Key features:**\n- Delegates to plugin agent\n- Documents agent capabilities\n- References plugin resources\n- Clear scope definition\n\n---\n\n## 7. Skill Integration\n\n**Use case:** Command that leverages plugin skill for specialized knowledge\n\n**File:** `commands/document-api.md`\n\n```markdown\n---\ndescription: Document API following plugin standards\nargument-hint: [api-file]\n---\n\nAPI source code: @$1\n\nGenerate API documentation following the plugin's API documentation standards.\n\nUse the api-documentation-standards skill to ensure:\n- **OpenAPI compliance** - Follow OpenAPI 3.0 specification\n- **Consistent formatting** - Use plugin's documentation style\n- **Complete coverage** - Document all endpoints and schemas\n- **Example quality** - Provide realistic usage examples\n- **Error documentation** - Cover all error scenarios\n\nThe skill provides:\n- Standard documentation templates\n- API documentation best practices\n- Common patterns for this codebase\n- Quality validation criteria\n\nGenerate production-ready API documentation.\n```\n\n**Key features:**\n- Invokes plugin skill by name\n- Documents skill purpose\n- Clear expectations\n- Leverages skill knowledge\n\n---\n\n## 8. Multi-Component Workflow\n\n**Use case:** Complex workflow using agents, skills, and scripts\n\n**File:** `commands/complete-review.md`\n\n```markdown\n---\ndescription: Comprehensive review using all plugin components\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget file: @$1\n\nExecute comprehensive review workflow:\n\n**Phase 1: Automated Analysis**\nRun plugin analyzer: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\n**Phase 2: Deep Review (Agent)**\nLaunch the code-quality-reviewer agent for detailed analysis.\nAgent will examine:\n- Code structure and organization\n- Error handling patterns\n- Testing coverage\n- Documentation quality\n\n**Phase 3: Standards Check (Skill)**\nUse the coding-standards skill to validate:\n- Naming conventions\n- Code formatting\n- Best practices adherence\n- Framework-specific patterns\n\n**Phase 4: Report Generation**\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nCompile all findings into comprehensive report following template.\n\n**Phase 5: Recommendations**\nGenerate prioritized action items:\n1. Critical issues (must fix)\n2. Important improvements (should fix)\n3. Nice-to-have enhancements (could fix)\n\nInclude specific file locations and suggested changes for each item.\n```\n\n**Key features:**\n- Multi-phase workflow\n- Combines scripts, agents, skills\n- Template-based reporting\n- Prioritized outputs\n\n---\n\n## 9. Validated Input Command\n\n**Use case:** Command with input validation and error handling\n\n**File:** `commands/build-env.md`\n\n```markdown\n---\ndescription: Build for specific environment with validation\nargument-hint: [environment]\nallowed-tools: Bash(*)\n---\n\nValidate environment argument: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" && echo \"VALID\" || echo \"INVALID\"`\n\nCheck build script exists: !`test -x ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh && echo \"EXISTS\" || echo \"MISSING\"`\n\nVerify configuration available: !`test -f ${CLAUDE_PLUGIN_ROOT}/config/$1.json && echo \"FOUND\" || echo \"NOT_FOUND\"`\n\nIf all validations pass:\n\n**Configuration:** @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\n**Execute build:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh $1 2>&1`\n\n**Validation results:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-build.sh $1 2>&1`\n\nReport build status and any issues.\n\nIf validations fail:\n- Explain which validation failed\n- Provide expected values/locations\n- Suggest corrective actions\n- Document troubleshooting steps\n```\n\n**Key features:**\n- Input validation\n- Resource existence checks\n- Error handling\n- Helpful error messages\n- Graceful failure handling\n\n---\n\n## 10. Environment-Aware Command\n\n**Use case:** Command that adapts behavior based on environment\n\n**File:** `commands/run-checks.md`\n\n```markdown\n---\ndescription: Run environment-appropriate checks\nargument-hint: [environment]\nallowed-tools: Bash(*), Read\n---\n\nEnvironment: $1\n\nLoad environment configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-checks.json\n\nDetermine check level: !`echo \"$1\" | grep -E \"^prod$\" && echo \"FULL\" || echo \"BASIC\"`\n\n**For production environment:**\n- Full test suite: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-full.sh`\n- Security scan: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh`\n- Performance audit: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-check.sh`\n- Compliance check: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/compliance.sh`\n\n**For non-production environments:**\n- Basic tests: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-basic.sh`\n- Quick lint: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh`\n\nAnalyze results based on environment requirements:\n\n**Production:** All checks must pass with zero critical issues\n**Staging:** No critical issues, warnings acceptable\n**Development:** Focus on blocking issues only\n\nReport status and recommend proceed/block decision.\n```\n\n**Key features:**\n- Environment-aware logic\n- Conditional execution\n- Different validation levels\n- Appropriate reporting per environment\n\n---\n\n## Common Patterns Summary\n\n### Pattern: Plugin Script Execution\n```markdown\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/script-name.js $1`\n```\nUse for: Running plugin-provided Node.js scripts\n\n### Pattern: Plugin Configuration Loading\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/config/config-name.json\n```\nUse for: Loading plugin configuration files\n\n### Pattern: Plugin Template Usage\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/templates/template-name.md\n```\nUse for: Using plugin templates for generation\n\n### Pattern: Agent Invocation\n```markdown\nLaunch the [agent-name] agent for [task description].\n```\nUse for: Delegating complex tasks to plugin agents\n\n### Pattern: Skill Reference\n```markdown\nUse the [skill-name] skill to ensure [requirements].\n```\nUse for: Leveraging plugin skills for specialized knowledge\n\n### Pattern: Input Validation\n```markdown\nValidate input: !`echo \"$1\" | grep -E \"^pattern$\" && echo \"OK\" || echo \"ERROR\"`\n```\nUse for: Validating command arguments\n\n### Pattern: Resource Validation\n```markdown\nCheck exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/path/file && echo \"YES\" || echo \"NO\"`\n```\nUse for: Verifying required plugin files exist\n\n---\n\n## Development Tips\n\n### Testing Plugin Commands\n\n1. **Test with plugin installed:**\n ```bash\n cd /path/to/plugin\n claude /command-name args\n ```\n\n2. **Verify ${CLAUDE_PLUGIN_ROOT} expansion:**\n ```bash\n # Add debug output to command\n !`echo \"Plugin root: ${CLAUDE_PLUGIN_ROOT}\"`\n ```\n\n3. **Test across different working directories:**\n ```bash\n cd /tmp && claude /command-name\n cd /other/project && claude /command-name\n ```\n\n4. **Validate resource availability:**\n ```bash\n # Check all plugin resources exist\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/scripts/`\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/config/`\n ```\n\n### Common Mistakes to Avoid\n\n1. **Using relative paths instead of ${CLAUDE_PLUGIN_ROOT}:**\n ```markdown\n # Wrong\n !`node ./scripts/analyze.js`\n\n # Correct\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n ```\n\n2. **Forgetting to allow required tools:**\n ```markdown\n # Missing allowed-tools\n !`bash script.sh` # Will fail without Bash permission\n\n # Correct\n ---\n allowed-tools: Bash(*)\n ---\n !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n ```\n\n3. **Not validating inputs:**\n ```markdown\n # Risky - no validation\n Deploy to $1 environment\n\n # Better - with validation\n Validate: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n Deploy to $1 environment (if valid)\n ```\n\n4. **Hardcoding plugin paths:**\n ```markdown\n # Wrong - breaks on different installations\n @/home/user/.claude/plugins/my-plugin/config.json\n\n # Correct - works everywhere\n @${CLAUDE_PLUGIN_ROOT}/config.json\n ```\n\n---\n\nFor detailed plugin-specific features, see `references/plugin-features-reference.md`.\nFor general command development, see main `SKILL.md`.\n","plugins/plugin-dev/skills/command-development/examples/simple-commands.md":"# Simple Command Examples\n\nBasic slash command patterns for common use cases.\n\n**Important:** All examples below are written as instructions FOR Claude (agent consumption), not messages TO users. Commands tell Claude what to do, not tell users what will happen.\n\n## Example 1: Code Review Command\n\n**File:** `.claude/commands/review.md`\n\n```markdown\n---\ndescription: Review code for quality and issues\nallowed-tools: Read, Bash(git:*)\n---\n\nReview the code in this repository for:\n\n1. **Code Quality:**\n - Readability and maintainability\n - Consistent style and formatting\n - Appropriate abstraction levels\n\n2. **Potential Issues:**\n - Logic errors or bugs\n - Edge cases not handled\n - Performance concerns\n\n3. **Best Practices:**\n - Design patterns used correctly\n - Error handling present\n - Documentation adequate\n\nProvide specific feedback with file and line references.\n```\n\n**Usage:**\n```\n> /review\n```\n\n---\n\n## Example 2: Security Review Command\n\n**File:** `.claude/commands/security-review.md`\n\n```markdown\n---\ndescription: Review code for security vulnerabilities\nallowed-tools: Read, Grep\nmodel: sonnet\n---\n\nPerform comprehensive security review checking for:\n\n**Common Vulnerabilities:**\n- SQL injection risks\n- Cross-site scripting (XSS)\n- Authentication/authorization issues\n- Insecure data handling\n- Hardcoded secrets or credentials\n\n**Security Best Practices:**\n- Input validation present\n- Output encoding correct\n- Secure defaults used\n- Error messages safe\n- Logging appropriate (no sensitive data)\n\nFor each issue found:\n- File and line number\n- Severity (Critical/High/Medium/Low)\n- Description of vulnerability\n- Recommended fix\n\nPrioritize issues by severity.\n```\n\n**Usage:**\n```\n> /security-review\n```\n\n---\n\n## Example 3: Test Command with File Argument\n\n**File:** `.claude/commands/test-file.md`\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*), Bash(jest:*)\n---\n\nRun tests for $1:\n\nTest execution: !`npm test $1`\n\nAnalyze results:\n- Tests passed/failed\n- Code coverage\n- Performance issues\n- Flaky tests\n\nIf failures found, suggest fixes based on error messages.\n```\n\n**Usage:**\n```\n> /test-file src/utils/helpers.test.ts\n```\n\n---\n\n## Example 4: Documentation Generator\n\n**File:** `.claude/commands/document.md`\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1\n\nInclude:\n\n**Overview:**\n- Purpose and responsibility\n- Main functionality\n- Dependencies\n\n**API Documentation:**\n- Function/method signatures\n- Parameter descriptions with types\n- Return values with types\n- Exceptions/errors thrown\n\n**Usage Examples:**\n- Basic usage\n- Common patterns\n- Edge cases\n\n**Implementation Notes:**\n- Algorithm complexity\n- Performance considerations\n- Known limitations\n\nFormat as Markdown suitable for project documentation.\n```\n\n**Usage:**\n```\n> /document src/api/users.ts\n```\n\n---\n\n## Example 5: Git Status Summary\n\n**File:** `.claude/commands/git-status.md`\n\n```markdown\n---\ndescription: Summarize Git repository status\nallowed-tools: Bash(git:*)\n---\n\nRepository Status Summary:\n\n**Current Branch:** !`git branch --show-current`\n\n**Status:** !`git status --short`\n\n**Recent Commits:** !`git log --oneline -5`\n\n**Remote Status:** !`git fetch && git status -sb`\n\nProvide:\n- Summary of changes\n- Suggested next actions\n- Any warnings or issues\n```\n\n**Usage:**\n```\n> /git-status\n```\n\n---\n\n## Example 6: Deployment Command\n\n**File:** `.claude/commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy to specified environment\nargument-hint: [environment] [version]\nallowed-tools: Bash(kubectl:*), Read\n---\n\nDeploy to $1 environment using version $2\n\n**Pre-deployment Checks:**\n1. Verify $1 configuration exists\n2. Check version $2 is valid\n3. Verify cluster accessibility: !`kubectl cluster-info`\n\n**Deployment Steps:**\n1. Update deployment manifest with version $2\n2. Apply configuration to $1\n3. Monitor rollout status\n4. Verify pod health\n5. Run smoke tests\n\n**Rollback Plan:**\nDocument current version for rollback if issues occur.\n\nProceed with deployment? (yes/no)\n```\n\n**Usage:**\n```\n> /deploy staging v1.2.3\n```\n\n---\n\n## Example 7: Comparison Command\n\n**File:** `.claude/commands/compare-files.md`\n\n```markdown\n---\ndescription: Compare two files\nargument-hint: [file1] [file2]\n---\n\nCompare @$1 with @$2\n\n**Analysis:**\n\n1. **Differences:**\n - Lines added\n - Lines removed\n - Lines modified\n\n2. **Functional Changes:**\n - Breaking changes\n - New features\n - Bug fixes\n - Refactoring\n\n3. **Impact:**\n - Affected components\n - Required updates elsewhere\n - Migration requirements\n\n4. **Recommendations:**\n - Code review focus areas\n - Testing requirements\n - Documentation updates needed\n\nPresent as structured comparison report.\n```\n\n**Usage:**\n```\n> /compare-files src/old-api.ts src/new-api.ts\n```\n\n---\n\n## Example 8: Quick Fix Command\n\n**File:** `.claude/commands/quick-fix.md`\n\n```markdown\n---\ndescription: Quick fix for common issues\nargument-hint: [issue-description]\nmodel: haiku\n---\n\nQuickly fix: $ARGUMENTS\n\n**Approach:**\n1. Identify the issue\n2. Find relevant code\n3. Propose fix\n4. Explain solution\n\nFocus on:\n- Simple, direct solution\n- Minimal changes\n- Following existing patterns\n- No breaking changes\n\nProvide code changes with file paths and line numbers.\n```\n\n**Usage:**\n```\n> /quick-fix button not responding to clicks\n> /quick-fix typo in error message\n```\n\n---\n\n## Example 9: Research Command\n\n**File:** `.claude/commands/research.md`\n\n```markdown\n---\ndescription: Research best practices for topic\nargument-hint: [topic]\nmodel: sonnet\n---\n\nResearch best practices for: $ARGUMENTS\n\n**Coverage:**\n\n1. **Current State:**\n - How we currently handle this\n - Existing implementations\n\n2. **Industry Standards:**\n - Common patterns\n - Recommended approaches\n - Tools and libraries\n\n3. **Comparison:**\n - Our approach vs standards\n - Gaps or improvements needed\n - Migration considerations\n\n4. **Recommendations:**\n - Concrete action items\n - Priority and effort estimates\n - Resources for implementation\n\nProvide actionable guidance based on research.\n```\n\n**Usage:**\n```\n> /research error handling in async operations\n> /research API authentication patterns\n```\n\n---\n\n## Example 10: Explain Code Command\n\n**File:** `.claude/commands/explain.md`\n\n```markdown\n---\ndescription: Explain how code works\nargument-hint: [file-or-function]\n---\n\nExplain @$1 in detail\n\n**Explanation Structure:**\n\n1. **Overview:**\n - What it does\n - Why it exists\n - How it fits in system\n\n2. **Step-by-Step:**\n - Line-by-line walkthrough\n - Key algorithms or logic\n - Important details\n\n3. **Inputs and Outputs:**\n - Parameters and types\n - Return values\n - Side effects\n\n4. **Edge Cases:**\n - Error handling\n - Special cases\n - Limitations\n\n5. **Usage Examples:**\n - How to call it\n - Common patterns\n - Integration points\n\nExplain at level appropriate for junior engineer.\n```\n\n**Usage:**\n```\n> /explain src/utils/cache.ts\n> /explain AuthService.login\n```\n\n---\n\n## Key Patterns\n\n### Pattern 1: Read-Only Analysis\n\n```markdown\n---\nallowed-tools: Read, Grep\n---\n\nAnalyze but don't modify...\n```\n\n**Use for:** Code review, documentation, analysis\n\n### Pattern 2: Git Operations\n\n```markdown\n---\nallowed-tools: Bash(git:*)\n---\n\n!`git status`\nAnalyze and suggest...\n```\n\n**Use for:** Repository status, commit analysis\n\n### Pattern 3: Single Argument\n\n```markdown\n---\nargument-hint: [target]\n---\n\nProcess $1...\n```\n\n**Use for:** File operations, targeted actions\n\n### Pattern 4: Multiple Arguments\n\n```markdown\n---\nargument-hint: [source] [target] [options]\n---\n\nProcess $1 to $2 with $3...\n```\n\n**Use for:** Workflows, deployments, comparisons\n\n### Pattern 5: Fast Execution\n\n```markdown\n---\nmodel: haiku\n---\n\nQuick simple task...\n```\n\n**Use for:** Simple, repetitive commands\n\n### Pattern 6: File Comparison\n\n```markdown\nCompare @$1 with @$2...\n```\n\n**Use for:** Diff analysis, migration planning\n\n### Pattern 7: Context Gathering\n\n```markdown\n---\nallowed-tools: Bash(git:*), Read\n---\n\nContext: !`git status`\nFiles: @file1 @file2\n\nAnalyze...\n```\n\n**Use for:** Informed decision making\n\n## Tips for Writing Simple Commands\n\n1. **Start basic:** Single responsibility, clear purpose\n2. **Add complexity gradually:** Start without frontmatter\n3. **Test incrementally:** Verify each feature works\n4. **Use descriptive names:** Command name should indicate purpose\n5. **Document arguments:** Always use argument-hint\n6. **Provide examples:** Show usage in comments\n7. **Handle errors:** Consider missing arguments or files\n","plugins/plugin-dev/skills/command-development/references/advanced-workflows.md":"# Advanced Workflow Patterns\n\nMulti-step command sequences and composition patterns for complex workflows.\n\n## Overview\n\nAdvanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks.\n\n## Multi-Step Command Patterns\n\n### Sequential Workflow Command\n\nCommands that guide users through multi-step processes:\n\n```markdown\n---\ndescription: Complete PR review workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read, Grep\n---\n\n# PR Review Workflow for #$1\n\n## Step 1: Fetch PR Details\n!`gh pr view $1 --json title,body,author,files`\n\n## Step 2: Review Files\nFiles changed: !`gh pr diff $1 --name-only`\n\nFor each file:\n- Check code quality\n- Verify tests exist\n- Review documentation\n\n## Step 3: Run Checks\nTest status: !`gh pr checks $1`\n\nVerify:\n- All tests passing\n- No merge conflicts\n- CI/CD successful\n\n## Step 4: Provide Feedback\n\nSummarize:\n- Issues found (critical/minor)\n- Suggestions for improvement\n- Approval recommendation\n\nWould you like to:\n1. Approve PR\n2. Request changes\n3. Leave comments only\n\nReply with your choice and I'll help complete the action.\n```\n\n**Key features:**\n- Numbered steps for clarity\n- Bash execution for context\n- Decision points for user input\n- Next action suggestions\n\n### State-Carrying Workflow\n\nCommands that maintain state between invocations:\n\n```markdown\n---\ndescription: Initialize deployment workflow\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment\n\nCreating deployment tracking file...\n\nCurrent branch: !`git branch --show-current`\nLatest commit: !`git log -1 --format=%H`\n\nDeployment state saved to `.claude/deployment-state.local.md`:\n\n\\`\\`\\`markdown\n---\ninitialized: true\nbranch: $(git branch --show-current)\ncommit: $(git log -1 --format=%H)\ntimestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)\nstatus: initialized\n---\n\n# Deployment Tracking\n\nBranch: $(git branch --show-current)\nStarted: $(date)\n\nNext steps:\n1. Run tests: /deploy-test\n2. Build: /deploy-build\n3. Deploy: /deploy-execute\n\\`\\`\\`\n\nState saved. Run `/deploy-test` to continue.\n```\n\n**Next command** (`/deploy-test`):\n```markdown\n---\ndescription: Run deployment tests\nallowed-tools: Read, Bash(npm:*)\n---\n\nReading deployment state from `.claude/deployment-state.local.md`...\n\nRunning tests: !`npm test`\n\nUpdating state to 'tested'...\n\nTests complete. Run `/deploy-build` to continue.\n```\n\n**Pattern benefits:**\n- Persistent state across commands\n- Clear workflow progression\n- Safety checkpoints\n- Resume capability\n\n### Conditional Workflow Branching\n\nCommands that adapt based on conditions:\n\n```markdown\n---\ndescription: Smart deployment workflow\nargument-hint: [environment]\nallowed-tools: Bash(git:*), Bash(npm:*), Read\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\nBranch: !`git branch --show-current`\nStatus: !`git status --short`\n\n**Checking conditions:**\n\n1. Branch status:\n - If main/master: Require approval\n - If feature branch: Warning about target\n - If hotfix: Fast-track process\n\n2. Tests:\n !`npm test`\n - If tests fail: STOP - fix tests first\n - If tests pass: Continue\n\n3. Environment:\n - If $1 = 'production': Extra validation\n - If $1 = 'staging': Standard process\n - If $1 = 'dev': Minimal checks\n\n**Workflow decision:**\nBased on above, proceeding with: [determined workflow]\n\n[Conditional steps based on environment and status]\n\nReady to deploy? (yes/no)\n```\n\n## Command Composition Patterns\n\n### Command Chaining\n\nCommands designed to work together:\n\n```markdown\n---\ndescription: Prepare for code review\n---\n\n# Prepare Code Review\n\nRunning preparation sequence:\n\n1. Format code: /format-code\n2. Run linter: /lint-code\n3. Run tests: /test-all\n4. Generate coverage: /coverage-report\n5. Create review summary: /review-summary\n\nThis is a meta-command. After completing each step above,\nI'll compile results and prepare comprehensive review materials.\n\nStarting sequence...\n```\n\n**Individual commands** are simple:\n- `/format-code` - Just formats\n- `/lint-code` - Just lints\n- `/test-all` - Just tests\n\n**Composition command** orchestrates them.\n\n### Pipeline Pattern\n\nCommands that process output from previous commands:\n\n```markdown\n---\ndescription: Analyze test failures\n---\n\n# Analyze Test Failures\n\n## Step 1: Get test results\n(Run /test-all first if not done)\n\nReading test output...\n\n## Step 2: Categorize failures\n- Flaky tests (random failures)\n- Consistent failures\n- New failures vs existing\n\n## Step 3: Prioritize\nRank by:\n- Impact (critical path vs edge case)\n- Frequency (always fails vs sometimes)\n- Effort (quick fix vs major work)\n\n## Step 4: Generate fix plan\nFor each failure:\n- Root cause hypothesis\n- Suggested fix approach\n- Estimated effort\n\nWould you like me to:\n1. Fix highest priority failure\n2. Generate detailed fix plans for all\n3. Create GitHub issues for each\n```\n\n### Parallel Execution Pattern\n\nCommands that coordinate multiple simultaneous operations:\n\n```markdown\n---\ndescription: Run comprehensive validation\nallowed-tools: Bash(*), Read\n---\n\n# Comprehensive Validation\n\nRunning validations in parallel...\n\nStarting:\n- Code quality checks\n- Security scanning\n- Dependency audit\n- Performance profiling\n\nThis will take 2-3 minutes. I'll monitor all processes\nand report when complete.\n\n[Poll each process and report progress]\n\nAll validations complete. Summary:\n- Quality: PASS (0 issues)\n- Security: WARN (2 minor issues)\n- Dependencies: PASS\n- Performance: PASS (baseline met)\n\nDetails:\n[Collated results from all checks]\n```\n\n## Workflow State Management\n\n### Using .local.md Files\n\nStore workflow state in plugin-specific files:\n\n```markdown\n.claude/plugin-name-workflow.local.md:\n\n---\nworkflow: deployment\nstage: testing\nstarted: 2025-01-15T10:30:00Z\nenvironment: staging\nbranch: feature/new-api\ncommit: abc123def\ntests_passed: false\nbuild_complete: false\n---\n\n# Deployment Workflow State\n\nCurrent stage: Testing\nStarted: 2025-01-15 10:30 UTC\n\nCompleted steps:\n- ✅ Validation\n- ✅ Branch check\n- ⏳ Testing (in progress)\n\nPending steps:\n- Build\n- Deploy\n- Smoke tests\n```\n\n**Reading state in commands:**\n\n```markdown\n---\ndescription: Continue deployment workflow\nallowed-tools: Read, Write\n---\n\nReading workflow state from .claude/plugin-name-workflow.local.md...\n\nCurrent stage: @.claude/plugin-name-workflow.local.md\n\n[Parse YAML frontmatter to determine next step]\n\nNext action based on state: [determined action]\n```\n\n### Workflow Recovery\n\nHandle interrupted workflows:\n\n```markdown\n---\ndescription: Resume deployment workflow\nallowed-tools: Read\n---\n\n# Resume Deployment\n\nChecking for interrupted workflow...\n\nState file: @.claude/plugin-name-workflow.local.md\n\n**Workflow found:**\n- Started: [timestamp]\n- Environment: [env]\n- Last completed: [step]\n\n**Recovery options:**\n1. Resume from last step\n2. Restart from beginning\n3. Abort and clean up\n\nWhich would you like? (1/2/3)\n```\n\n## Workflow Coordination Patterns\n\n### Cross-Command Communication\n\nCommands that signal each other:\n\n```markdown\n---\ndescription: Mark feature complete\nallowed-tools: Write\n---\n\n# Mark Feature Complete\n\nWriting completion marker...\n\nCreating: .claude/feature-complete.flag\n\nThis signals other commands that feature is ready for:\n- Integration testing (/integration-test will auto-detect)\n- Documentation generation (/docs-generate will include)\n- Release notes (/release-notes will add)\n\nFeature marked complete.\n```\n\n**Other commands check for flag:**\n\n```markdown\n---\ndescription: Generate release notes\nallowed-tools: Read, Bash(git:*)\n---\n\nChecking for completed features...\n\nif [ -f .claude/feature-complete.flag ]; then\n Feature ready for release notes\nfi\n\n[Include in release notes]\n```\n\n### Workflow Locking\n\nPrevent concurrent workflow execution:\n\n```markdown\n---\ndescription: Start deployment\nallowed-tools: Read, Write, Bash\n---\n\n# Start Deployment\n\nChecking for active deployments...\n\nif [ -f .claude/deployment.lock ]; then\n ERROR: Deployment already in progress\n Started: [timestamp from lock file]\n\n Cannot start concurrent deployment.\n Wait for completion or run /deployment-abort\n\n Exit.\nfi\n\nCreating deployment lock...\n\nDeployment started. Lock created.\n[Proceed with deployment]\n```\n\n**Lock cleanup:**\n\n```markdown\n---\ndescription: Complete deployment\nallowed-tools: Write, Bash\n---\n\nDeployment complete.\n\nRemoving deployment lock...\nrm .claude/deployment.lock\n\nReady for next deployment.\n```\n\n## Advanced Argument Handling\n\n### Optional Arguments with Defaults\n\n```markdown\n---\ndescription: Deploy with optional version\nargument-hint: [environment] [version]\n---\n\nEnvironment: ${1:-staging}\nVersion: ${2:-latest}\n\nDeploying ${2:-latest} to ${1:-staging}...\n\nNote: Using defaults for missing arguments:\n- Environment defaults to 'staging'\n- Version defaults to 'latest'\n```\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy to validated environment\nargument-hint: [environment]\n---\n\nEnvironment: $1\n\nValidating environment...\n\nvalid_envs=\"dev staging production\"\nif ! echo \"$valid_envs\" | grep -w \"$1\" > /dev/null; then\n ERROR: Invalid environment '$1'\n Valid options: dev, staging, production\n Exit.\nfi\n\nEnvironment validated. Proceeding...\n```\n\n### Argument Transformation\n\n```markdown\n---\ndescription: Deploy with shorthand\nargument-hint: [env-shorthand]\n---\n\nInput: $1\n\nExpanding shorthand:\n- d/dev → development\n- s/stg → staging\n- p/prod → production\n\ncase \"$1\" in\n d|dev) ENV=\"development\";;\n s|stg) ENV=\"staging\";;\n p|prod) ENV=\"production\";;\n *) ENV=\"$1\";;\nesac\n\nDeploying to: $ENV\n```\n\n## Error Handling in Workflows\n\n### Graceful Failure\n\n```markdown\n---\ndescription: Resilient deployment workflow\n---\n\n# Deployment Workflow\n\nRunning steps with error handling...\n\n## Step 1: Tests\n!`npm test`\n\nif [ $? -ne 0 ]; then\n ERROR: Tests failed\n\n Options:\n 1. Fix tests and retry\n 2. Skip tests (NOT recommended)\n 3. Abort deployment\n\n What would you like to do?\n\n [Wait for user input before continuing]\nfi\n\n## Step 2: Build\n[Continue only if Step 1 succeeded]\n```\n\n### Rollback on Failure\n\n```markdown\n---\ndescription: Deployment with rollback\n---\n\n# Deploy with Rollback\n\nSaving current state for rollback...\nPrevious version: !`current-version.sh`\n\nDeploying new version...\n\n!`deploy.sh`\n\nif [ $? -ne 0 ]; then\n DEPLOYMENT FAILED\n\n Initiating automatic rollback...\n !`rollback.sh`\n\n Rolled back to previous version.\n Check logs for failure details.\nfi\n\nDeployment complete.\n```\n\n### Checkpoint Recovery\n\n```markdown\n---\ndescription: Workflow with checkpoints\n---\n\n# Multi-Stage Deployment\n\n## Checkpoint 1: Validation\n!`validate.sh`\necho \"checkpoint:validation\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 2: Build\n!`build.sh`\necho \"checkpoint:build\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 3: Deploy\n!`deploy.sh`\necho \"checkpoint:deploy\" >> .claude/deployment-checkpoints.log\n\nIf any step fails, resume with:\n/deployment-resume [last-successful-checkpoint]\n```\n\n## Best Practices\n\n### Workflow Design\n\n1. **Clear progression**: Number steps, show current position\n2. **Explicit state**: Don't rely on implicit state\n3. **User control**: Provide decision points\n4. **Error recovery**: Handle failures gracefully\n5. **Progress indication**: Show what's done, what's pending\n\n### Command Composition\n\n1. **Single responsibility**: Each command does one thing well\n2. **Composable design**: Commands work together easily\n3. **Standard interfaces**: Consistent input/output formats\n4. **Loose coupling**: Commands don't depend on each other's internals\n\n### State Management\n\n1. **Persistent state**: Use .local.md files\n2. **Atomic updates**: Write complete state files atomically\n3. **State validation**: Check state file format/completeness\n4. **Cleanup**: Remove stale state files\n5. **Documentation**: Document state file formats\n\n### Error Handling\n\n1. **Fail fast**: Detect errors early\n2. **Clear messages**: Explain what went wrong\n3. **Recovery options**: Provide clear next steps\n4. **State preservation**: Keep state for recovery\n5. **Rollback capability**: Support undoing changes\n\n## Example: Complete Deployment Workflow\n\n### Initialize Command\n\n```markdown\n---\ndescription: Initialize deployment\nargument-hint: [environment]\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment to $1\n\nCreating workflow state...\n\n\\`\\`\\`yaml\n---\nworkflow: deployment\nenvironment: $1\nbranch: !`git branch --show-current`\ncommit: !`git rev-parse HEAD`\nstage: initialized\ntimestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`\n---\n\\`\\`\\`\n\nWritten to .claude/deployment-state.local.md\n\nNext: Run /deployment-validate\n```\n\n### Validation Command\n\n```markdown\n---\ndescription: Validate deployment\nallowed-tools: Read, Bash\n---\n\nReading state: @.claude/deployment-state.local.md\n\nRunning validation...\n- Branch check: PASS\n- Tests: PASS\n- Build: PASS\n\nUpdating state to 'validated'...\n\nNext: Run /deployment-execute\n```\n\n### Execution Command\n\n```markdown\n---\ndescription: Execute deployment\nallowed-tools: Read, Bash, Write\n---\n\nReading state: @.claude/deployment-state.local.md\n\nExecuting deployment to [environment]...\n\n!`deploy.sh [environment]`\n\nDeployment complete.\nUpdating state to 'completed'...\n\nCleanup: /deployment-cleanup\n```\n\n### Cleanup Command\n\n```markdown\n---\ndescription: Clean up deployment\nallowed-tools: Bash\n---\n\nRemoving deployment state...\nrm .claude/deployment-state.local.md\n\nDeployment workflow complete.\n```\n\nThis complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.\n","plugins/plugin-dev/skills/command-development/references/documentation-patterns.md":"# Command Documentation Patterns\n\nStrategies for creating self-documenting, maintainable commands with excellent user experience.\n\n## Overview\n\nWell-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.\n\n## Self-Documenting Command Structure\n\n### Complete Command Template\n\n```markdown\n---\ndescription: Clear, actionable description under 60 chars\nargument-hint: [arg1] [arg2] [optional-arg]\nallowed-tools: Read, Bash(git:*)\nmodel: sonnet\n---\n\n\n\n# Command Implementation\n\n[Command prompt content here...]\n\n[Explain what will happen...]\n\n[Guide user through steps...]\n\n[Provide clear output...]\n```\n\n### Documentation Comment Sections\n\n**PURPOSE**: Why the command exists\n- Problem it solves\n- Use cases\n- When to use vs when not to use\n\n**USAGE**: Basic syntax\n- Command invocation pattern\n- Required vs optional arguments\n- Default values\n\n**ARGUMENTS**: Detailed argument documentation\n- Each argument described\n- Type information\n- Valid values/ranges\n- Defaults\n\n**EXAMPLES**: Concrete usage examples\n- Common use cases\n- Edge cases\n- Expected outputs\n\n**REQUIREMENTS**: Prerequisites\n- Dependencies\n- Permissions\n- Environmental setup\n\n**RELATED COMMANDS**: Connections\n- Similar commands\n- Complementary commands\n- Alternative approaches\n\n**TROUBLESHOOTING**: Common issues\n- Known problems\n- Solutions\n- Workarounds\n\n**CHANGELOG**: Version history\n- What changed when\n- Breaking changes highlighted\n- Migration guidance\n\n## In-Line Documentation Patterns\n\n### Commented Sections\n\n```markdown\n---\ndescription: Complex multi-step command\n---\n\n\n\n\nChecking prerequisites...\n- Git repository: !`git rev-parse --git-dir 2>/dev/null`\n- Branch exists: [validation logic]\n\n\n\n\nAnalyzing differences between $1 and $2...\n[Analysis logic...]\n\n\n\n\nBased on analysis, recommend:\n[Recommendations...]\n\n\n```\n\n### Inline Explanations\n\n```markdown\n---\ndescription: Deployment command with inline docs\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\n\nCurrent branch: !`git branch --show-current`\n\n\nif [ \"$1\" = \"production\" ] && [ \"$(git branch --show-current)\" != \"main\" ]; then\n ⚠️ WARNING: Not on main branch for production deploy\n This is unusual. Confirm this is intentional.\nfi\n\n\nRunning tests: !`npm test`\n\n✓ All checks passed\n\n## Deployment\n\n\n\nDeploying to $1 environment...\n[Deployment steps...]\n\n\nVerifying deployment health...\n[Health checks...]\n\nDeployment complete!\n\n## Next Steps\n\n\n1. Monitor logs: /logs $1\n2. Run smoke tests: /smoke-test $1\n3. Notify team: /notify-deployment $1\n```\n\n### Decision Point Documentation\n\n```markdown\n---\ndescription: Interactive deployment command\n---\n\n# Interactive Deployment\n\n## Configuration Review\n\nTarget: $1\nCurrent version: !`cat version.txt`\nNew version: $2\n\n\n\n\n\nReview the above configuration.\n\n**Continue with deployment?**\n- Reply \"yes\" to proceed\n- Reply \"no\" to cancel\n- Reply \"edit\" to modify configuration\n\n[Await user input before continuing...]\n\n\n\n\nProceeding with deployment...\n```\n\n## Help Text Patterns\n\n### Built-in Help Command\n\nCreate a help subcommand for complex commands:\n\n```markdown\n---\ndescription: Main command with help\nargument-hint: [subcommand] [args]\n---\n\n# Command Processor\n\nif [ \"$1\" = \"help\" ] || [ \"$1\" = \"--help\" ] || [ \"$1\" = \"-h\" ]; then\n **Command Help**\n\n USAGE:\n /command [subcommand] [args]\n\n SUBCOMMANDS:\n init [name] Initialize new configuration\n deploy [env] Deploy to environment\n status Show current status\n rollback Rollback last deployment\n help Show this help\n\n EXAMPLES:\n /command init my-project\n /command deploy staging\n /command status\n /command rollback\n\n For detailed help on a subcommand:\n /command [subcommand] --help\n\n Exit.\nfi\n\n[Regular command processing...]\n```\n\n### Contextual Help\n\nProvide help based on context:\n\n```markdown\n---\ndescription: Context-aware command\nargument-hint: [operation] [target]\n---\n\n# Context-Aware Operation\n\nif [ -z \"$1\" ]; then\n **No operation specified**\n\n Available operations:\n - analyze: Analyze target for issues\n - fix: Apply automatic fixes\n - report: Generate detailed report\n\n Usage: /command [operation] [target]\n\n Examples:\n /command analyze src/\n /command fix src/app.js\n /command report\n\n Run /command help for more details.\n\n Exit.\nfi\n\n[Command continues if operation provided...]\n```\n\n## Error Message Documentation\n\n### Helpful Error Messages\n\n```markdown\n---\ndescription: Command with good error messages\n---\n\n# Validation Command\n\nif [ -z \"$1\" ]; then\n ❌ ERROR: Missing required argument\n\n The 'file-path' argument is required.\n\n USAGE:\n /validate [file-path]\n\n EXAMPLE:\n /validate src/app.js\n\n Try again with a file path.\n\n Exit.\nfi\n\nif [ ! -f \"$1\" ]; then\n ❌ ERROR: File not found: $1\n\n The specified file does not exist or is not accessible.\n\n COMMON CAUSES:\n 1. Typo in file path\n 2. File was deleted or moved\n 3. Insufficient permissions\n\n SUGGESTIONS:\n - Check spelling: $1\n - Verify file exists: ls -la $(dirname \"$1\")\n - Check permissions: ls -l \"$1\"\n\n Exit.\nfi\n\n[Command continues if validation passes...]\n```\n\n### Error Recovery Guidance\n\n```markdown\n---\ndescription: Command with recovery guidance\n---\n\n# Operation Command\n\nRunning operation...\n\n!`risky-operation.sh`\n\nif [ $? -ne 0 ]; then\n ❌ OPERATION FAILED\n\n The operation encountered an error and could not complete.\n\n WHAT HAPPENED:\n The risky-operation.sh script returned a non-zero exit code.\n\n WHAT THIS MEANS:\n - Changes may be partially applied\n - System may be in inconsistent state\n - Manual intervention may be needed\n\n RECOVERY STEPS:\n 1. Check operation logs: cat /tmp/operation.log\n 2. Verify system state: /check-state\n 3. If needed, rollback: /rollback-operation\n 4. Fix underlying issue\n 5. Retry operation: /retry-operation\n\n NEED HELP?\n - Check troubleshooting guide: /help troubleshooting\n - Contact support with error code: ERR_OP_FAILED_001\n\n Exit.\nfi\n```\n\n## Usage Example Documentation\n\n### Embedded Examples\n\n```markdown\n---\ndescription: Command with embedded examples\n---\n\n# Feature Command\n\nThis command performs feature analysis with multiple options.\n\n## Basic Usage\n\n\\`\\`\\`\n/feature analyze src/\n\\`\\`\\`\n\nAnalyzes all files in src/ directory for feature usage.\n\n## Advanced Usage\n\n\\`\\`\\`\n/feature analyze src/ --detailed\n\\`\\`\\`\n\nProvides detailed analysis including:\n- Feature breakdown by file\n- Usage patterns\n- Optimization suggestions\n\n## Use Cases\n\n**Use Case 1: Quick overview**\n\\`\\`\\`\n/feature analyze .\n\\`\\`\\`\nGet high-level feature summary of entire project.\n\n**Use Case 2: Specific directory**\n\\`\\`\\`\n/feature analyze src/components\n\\`\\`\\`\nFocus analysis on components directory only.\n\n**Use Case 3: Comparison**\n\\`\\`\\`\n/feature analyze src/ --compare baseline.json\n\\`\\`\\`\nCompare current features against baseline.\n\n---\n\nNow processing your request...\n\n[Command implementation...]\n```\n\n### Example-Driven Documentation\n\n```markdown\n---\ndescription: Example-heavy command\n---\n\n# Transformation Command\n\n## What This Does\n\nTransforms data from one format to another.\n\n## Examples First\n\n### Example 1: JSON to YAML\n**Input:** `data.json`\n\\`\\`\\`json\n{\"name\": \"test\", \"value\": 42}\n\\`\\`\\`\n\n**Command:** `/transform data.json yaml`\n\n**Output:** `data.yaml`\n\\`\\`\\`yaml\nname: test\nvalue: 42\n\\`\\`\\`\n\n### Example 2: CSV to JSON\n**Input:** `data.csv`\n\\`\\`\\`csv\nname,value\ntest,42\n\\`\\`\\`\n\n**Command:** `/transform data.csv json`\n\n**Output:** `data.json`\n\\`\\`\\`json\n[{\"name\": \"test\", \"value\": \"42\"}]\n\\`\\`\\`\n\n### Example 3: With Options\n**Command:** `/transform data.json yaml --pretty --sort-keys`\n\n**Result:** Formatted YAML with sorted keys\n\n---\n\n## Your Transformation\n\nFile: $1\nFormat: $2\n\n[Perform transformation...]\n```\n\n## Maintenance Documentation\n\n### Version and Changelog\n\n```markdown\n\n```\n\n### Maintenance Notes\n\n```markdown\n\n```\n\n## README Documentation\n\nCommands should have companion README files:\n\n```markdown\n# Command Name\n\nBrief description of what the command does.\n\n## Installation\n\nThis command is part of the [plugin-name] plugin.\n\nInstall with:\n\\`\\`\\`\n/plugin install plugin-name\n\\`\\`\\`\n\n## Usage\n\nBasic usage:\n\\`\\`\\`\n/command-name [arg1] [arg2]\n\\`\\`\\`\n\n## Arguments\n\n- `arg1`: Description (required)\n- `arg2`: Description (optional, defaults to X)\n\n## Examples\n\n### Example 1: Basic Usage\n\\`\\`\\`\n/command-name value1 value2\n\\`\\`\\`\n\nDescription of what happens.\n\n### Example 2: Advanced Usage\n\\`\\`\\`\n/command-name value1 --option\n\\`\\`\\`\n\nDescription of advanced feature.\n\n## Configuration\n\nOptional configuration file: `.claude/command-name.local.md`\n\n\\`\\`\\`markdown\n---\ndefault_arg: value\nenable_feature: true\n---\n\\`\\`\\`\n\n## Requirements\n\n- Git 2.x or later\n- jq (for JSON processing)\n- Node.js 14+ (optional, for advanced features)\n\n## Troubleshooting\n\n### Issue: Command not found\n\n**Solution:** Ensure plugin is installed and enabled.\n\n### Issue: Permission denied\n\n**Solution:** Check file permissions and allowed-tools setting.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT License - See [LICENSE](LICENSE).\n\n## Support\n\n- Issues: https://github.com/user/plugin/issues\n- Docs: https://docs.example.com\n- Email: support@example.com\n```\n\n## Best Practices\n\n### Documentation Principles\n\n1. **Write for your future self**: Assume you'll forget details\n2. **Examples before explanations**: Show, then tell\n3. **Progressive disclosure**: Basic info first, details available\n4. **Keep it current**: Update docs when code changes\n5. **Test your docs**: Verify examples actually work\n\n### Documentation Locations\n\n1. **In command file**: Core usage, examples, inline explanations\n2. **README**: Installation, configuration, troubleshooting\n3. **Separate docs**: Detailed guides, tutorials, API reference\n4. **Comments**: Implementation details for maintainers\n\n### Documentation Style\n\n1. **Clear and concise**: No unnecessary words\n2. **Active voice**: \"Run the command\" not \"The command can be run\"\n3. **Consistent terminology**: Use same terms throughout\n4. **Formatted well**: Use headings, lists, code blocks\n5. **Accessible**: Assume reader is beginner\n\n### Documentation Maintenance\n\n1. **Version everything**: Track what changed when\n2. **Deprecate gracefully**: Warn before removing features\n3. **Migration guides**: Help users upgrade\n4. **Archive old docs**: Keep old versions accessible\n5. **Review regularly**: Ensure docs match reality\n\n## Documentation Checklist\n\nBefore releasing a command:\n\n- [ ] Description in frontmatter is clear\n- [ ] argument-hint documents all arguments\n- [ ] Usage examples in comments\n- [ ] Common use cases shown\n- [ ] Error messages are helpful\n- [ ] Requirements documented\n- [ ] Related commands listed\n- [ ] Changelog maintained\n- [ ] Version number updated\n- [ ] README created/updated\n- [ ] Examples actually work\n- [ ] Troubleshooting section complete\n\nWith good documentation, commands become self-service, reducing support burden and improving user experience.\n","plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md":"# Command Frontmatter Reference\n\nComplete reference for YAML frontmatter fields in slash commands.\n\n## Frontmatter Overview\n\nYAML frontmatter is optional metadata at the start of command files:\n\n```markdown\n---\ndescription: Brief description\nallowed-tools: Read, Write\nmodel: sonnet\nargument-hint: [arg1] [arg2]\n---\n\nCommand prompt content here...\n```\n\nAll fields are optional. Commands work without any frontmatter.\n\n## Field Specifications\n\n### description\n\n**Type:** String\n**Required:** No\n**Default:** First line of command prompt\n**Max Length:** ~60 characters recommended for `/help` display\n\n**Purpose:** Describes what the command does, shown in `/help` output\n\n**Examples:**\n```yaml\ndescription: Review code for security issues\n```\n```yaml\ndescription: Deploy to staging environment\n```\n```yaml\ndescription: Generate API documentation\n```\n\n**Best practices:**\n- Keep under 60 characters for clean display\n- Start with verb (Review, Deploy, Generate)\n- Be specific about what command does\n- Avoid redundant \"command\" or \"slash command\"\n\n**Good:**\n- ✅ \"Review PR for code quality and security\"\n- ✅ \"Deploy application to specified environment\"\n- ✅ \"Generate comprehensive API documentation\"\n\n**Bad:**\n- ❌ \"This command reviews PRs\" (unnecessary \"This command\")\n- ❌ \"Review\" (too vague)\n- ❌ \"A command that reviews pull requests for code quality, security issues, and best practices\" (too long)\n\n### allowed-tools\n\n**Type:** String or Array of strings\n**Required:** No\n**Default:** Inherits from conversation permissions\n\n**Purpose:** Restrict or specify which tools command can use\n\n**Formats:**\n\n**Single tool:**\n```yaml\nallowed-tools: Read\n```\n\n**Multiple tools (comma-separated):**\n```yaml\nallowed-tools: Read, Write, Edit\n```\n\n**Multiple tools (array):**\n```yaml\nallowed-tools:\n - Read\n - Write\n - Bash(git:*)\n```\n\n**Tool Patterns:**\n\n**Specific tools:**\n```yaml\nallowed-tools: Read, Grep, Edit\n```\n\n**Bash with command filter:**\n```yaml\nallowed-tools: Bash(git:*) # Only git commands\nallowed-tools: Bash(npm:*) # Only npm commands\nallowed-tools: Bash(docker:*) # Only docker commands\n```\n\n**All tools (not recommended):**\n```yaml\nallowed-tools: \"*\"\n```\n\n**When to use:**\n\n1. **Security:** Restrict command to safe operations\n ```yaml\n allowed-tools: Read, Grep # Read-only command\n ```\n\n2. **Clarity:** Document required tools\n ```yaml\n allowed-tools: Bash(git:*), Read\n ```\n\n3. **Bash execution:** Enable bash command output\n ```yaml\n allowed-tools: Bash(git status:*), Bash(git diff:*)\n ```\n\n**Best practices:**\n- Be as restrictive as possible\n- Use command filters for Bash (e.g., `git:*` not `*`)\n- Only specify when different from conversation permissions\n- Document why specific tools are needed\n\n### model\n\n**Type:** String\n**Required:** No\n**Default:** Inherits from conversation\n**Values:** `sonnet`, `opus`, `haiku`\n\n**Purpose:** Specify which Claude model executes the command\n\n**Examples:**\n```yaml\nmodel: haiku # Fast, efficient for simple tasks\n```\n```yaml\nmodel: sonnet # Balanced performance (default)\n```\n```yaml\nmodel: opus # Maximum capability for complex tasks\n```\n\n**When to use:**\n\n**Use `haiku` for:**\n- Simple, formulaic commands\n- Fast execution needed\n- Low complexity tasks\n- Frequent invocations\n\n```yaml\n---\ndescription: Format code file\nmodel: haiku\n---\n```\n\n**Use `sonnet` for:**\n- Standard commands (default)\n- Balanced speed/quality\n- Most common use cases\n\n```yaml\n---\ndescription: Review code changes\nmodel: sonnet\n---\n```\n\n**Use `opus` for:**\n- Complex analysis\n- Architectural decisions\n- Deep code understanding\n- Critical tasks\n\n```yaml\n---\ndescription: Analyze system architecture\nmodel: opus\n---\n```\n\n**Best practices:**\n- Omit unless specific need\n- Use `haiku` for speed when possible\n- Reserve `opus` for genuinely complex tasks\n- Test with different models to find right balance\n\n### argument-hint\n\n**Type:** String\n**Required:** No\n**Default:** None\n\n**Purpose:** Document expected arguments for users and autocomplete\n\n**Format:**\n```yaml\nargument-hint: [arg1] [arg2] [optional-arg]\n```\n\n**Examples:**\n\n**Single argument:**\n```yaml\nargument-hint: [pr-number]\n```\n\n**Multiple required arguments:**\n```yaml\nargument-hint: [environment] [version]\n```\n\n**Optional arguments:**\n```yaml\nargument-hint: [file-path] [options]\n```\n\n**Descriptive names:**\n```yaml\nargument-hint: [source-branch] [target-branch] [commit-message]\n```\n\n**Best practices:**\n- Use square brackets `[]` for each argument\n- Use descriptive names (not `arg1`, `arg2`)\n- Indicate optional vs required in description\n- Match order to positional arguments in command\n- Keep concise but clear\n\n**Examples by pattern:**\n\n**Simple command:**\n```yaml\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$1...\n```\n\n**Multi-argument:**\n```yaml\n---\ndescription: Deploy to environment\nargument-hint: [app-name] [environment] [version]\n---\n\nDeploy $1 to $2 using version $3...\n```\n\n**With options:**\n```yaml\n---\ndescription: Run tests with options\nargument-hint: [test-pattern] [options]\n---\n\nRun tests matching $1 with options: $2\n```\n\n### disable-model-invocation\n\n**Type:** Boolean\n**Required:** No\n**Default:** false\n\n**Purpose:** Prevent SlashCommand tool from programmatically invoking command\n\n**Examples:**\n```yaml\ndisable-model-invocation: true\n```\n\n**When to use:**\n\n1. **Manual-only commands:** Commands requiring user judgment\n ```yaml\n ---\n description: Approve deployment to production\n disable-model-invocation: true\n ---\n ```\n\n2. **Destructive operations:** Commands with irreversible effects\n ```yaml\n ---\n description: Delete all test data\n disable-model-invocation: true\n ---\n ```\n\n3. **Interactive workflows:** Commands needing user input\n ```yaml\n ---\n description: Walk through setup wizard\n disable-model-invocation: true\n ---\n ```\n\n**Default behavior (false):**\n- Command available to SlashCommand tool\n- Claude can invoke programmatically\n- Still available for manual invocation\n\n**When true:**\n- Command only invokable by user typing `/command`\n- Not available to SlashCommand tool\n- Safer for sensitive operations\n\n**Best practices:**\n- Use sparingly (limits Claude's autonomy)\n- Document why in command comments\n- Consider if command should exist if always manual\n\n## Complete Examples\n\n### Minimal Command\n\nNo frontmatter needed:\n\n```markdown\nReview this code for common issues and suggest improvements.\n```\n\n### Simple Command\n\nJust description:\n\n```markdown\n---\ndescription: Review code for issues\n---\n\nReview this code for common issues and suggest improvements.\n```\n\n### Standard Command\n\nDescription and tools:\n\n```markdown\n---\ndescription: Review Git changes\nallowed-tools: Bash(git:*), Read\n---\n\nCurrent changes: !`git diff --name-only`\n\nReview each changed file for:\n- Code quality\n- Potential bugs\n- Best practices\n```\n\n### Complex Command\n\nAll common fields:\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [app-name] [environment] [version]\nallowed-tools: Bash(kubectl:*), Bash(helm:*), Read\nmodel: sonnet\n---\n\nDeploy $1 to $2 environment using version $3\n\nPre-deployment checks:\n- Verify $2 configuration\n- Check cluster status: !`kubectl cluster-info`\n- Validate version $3 exists\n\nProceed with deployment following deployment runbook.\n```\n\n### Manual-Only Command\n\nRestricted invocation:\n\n```markdown\n---\ndescription: Approve production deployment\nargument-hint: [deployment-id]\ndisable-model-invocation: true\nallowed-tools: Bash(gh:*)\n---\n\n\n\nReview deployment $1 for production approval:\n\nDeployment details: !`gh api /deployments/$1`\n\nVerify:\n- All tests passed\n- Security scan clean\n- Stakeholder approval\n- Rollback plan ready\n\nType \"APPROVED\" to confirm deployment.\n```\n\n## Validation\n\n### Common Errors\n\n**Invalid YAML syntax:**\n```yaml\n---\ndescription: Missing quote\nallowed-tools: Read, Write\nmodel: sonnet\n--- # ❌ Missing closing quote above\n```\n\n**Fix:** Validate YAML syntax\n\n**Incorrect tool specification:**\n```yaml\nallowed-tools: Bash # ❌ Missing command filter\n```\n\n**Fix:** Use `Bash(git:*)` format\n\n**Invalid model name:**\n```yaml\nmodel: gpt4 # ❌ Not a valid Claude model\n```\n\n**Fix:** Use `sonnet`, `opus`, or `haiku`\n\n### Validation Checklist\n\nBefore committing command:\n- [ ] YAML syntax valid (no errors)\n- [ ] Description under 60 characters\n- [ ] allowed-tools uses proper format\n- [ ] model is valid value if specified\n- [ ] argument-hint matches positional arguments\n- [ ] disable-model-invocation used appropriately\n\n## Best Practices Summary\n\n1. **Start minimal:** Add frontmatter only when needed\n2. **Document arguments:** Always use argument-hint with arguments\n3. **Restrict tools:** Use most restrictive allowed-tools that works\n4. **Choose right model:** Use haiku for speed, opus for complexity\n5. **Manual-only sparingly:** Only use disable-model-invocation when necessary\n6. **Clear descriptions:** Make commands discoverable in `/help`\n7. **Test thoroughly:** Verify frontmatter works as expected\n","plugins/plugin-dev/skills/command-development/references/interactive-commands.md":"# Interactive Command Patterns\n\nComprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.\n\n## Overview\n\nSome commands need user input that doesn't work well with simple arguments. For example:\n- Choosing between multiple complex options with trade-offs\n- Selecting multiple items from a list\n- Making decisions that require explanation\n- Gathering preferences or configuration interactively\n\nFor these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments.\n\n## When to Use AskUserQuestion\n\n### Use AskUserQuestion When:\n\n1. **Multiple choice decisions** with explanations needed\n2. **Complex options** that require context to choose\n3. **Multi-select scenarios** (choosing multiple items)\n4. **Preference gathering** for configuration\n5. **Interactive workflows** that adapt based on answers\n\n### Use Command Arguments When:\n\n1. **Simple values** (file paths, numbers, names)\n2. **Known inputs** user already has\n3. **Scriptable workflows** that should be automatable\n4. **Fast invocations** where prompting would slow down\n\n## AskUserQuestion Basics\n\n### Tool Parameters\n\n```typescript\n{\n questions: [\n {\n question: \"Which authentication method should we use?\",\n header: \"Auth method\", // Short label (max 12 chars)\n multiSelect: false, // true for multiple selection\n options: [\n {\n label: \"OAuth 2.0\",\n description: \"Industry standard, supports multiple providers\"\n },\n {\n label: \"JWT\",\n description: \"Stateless, good for APIs\"\n },\n {\n label: \"Session\",\n description: \"Traditional, server-side state\"\n }\n ]\n }\n ]\n}\n```\n\n**Key points:**\n- Users can always choose \"Other\" to provide custom input (automatic)\n- `multiSelect: true` allows selecting multiple options\n- Options should be 2-4 choices (not more)\n- Can ask 1-4 questions per tool call\n\n## Command Pattern for User Interaction\n\n### Basic Interactive Command\n\n```markdown\n---\ndescription: Interactive setup command\nallowed-tools: AskUserQuestion, Write\n---\n\n# Interactive Plugin Setup\n\nThis command will guide you through configuring the plugin with a series of questions.\n\n## Step 1: Gather Configuration\n\nUse the AskUserQuestion tool to ask:\n\n**Question 1 - Deployment target:**\n- header: \"Deploy to\"\n- question: \"Which deployment platform will you use?\"\n- options:\n - AWS (Amazon Web Services with ECS/EKS)\n - GCP (Google Cloud with GKE)\n - Azure (Microsoft Azure with AKS)\n - Local (Docker on local machine)\n\n**Question 2 - Environment strategy:**\n- header: \"Environments\"\n- question: \"How many environments do you need?\"\n- options:\n - Single (Just production)\n - Standard (Dev, Staging, Production)\n - Complete (Dev, QA, Staging, Production)\n\n**Question 3 - Features to enable:**\n- header: \"Features\"\n- question: \"Which features do you want to enable?\"\n- multiSelect: true\n- options:\n - Auto-scaling (Automatic resource scaling)\n - Monitoring (Health checks and metrics)\n - CI/CD (Automated deployment pipeline)\n - Backups (Automated database backups)\n\n## Step 2: Process Answers\n\nBased on the answers received from AskUserQuestion:\n\n1. Parse the deployment target choice\n2. Set up environment-specific configuration\n3. Enable selected features\n4. Generate configuration files\n\n## Step 3: Generate Configuration\n\nCreate `.claude/plugin-name.local.md` with:\n\n\\`\\`\\`yaml\n---\ndeployment_target: [answer from Q1]\nenvironments: [answer from Q2]\nfeatures:\n auto_scaling: [true if selected in Q3]\n monitoring: [true if selected in Q3]\n ci_cd: [true if selected in Q3]\n backups: [true if selected in Q3]\n---\n\n# Plugin Configuration\n\nGenerated: [timestamp]\nTarget: [deployment_target]\nEnvironments: [environments]\n\\`\\`\\`\n\n## Step 4: Confirm and Next Steps\n\nConfirm configuration created and guide user on next steps.\n```\n\n### Multi-Stage Interactive Workflow\n\n```markdown\n---\ndescription: Multi-stage interactive workflow\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Multi-Stage Deployment Setup\n\nThis command walks through deployment setup in stages, adapting based on your answers.\n\n## Stage 1: Basic Configuration\n\nUse AskUserQuestion to ask about deployment basics.\n\nBased on answers, determine which additional questions to ask.\n\n## Stage 2: Advanced Options (Conditional)\n\nIf user selected \"Advanced\" deployment in Stage 1:\n\nUse AskUserQuestion to ask about:\n- Load balancing strategy\n- Caching configuration\n- Security hardening options\n\nIf user selected \"Simple\" deployment:\n- Skip advanced questions\n- Use sensible defaults\n\n## Stage 3: Confirmation\n\nShow summary of all selections.\n\nUse AskUserQuestion for final confirmation:\n- header: \"Confirm\"\n- question: \"Does this configuration look correct?\"\n- options:\n - Yes (Proceed with setup)\n - No (Start over)\n - Modify (Let me adjust specific settings)\n\nIf \"Modify\", ask which specific setting to change.\n\n## Stage 4: Execute Setup\n\nBased on confirmed configuration, execute setup steps.\n```\n\n## Interactive Question Design\n\n### Question Structure\n\n**Good questions:**\n```markdown\nQuestion: \"Which database should we use for this project?\"\nHeader: \"Database\"\nOptions:\n - PostgreSQL (Relational, ACID compliant, best for complex queries)\n - MongoDB (Document store, flexible schema, best for rapid iteration)\n - Redis (In-memory, fast, best for caching and sessions)\n```\n\n**Poor questions:**\n```markdown\nQuestion: \"Database?\" // Too vague\nHeader: \"DB\" // Unclear abbreviation\nOptions:\n - Option 1 // Not descriptive\n - Option 2\n```\n\n### Option Design Best Practices\n\n**Clear labels:**\n- Use 1-5 words\n- Specific and descriptive\n- No jargon without context\n\n**Helpful descriptions:**\n- Explain what the option means\n- Mention key benefits or trade-offs\n- Help user make informed decision\n- Keep to 1-2 sentences\n\n**Appropriate number:**\n- 2-4 options per question\n- Don't overwhelm with too many choices\n- Group related options\n- \"Other\" automatically provided\n\n### Multi-Select Questions\n\n**When to use multiSelect:**\n\n```markdown\nUse AskUserQuestion for enabling features:\n\nQuestion: \"Which features do you want to enable?\"\nHeader: \"Features\"\nmultiSelect: true // Allow selecting multiple\nOptions:\n - Logging (Detailed operation logs)\n - Metrics (Performance monitoring)\n - Alerts (Error notifications)\n - Backups (Automatic backups)\n```\n\nUser can select any combination: none, some, or all.\n\n**When NOT to use multiSelect:**\n\n```markdown\nQuestion: \"Which authentication method?\"\nmultiSelect: false // Only one auth method makes sense\n```\n\nMutually exclusive choices should not use multiSelect.\n\n## Command Patterns with AskUserQuestion\n\n### Pattern 1: Simple Yes/No Decision\n\n```markdown\n---\ndescription: Command with confirmation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Destructive Operation\n\nThis operation will delete all cached data.\n\nUse AskUserQuestion to confirm:\n\nQuestion: \"This will delete all cached data. Are you sure?\"\nHeader: \"Confirm\"\nOptions:\n - Yes (Proceed with deletion)\n - No (Cancel operation)\n\nIf user selects \"Yes\":\n Execute deletion\n Report completion\n\nIf user selects \"No\":\n Cancel operation\n Exit without changes\n```\n\n### Pattern 2: Multiple Configuration Questions\n\n```markdown\n---\ndescription: Multi-question configuration\nallowed-tools: AskUserQuestion, Write\n---\n\n# Project Configuration Setup\n\nGather configuration through multiple questions.\n\nUse AskUserQuestion with multiple questions in one call:\n\n**Question 1:**\n- question: \"Which programming language?\"\n- header: \"Language\"\n- options: Python, TypeScript, Go, Rust\n\n**Question 2:**\n- question: \"Which test framework?\"\n- header: \"Testing\"\n- options: Jest, PyTest, Go Test, Cargo Test\n (Adapt based on language from Q1)\n\n**Question 3:**\n- question: \"Which CI/CD platform?\"\n- header: \"CI/CD\"\n- options: GitHub Actions, GitLab CI, CircleCI\n\n**Question 4:**\n- question: \"Which features do you need?\"\n- header: \"Features\"\n- multiSelect: true\n- options: Linting, Type checking, Code coverage, Security scanning\n\nProcess all answers together to generate cohesive configuration.\n```\n\n### Pattern 3: Conditional Question Flow\n\n```markdown\n---\ndescription: Conditional interactive workflow\nallowed-tools: AskUserQuestion, Read, Write\n---\n\n# Adaptive Configuration\n\n## Question 1: Deployment Complexity\n\nUse AskUserQuestion:\n\nQuestion: \"How complex is your deployment?\"\nHeader: \"Complexity\"\nOptions:\n - Simple (Single server, straightforward)\n - Standard (Multiple servers, load balancing)\n - Complex (Microservices, orchestration)\n\n## Conditional Questions Based on Answer\n\nIf answer is \"Simple\":\n - No additional questions\n - Use minimal configuration\n\nIf answer is \"Standard\":\n - Ask about load balancing strategy\n - Ask about scaling policy\n\nIf answer is \"Complex\":\n - Ask about orchestration platform (Kubernetes, Docker Swarm)\n - Ask about service mesh (Istio, Linkerd, None)\n - Ask about monitoring (Prometheus, Datadog, CloudWatch)\n - Ask about logging aggregation\n\n## Process Conditional Answers\n\nGenerate configuration appropriate for selected complexity level.\n```\n\n### Pattern 4: Iterative Collection\n\n```markdown\n---\ndescription: Collect multiple items iteratively\nallowed-tools: AskUserQuestion, Write\n---\n\n# Collect Team Members\n\nWe'll collect team member information for the project.\n\n## Question: How many team members?\n\nUse AskUserQuestion:\n\nQuestion: \"How many team members should we set up?\"\nHeader: \"Team size\"\nOptions:\n - 2 people\n - 3 people\n - 4 people\n - 6 people\n\n## Iterate Through Team Members\n\nFor each team member (1 to N based on answer):\n\nUse AskUserQuestion for member details:\n\nQuestion: \"What role for team member [number]?\"\nHeader: \"Role\"\nOptions:\n - Frontend Developer\n - Backend Developer\n - DevOps Engineer\n - QA Engineer\n - Designer\n\nStore each member's information.\n\n## Generate Team Configuration\n\nAfter collecting all N members, create team configuration file with all members and their roles.\n```\n\n### Pattern 5: Dependency Selection\n\n```markdown\n---\ndescription: Select dependencies with multi-select\nallowed-tools: AskUserQuestion\n---\n\n# Configure Project Dependencies\n\n## Question: Required Libraries\n\nUse AskUserQuestion with multiSelect:\n\nQuestion: \"Which libraries does your project need?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - React (UI framework)\n - Express (Web server)\n - TypeORM (Database ORM)\n - Jest (Testing framework)\n - Axios (HTTP client)\n\nUser can select any combination.\n\n## Process Selections\n\nFor each selected library:\n- Add to package.json dependencies\n- Generate sample configuration\n- Create usage examples\n- Update documentation\n```\n\n## Best Practices for Interactive Commands\n\n### Question Design\n\n1. **Clear and specific**: Question should be unambiguous\n2. **Concise header**: Max 12 characters for clean display\n3. **Helpful options**: Labels are clear, descriptions explain trade-offs\n4. **Appropriate count**: 2-4 options per question, 1-4 questions per call\n5. **Logical order**: Questions flow naturally\n\n### Error Handling\n\n```markdown\n# Handle AskUserQuestion Responses\n\nAfter calling AskUserQuestion, verify answers received:\n\nIf answers are empty or invalid:\n Something went wrong gathering responses.\n\n Please try again or provide configuration manually:\n [Show alternative approach]\n\n Exit.\n\nIf answers look correct:\n Process as expected\n```\n\n### Progressive Disclosure\n\n```markdown\n# Start Simple, Get Detailed as Needed\n\n## Question 1: Setup Type\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to set up?\"\nHeader: \"Setup type\"\nOptions:\n - Quick (Use recommended defaults)\n - Custom (Configure all options)\n - Guided (Step-by-step with explanations)\n\nIf \"Quick\":\n Apply defaults, minimal questions\n\nIf \"Custom\":\n Ask all available configuration questions\n\nIf \"Guided\":\n Ask questions with extra explanation\n Provide recommendations along the way\n```\n\n### Multi-Select Guidelines\n\n**Good multi-select use:**\n```markdown\nQuestion: \"Which features do you want to enable?\"\nmultiSelect: true\nOptions:\n - Logging\n - Metrics\n - Alerts\n - Backups\n\nReason: User might want any combination\n```\n\n**Bad multi-select use:**\n```markdown\nQuestion: \"Which database engine?\"\nmultiSelect: true // ❌ Should be single-select\n\nReason: Can only use one database engine\n```\n\n## Advanced Patterns\n\n### Validation Loop\n\n```markdown\n---\ndescription: Interactive with validation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Setup with Validation\n\n## Gather Configuration\n\nUse AskUserQuestion to collect settings.\n\n## Validate Configuration\n\nCheck if configuration is valid:\n- Required dependencies available?\n- Settings compatible with each other?\n- No conflicts detected?\n\nIf validation fails:\n Show validation errors\n\n Use AskUserQuestion to ask:\n\n Question: \"Configuration has issues. What would you like to do?\"\n Header: \"Next step\"\n Options:\n - Fix (Adjust settings to resolve issues)\n - Override (Proceed despite warnings)\n - Cancel (Abort setup)\n\n Based on answer, retry or proceed or exit.\n```\n\n### Build Configuration Incrementally\n\n```markdown\n---\ndescription: Incremental configuration builder\nallowed-tools: AskUserQuestion, Write, Read\n---\n\n# Incremental Setup\n\n## Phase 1: Core Settings\n\nUse AskUserQuestion for core settings.\n\nSave to `.claude/config-partial.yml`\n\n## Phase 2: Review Core Settings\n\nShow user the core settings:\n\nBased on these core settings, you need to configure:\n- [Setting A] (because you chose [X])\n- [Setting B] (because you chose [Y])\n\nReady to continue?\n\n## Phase 3: Detailed Settings\n\nUse AskUserQuestion for settings based on Phase 1 answers.\n\nMerge with core settings.\n\n## Phase 4: Final Review\n\nPresent complete configuration.\n\nUse AskUserQuestion for confirmation:\n\nQuestion: \"Is this configuration correct?\"\nOptions:\n - Yes (Save and apply)\n - No (Start over)\n - Modify (Edit specific settings)\n```\n\n### Dynamic Options Based on Context\n\n```markdown\n---\ndescription: Context-aware questions\nallowed-tools: AskUserQuestion, Bash, Read\n---\n\n# Context-Aware Setup\n\n## Detect Current State\n\nCheck existing configuration:\n- Current language: !`detect-language.sh`\n- Existing frameworks: !`detect-frameworks.sh`\n- Available tools: !`check-tools.sh`\n\n## Ask Context-Appropriate Questions\n\nBased on detected language, ask relevant questions.\n\nIf language is TypeScript:\n\n Use AskUserQuestion:\n\n Question: \"Which TypeScript features should we enable?\"\n Options:\n - Strict Mode (Maximum type safety)\n - Decorators (Experimental decorator support)\n - Path Mapping (Module path aliases)\n\nIf language is Python:\n\n Use AskUserQuestion:\n\n Question: \"Which Python tools should we configure?\"\n Options:\n - Type Hints (mypy for type checking)\n - Black (Code formatting)\n - Pylint (Linting and style)\n\nQuestions adapt to project context.\n```\n\n## Real-World Example: Multi-Agent Swarm Launch\n\n**From multi-agent-swarm plugin:**\n\n```markdown\n---\ndescription: Launch multi-agent swarm\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Launch Multi-Agent Swarm\n\n## Interactive Mode (No Task List Provided)\n\nIf user didn't provide task list file, help create one interactively.\n\n### Question 1: Agent Count\n\nUse AskUserQuestion:\n\nQuestion: \"How many agents should we launch?\"\nHeader: \"Agent count\"\nOptions:\n - 2 agents (Best for simple projects)\n - 3 agents (Good for medium projects)\n - 4 agents (Standard team size)\n - 6 agents (Large projects)\n - 8 agents (Complex multi-component projects)\n\n### Question 2: Task Definition Approach\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to define tasks?\"\nHeader: \"Task setup\"\nOptions:\n - File (I have a task list file ready)\n - Guided (Help me create tasks interactively)\n - Custom (Other approach)\n\nIf \"File\":\n Ask for file path\n Validate file exists and has correct format\n\nIf \"Guided\":\n Enter iterative task creation mode (see below)\n\n### Question 3: Coordination Mode\n\nUse AskUserQuestion:\n\nQuestion: \"How should agents coordinate?\"\nHeader: \"Coordination\"\nOptions:\n - Team Leader (One agent coordinates others)\n - Collaborative (Agents coordinate as peers)\n - Autonomous (Independent work, minimal coordination)\n\n### Iterative Task Creation (If \"Guided\" Selected)\n\nFor each agent (1 to N from Question 1):\n\n**Question A: Agent Name**\nQuestion: \"What should we call agent [number]?\"\nHeader: \"Agent name\"\nOptions:\n - auth-agent\n - api-agent\n - ui-agent\n - db-agent\n (Provide relevant suggestions based on common patterns)\n\n**Question B: Task Type**\nQuestion: \"What task for [agent-name]?\"\nHeader: \"Task type\"\nOptions:\n - Authentication (User auth, JWT, OAuth)\n - API Endpoints (REST/GraphQL APIs)\n - UI Components (Frontend components)\n - Database (Schema, migrations, queries)\n - Testing (Test suites and coverage)\n - Documentation (Docs, README, guides)\n\n**Question C: Dependencies**\nQuestion: \"What does [agent-name] depend on?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - [List of previously defined agents]\n - No dependencies\n\n**Question D: Base Branch**\nQuestion: \"Which base branch for PR?\"\nHeader: \"PR base\"\nOptions:\n - main\n - staging\n - develop\n\nStore all task information for each agent.\n\n### Generate Task List File\n\nAfter collecting all agent task details:\n\n1. Ask for project name\n2. Generate task list in proper format\n3. Save to `.daisy/swarm/tasks.md`\n4. Show user the file path\n5. Proceed with launch using generated task list\n```\n\n## Best Practices\n\n### Question Writing\n\n1. **Be specific**: \"Which database?\" not \"Choose option?\"\n2. **Explain trade-offs**: Describe pros/cons in option descriptions\n3. **Provide context**: Question text should stand alone\n4. **Guide decisions**: Help user make informed choice\n5. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences\n\n### Option Design\n\n1. **Meaningful labels**: Specific, clear names\n2. **Informative descriptions**: Explain what each option does\n3. **Show trade-offs**: Help user understand implications\n4. **Consistent detail**: All options equally explained\n5. **2-4 options**: Not too few, not too many\n\n### Flow Design\n\n1. **Logical order**: Questions flow naturally\n2. **Build on previous**: Later questions use earlier answers\n3. **Minimize questions**: Ask only what's needed\n4. **Group related**: Ask related questions together\n5. **Show progress**: Indicate where in flow\n\n### User Experience\n\n1. **Set expectations**: Tell user what to expect\n2. **Explain why**: Help user understand purpose\n3. **Provide defaults**: Suggest recommended options\n4. **Allow escape**: Let user cancel or restart\n5. **Confirm actions**: Summarize before executing\n\n## Common Patterns\n\n### Pattern: Feature Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which features do you need?\"\nHeader: \"Features\"\nmultiSelect: true\nOptions:\n - Authentication\n - Authorization\n - Rate Limiting\n - Caching\n```\n\n### Pattern: Environment Configuration\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which environment is this?\"\nHeader: \"Environment\"\nOptions:\n - Development (Local development)\n - Staging (Pre-production testing)\n - Production (Live environment)\n```\n\n### Pattern: Priority Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What's the priority for this task?\"\nHeader: \"Priority\"\nOptions:\n - Critical (Must be done immediately)\n - High (Important, do soon)\n - Medium (Standard priority)\n - Low (Nice to have)\n```\n\n### Pattern: Scope Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What scope should we analyze?\"\nHeader: \"Scope\"\nOptions:\n - Current file (Just this file)\n - Current directory (All files in directory)\n - Entire project (Full codebase scan)\n```\n\n## Combining Arguments and Questions\n\n### Use Both Appropriately\n\n**Arguments for known values:**\n```markdown\n---\nargument-hint: [project-name]\nallowed-tools: AskUserQuestion, Write\n---\n\nSetup for project: $1\n\nNow gather additional configuration...\n\nUse AskUserQuestion for options that require explanation.\n```\n\n**Questions for complex choices:**\n```markdown\nProject name from argument: $1\n\nNow use AskUserQuestion to choose:\n- Architecture pattern\n- Technology stack\n- Deployment strategy\n\nThese require explanation, so questions work better than arguments.\n```\n\n## Troubleshooting\n\n**Questions not appearing:**\n- Verify AskUserQuestion in allowed-tools\n- Check question format is correct\n- Ensure options array has 2-4 items\n\n**User can't make selection:**\n- Check option labels are clear\n- Verify descriptions are helpful\n- Consider if too many options\n- Ensure multiSelect setting is correct\n\n**Flow feels confusing:**\n- Reduce number of questions\n- Group related questions\n- Add explanation between stages\n- Show progress through workflow\n\nWith AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.\n","plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md":"# Marketplace Considerations for Commands\n\nGuidelines for creating commands designed for distribution and marketplace success.\n\n## Overview\n\nCommands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.\n\n## Design for Distribution\n\n### Universal Compatibility\n\n**Cross-platform considerations:**\n\n```markdown\n---\ndescription: Cross-platform command\nallowed-tools: Bash(*)\n---\n\n# Platform-Aware Command\n\nDetecting platform...\n\ncase \"$(uname)\" in\n Darwin*) PLATFORM=\"macOS\" ;;\n Linux*) PLATFORM=\"Linux\" ;;\n MINGW*|MSYS*|CYGWIN*) PLATFORM=\"Windows\" ;;\n *) PLATFORM=\"Unknown\" ;;\nesac\n\nPlatform: $PLATFORM\n\n\nif [ \"$PLATFORM\" = \"Windows\" ]; then\n # Windows-specific handling\n PATH_SEP=\"\\\\\"\n NULL_DEVICE=\"NUL\"\nelse\n # Unix-like handling\n PATH_SEP=\"/\"\n NULL_DEVICE=\"/dev/null\"\nfi\n\n[Platform-appropriate implementation...]\n```\n\n**Avoid platform-specific commands:**\n\n```markdown\n\n!`pbcopy < file.txt`\n\n\nif command -v pbcopy > /dev/null; then\n pbcopy < file.txt\nelif command -v xclip > /dev/null; then\n xclip -selection clipboard < file.txt\nelif command -v clip.exe > /dev/null; then\n cat file.txt | clip.exe\nelse\n echo \"Clipboard not available on this platform\"\nfi\n```\n\n### Minimal Dependencies\n\n**Check for required tools:**\n\n```markdown\n---\ndescription: Dependency-aware command\nallowed-tools: Bash(*)\n---\n\n# Check Dependencies\n\nRequired tools:\n- git\n- jq\n- node\n\nChecking availability...\n\nMISSING_DEPS=\"\"\n\nfor tool in git jq node; do\n if ! command -v $tool > /dev/null; then\n MISSING_DEPS=\"$MISSING_DEPS $tool\"\n fi\ndone\n\nif [ -n \"$MISSING_DEPS\" ]; then\n ❌ ERROR: Missing required dependencies:$MISSING_DEPS\n\n INSTALLATION:\n - git: https://git-scm.com/downloads\n - jq: https://stedolan.github.io/jq/download/\n - node: https://nodejs.org/\n\n Install missing tools and try again.\n\n Exit.\nfi\n\n✓ All dependencies available\n\n[Continue with command...]\n```\n\n**Document optional dependencies:**\n\n```markdown\n\n```\n\n### Graceful Degradation\n\n**Handle missing features:**\n\n```markdown\n---\ndescription: Feature-aware command\n---\n\n# Feature Detection\n\nDetecting available features...\n\nFEATURES=\"\"\n\nif command -v gh > /dev/null; then\n FEATURES=\"$FEATURES github\"\nfi\n\nif command -v docker > /dev/null; then\n FEATURES=\"$FEATURES docker\"\nfi\n\nAvailable features: $FEATURES\n\nif echo \"$FEATURES\" | grep -q \"github\"; then\n # Full functionality with GitHub integration\n echo \"✓ GitHub integration available\"\nelse\n # Reduced functionality without GitHub\n echo \"⚠ Limited functionality: GitHub CLI not installed\"\n echo \" Install 'gh' for full features\"\nfi\n\n[Adapt behavior based on available features...]\n```\n\n## User Experience for Unknown Users\n\n### Clear Onboarding\n\n**First-run experience:**\n\n```markdown\n---\ndescription: Command with onboarding\nallowed-tools: Read, Write\n---\n\n# First Run Check\n\nif [ ! -f \".claude/command-initialized\" ]; then\n **Welcome to Command Name!**\n\n This appears to be your first time using this command.\n\n WHAT THIS COMMAND DOES:\n [Brief explanation of purpose and benefits]\n\n QUICK START:\n 1. Basic usage: /command [arg]\n 2. For help: /command help\n 3. Examples: /command examples\n\n SETUP:\n No additional setup required. You're ready to go!\n\n ✓ Initialization complete\n\n [Create initialization marker]\n\n Ready to proceed with your request...\nfi\n\n[Normal command execution...]\n```\n\n**Progressive feature discovery:**\n\n```markdown\n---\ndescription: Command with tips\n---\n\n# Command Execution\n\n[Main functionality...]\n\n---\n\n💡 TIP: Did you know?\n\nYou can speed up this command with the --fast flag:\n /command --fast [args]\n\nFor more tips: /command tips\n```\n\n### Comprehensive Error Handling\n\n**Anticipate user mistakes:**\n\n```markdown\n---\ndescription: Forgiving command\n---\n\n# User Input Handling\n\nArgument: \"$1\"\n\n\nif [ \"$1\" = \"hlep\" ] || [ \"$1\" = \"hepl\" ]; then\n Did you mean: help?\n\n Showing help instead...\n [Display help]\n\n Exit.\nfi\n\n\nif [ \"$1\" != \"valid-option1\" ] && [ \"$1\" != \"valid-option2\" ]; then\n ❌ Unknown option: $1\n\n Did you mean:\n - valid-option1 (most similar)\n - valid-option2\n\n For all options: /command help\n\n Exit.\nfi\n\n[Command continues...]\n```\n\n**Helpful diagnostics:**\n\n```markdown\n---\ndescription: Diagnostic command\n---\n\n# Operation Failed\n\nThe operation could not complete.\n\n**Diagnostic Information:**\n\nEnvironment:\n- Platform: $(uname)\n- Shell: $SHELL\n- Working directory: $(pwd)\n- Command: /command $@\n\nChecking common issues:\n- Git repository: $(git rev-parse --git-dir 2>&1)\n- Write permissions: $(test -w . && echo \"OK\" || echo \"DENIED\")\n- Required files: $(test -f config.yml && echo \"Found\" || echo \"Missing\")\n\nThis information helps debug the issue.\n\nFor support, include the above diagnostics.\n```\n\n## Distribution Best Practices\n\n### Namespace Awareness\n\n**Avoid name collisions:**\n\n```markdown\n---\ndescription: Namespaced command\n---\n\n\n\n# Plugin Name Command\n\n[Implementation...]\n```\n\n**Document naming rationale:**\n\n```markdown\n\n```\n\n### Configurability\n\n**User preferences:**\n\n```markdown\n---\ndescription: Configurable command\nallowed-tools: Read\n---\n\n# Load User Configuration\n\nDefault configuration:\n- verbose: false\n- color: true\n- max_results: 10\n\nChecking for user config: .claude/plugin-name.local.md\n\nif [ -f \".claude/plugin-name.local.md\" ]; then\n # Parse YAML frontmatter for settings\n VERBOSE=$(grep \"^verbose:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n COLOR=$(grep \"^color:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n MAX_RESULTS=$(grep \"^max_results:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n\n echo \"✓ Using user configuration\"\nelse\n echo \"Using default configuration\"\n echo \"Create .claude/plugin-name.local.md to customize\"\nfi\n\n[Use configuration in command...]\n```\n\n**Sensible defaults:**\n\n```markdown\n---\ndescription: Command with smart defaults\n---\n\n# Smart Defaults\n\nConfiguration:\n- Format: ${FORMAT:-json} # Defaults to json\n- Output: ${OUTPUT:-stdout} # Defaults to stdout\n- Verbose: ${VERBOSE:-false} # Defaults to false\n\nThese defaults work for 80% of use cases.\n\nOverride with arguments:\n /command --format yaml --output file.txt --verbose\n\nOr set in .claude/plugin-name.local.md:\n\\`\\`\\`yaml\n---\nformat: yaml\noutput: custom.txt\nverbose: true\n---\n\\`\\`\\`\n```\n\n### Version Compatibility\n\n**Version checking:**\n\n```markdown\n---\ndescription: Version-aware command\n---\n\n\n\n# Version Check\n\nCommand version: 2.1.0\nPlugin version: [detect from plugin.json]\n\nif [ \"$PLUGIN_VERSION\" < \"2.0.0\" ]; then\n ❌ ERROR: Incompatible plugin version\n\n This command requires plugin version >= 2.0.0\n Current version: $PLUGIN_VERSION\n\n Update plugin:\n /plugin update plugin-name\n\n Exit.\nfi\n\n✓ Version compatible\n\n[Command continues...]\n```\n\n**Deprecation warnings:**\n\n```markdown\n---\ndescription: Command with deprecation warnings\n---\n\n# Deprecation Check\n\nif [ \"$1\" = \"--old-flag\" ]; then\n ⚠️ DEPRECATION WARNING\n\n The --old-flag option is deprecated as of v2.0.0\n It will be removed in v3.0.0 (est. June 2025)\n\n Use instead: --new-flag\n\n Example:\n Old: /command --old-flag value\n New: /command --new-flag value\n\n See migration guide: /command migrate\n\n Continuing with deprecated behavior for now...\nfi\n\n[Handle both old and new flags during deprecation period...]\n```\n\n## Marketplace Presentation\n\n### Command Discovery\n\n**Descriptive naming:**\n\n```markdown\n---\ndescription: Review pull request with security and quality checks\n---\n\n\n```\n\n```markdown\n---\ndescription: Do the thing\n---\n\n\n```\n\n**Searchable keywords:**\n\n```markdown\n\n```\n\n### Showcase Examples\n\n**Compelling demonstrations:**\n\n```markdown\n---\ndescription: Advanced code analysis command\n---\n\n# Code Analysis Command\n\nThis command performs deep code analysis with actionable insights.\n\n## Demo: Quick Security Audit\n\nTry it now:\n\\`\\`\\`\n/analyze-code src/ --security\n\\`\\`\\`\n\n**What you'll get:**\n- Security vulnerability detection\n- Code quality metrics\n- Performance bottleneck identification\n- Actionable recommendations\n\n**Sample output:**\n\\`\\`\\`\nSecurity Analysis Results\n=========================\n\n🔴 Critical (2):\n - SQL injection risk in users.js:45\n - XSS vulnerability in display.js:23\n\n🟡 Warnings (5):\n - Unvalidated input in api.js:67\n ...\n\nRecommendations:\n1. Fix critical issues immediately\n2. Review warnings before next release\n3. Run /analyze-code --fix for auto-fixes\n\\`\\`\\`\n\n---\n\nReady to analyze your code...\n\n[Command implementation...]\n```\n\n### User Reviews and Feedback\n\n**Feedback mechanism:**\n\n```markdown\n---\ndescription: Command with feedback\n---\n\n# Command Complete\n\n[Command results...]\n\n---\n\n**How was your experience?**\n\nThis helps improve the command for everyone.\n\nRate this command:\n- 👍 Helpful\n- 👎 Not helpful\n- 🐛 Found a bug\n- 💡 Have a suggestion\n\nReply with an emoji or:\n- /command feedback\n\nYour feedback matters!\n```\n\n**Usage analytics preparation:**\n\n```markdown\n\n```\n\n## Quality Standards\n\n### Professional Polish\n\n**Consistent branding:**\n\n```markdown\n---\ndescription: Branded command\n---\n\n# ✨ Command Name\n\nPart of the [Plugin Name] suite\n\n[Command functionality...]\n\n---\n\n**Need Help?**\n- Documentation: https://docs.example.com\n- Support: support@example.com\n- Community: https://community.example.com\n\nPowered by Plugin Name v2.1.0\n```\n\n**Attention to detail:**\n\n```markdown\n\n\n✓ Use proper emoji/symbols consistently\n✓ Align output columns neatly\n✓ Format numbers with thousands separators\n✓ Use color/formatting appropriately\n✓ Provide progress indicators\n✓ Show estimated time remaining\n✓ Confirm successful operations\n```\n\n### Reliability\n\n**Idempotency:**\n\n```markdown\n---\ndescription: Idempotent command\n---\n\n# Safe Repeated Execution\n\nChecking if operation already completed...\n\nif [ -f \".claude/operation-completed.flag\" ]; then\n ℹ️ Operation already completed\n\n Completed at: $(cat .claude/operation-completed.flag)\n\n To re-run:\n 1. Remove flag: rm .claude/operation-completed.flag\n 2. Run command again\n\n Otherwise, no action needed.\n\n Exit.\nfi\n\nPerforming operation...\n\n[Safe, repeatable operation...]\n\nMarking complete...\necho \"$(date)\" > .claude/operation-completed.flag\n```\n\n**Atomic operations:**\n\n```markdown\n---\ndescription: Atomic command\n---\n\n# Atomic Operation\n\nThis operation is atomic - either fully succeeds or fully fails.\n\nCreating temporary workspace...\nTEMP_DIR=$(mktemp -d)\n\nPerforming changes in isolated environment...\n[Make changes in $TEMP_DIR]\n\nif [ $? -eq 0 ]; then\n ✓ Changes validated\n\n Applying changes atomically...\n mv $TEMP_DIR/* ./target/\n\n ✓ Operation complete\nelse\n ❌ Changes failed validation\n\n Rolling back...\n rm -rf $TEMP_DIR\n\n No changes applied. Safe to retry.\nfi\n```\n\n## Testing for Distribution\n\n### Pre-Release Checklist\n\n```markdown\n\n```\n\n### Beta Testing\n\n**Beta release approach:**\n\n```markdown\n---\ndescription: Beta command (v0.9.0)\n---\n\n# 🧪 Beta Command\n\n**This is a beta release**\n\nFeatures may change based on feedback.\n\nBETA STATUS:\n- Version: 0.9.0\n- Stability: Experimental\n- Support: Limited\n- Feedback: Encouraged\n\nKnown limitations:\n- Performance not optimized\n- Some edge cases not handled\n- Documentation incomplete\n\nHelp improve this command:\n- Report issues: /command report-issue\n- Suggest features: /command suggest\n- Join beta testers: /command join-beta\n\n---\n\n[Command implementation...]\n\n---\n\n**Thank you for beta testing!**\n\nYour feedback helps make this command better.\n```\n\n## Maintenance and Updates\n\n### Update Strategy\n\n**Versioned commands:**\n\n```markdown\n\n```\n\n**Update notifications:**\n\n```markdown\n---\ndescription: Update-aware command\n---\n\n# Check for Updates\n\nCurrent version: 2.1.0\nLatest version: [check if available]\n\nif [ \"$CURRENT_VERSION\" != \"$LATEST_VERSION\" ]; then\n 📢 UPDATE AVAILABLE\n\n New version: $LATEST_VERSION\n Current: $CURRENT_VERSION\n\n What's new:\n - Feature improvements\n - Bug fixes\n - Performance enhancements\n\n Update with:\n /plugin update plugin-name\n\n Release notes: https://releases.example.com/v$LATEST_VERSION\nfi\n\n[Command continues...]\n```\n\n## Best Practices Summary\n\n### Distribution Design\n\n1. **Universal**: Works across platforms and environments\n2. **Self-contained**: Minimal dependencies, clear requirements\n3. **Graceful**: Degrades gracefully when features unavailable\n4. **Forgiving**: Anticipates and handles user mistakes\n5. **Helpful**: Clear errors, good defaults, excellent docs\n\n### Marketplace Success\n\n1. **Discoverable**: Clear name, good description, searchable keywords\n2. **Professional**: Polished presentation, consistent branding\n3. **Reliable**: Tested thoroughly, handles edge cases\n4. **Maintainable**: Versioned, updated regularly, supported\n5. **User-focused**: Great UX, responsive to feedback\n\n### Quality Standards\n\n1. **Complete**: Fully documented, all features working\n2. **Tested**: Works in real environments, edge cases handled\n3. **Secure**: No vulnerabilities, safe operations\n4. **Performant**: Reasonable speed, resource-efficient\n5. **Ethical**: Privacy-respecting, user consent\n\nWith these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.\n","plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md":"# Plugin-Specific Command Features Reference\n\nThis reference covers features and patterns specific to commands bundled in Claude Code plugins.\n\n## Table of Contents\n\n- [Plugin Command Discovery](#plugin-command-discovery)\n- [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable)\n- [Plugin Command Patterns](#plugin-command-patterns)\n- [Integration with Plugin Components](#integration-with-plugin-components)\n- [Validation Patterns](#validation-patterns)\n\n## Plugin Command Discovery\n\n### Auto-Discovery\n\nClaude Code automatically discovers commands in plugins using the following locations:\n\n```\nplugin-name/\n├── commands/ # Auto-discovered commands\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ └── bar.md # /bar (plugin:plugin-name)\n└── plugin.json # Plugin manifest\n```\n\n**Key points:**\n- Commands are discovered at plugin load time\n- No manual registration required\n- Commands appear in `/help` with \"(plugin:plugin-name)\" label\n- Subdirectories create namespaces\n\n### Namespaced Plugin Commands\n\nOrganize commands in subdirectories for logical grouping:\n\n```\nplugin-name/\n└── commands/\n ├── review/\n │ ├── security.md # /security (plugin:plugin-name:review)\n │ └── style.md # /style (plugin:plugin-name:review)\n └── deploy/\n ├── staging.md # /staging (plugin:plugin-name:deploy)\n └── prod.md # /prod (plugin:plugin-name:deploy)\n```\n\n**Namespace behavior:**\n- Subdirectory name becomes namespace\n- Shown as \"(plugin:plugin-name:namespace)\" in `/help`\n- Helps organize related commands\n- Use when plugin has 5+ commands\n\n### Command Naming Conventions\n\n**Plugin command names should:**\n1. Be descriptive and action-oriented\n2. Avoid conflicts with common command names\n3. Use hyphens for multi-word names\n4. Consider prefixing with plugin name for uniqueness\n\n**Examples:**\n```\nGood:\n- /mylyn-sync (plugin-specific prefix)\n- /analyze-performance (descriptive action)\n- /docker-compose-up (clear purpose)\n\nAvoid:\n- /test (conflicts with common name)\n- /run (too generic)\n- /do-stuff (not descriptive)\n```\n\n## CLAUDE_PLUGIN_ROOT Environment Variable\n\n### Purpose\n\n`${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory.\n\n**Why it matters:**\n- Enables portable paths within plugin\n- Allows referencing plugin files and scripts\n- Works across different installations\n- Essential for multi-file plugin operations\n\n### Basic Usage\n\nReference files within your plugin:\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*), Read\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n\nRead template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md\n```\n\n**Expands to:**\n```\nRun analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js`\n\nRead template: @/path/to/plugins/plugin-name/templates/report.md\n```\n\n### Common Patterns\n\n#### 1. Executing Plugin Scripts\n\n```markdown\n---\ndescription: Run custom linter from plugin\nallowed-tools: Bash(node:*)\n---\n\nLint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`\n\nReview the linting output and suggest fixes.\n```\n\n#### 2. Loading Configuration Files\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nallowed-tools: Read, Bash(*)\n---\n\nConfiguration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json\n\nDeploy application using the configuration above for $1 environment.\n```\n\n#### 3. Accessing Plugin Resources\n\n```markdown\n---\ndescription: Generate report from template\n---\n\nUse this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md\n\nGenerate a report for @$1 following the template format.\n```\n\n#### 4. Multi-Step Plugin Workflows\n\n```markdown\n---\ndescription: Complete plugin workflow\nallowed-tools: Bash(*), Read\n---\n\nStep 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`\nStep 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\nStep 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`\n\nReview results and report status.\n```\n\n### Best Practices\n\n1. **Always use for plugin-internal paths:**\n ```markdown\n # Good\n @${CLAUDE_PLUGIN_ROOT}/templates/foo.md\n\n # Bad\n @./templates/foo.md # Relative to current directory, not plugin\n ```\n\n2. **Validate file existence:**\n ```markdown\n ---\n description: Use plugin config if exists\n allowed-tools: Bash(test:*), Read\n ---\n\n !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"exists\" || echo \"missing\"`\n\n If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json\n Otherwise, use defaults...\n ```\n\n3. **Document plugin file structure:**\n ```markdown\n \n ```\n\n4. **Combine with arguments:**\n ```markdown\n Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2`\n ```\n\n### Troubleshooting\n\n**Variable not expanding:**\n- Ensure command is loaded from plugin\n- Check bash execution is allowed\n- Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}`\n\n**File not found errors:**\n- Verify file exists in plugin directory\n- Check file path is correct relative to plugin root\n- Ensure file permissions allow reading/execution\n\n**Path with spaces:**\n- Bash commands automatically handle spaces\n- File references work with spaces in paths\n- No special quoting needed\n\n## Plugin Command Patterns\n\n### Pattern 1: Configuration-Based Commands\n\nCommands that load plugin-specific configuration:\n\n```markdown\n---\ndescription: Deploy using plugin settings\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json\n\nDeploy to $1 environment using:\n1. Configuration settings above\n2. Current git branch: !`git branch --show-current`\n3. Application version: !`cat package.json | grep version`\n\nExecute deployment and monitor progress.\n```\n\n**When to use:** Commands that need consistent settings across invocations\n\n### Pattern 2: Template-Based Generation\n\nCommands that use plugin templates:\n\n```markdown\n---\ndescription: Generate documentation from template\nargument-hint: [component-name]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md\n\nGenerate documentation for $1 component following the template structure.\nInclude:\n- Component purpose and usage\n- API reference\n- Examples\n- Testing guidelines\n```\n\n**When to use:** Standardized output generation\n\n### Pattern 3: Multi-Script Workflow\n\nCommands that orchestrate multiple plugin scripts:\n\n```markdown\n---\ndescription: Complete build and test workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nValidate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\n\nReview all outputs and report:\n1. Build status\n2. Validation results\n3. Test results\n4. Recommended next steps\n```\n\n**When to use:** Complex plugin workflows with multiple steps\n\n### Pattern 4: Environment-Aware Commands\n\nCommands that adapt to environment:\n\n```markdown\n---\ndescription: Deploy based on environment\nargument-hint: [dev|staging|prod]\n---\n\nEnvironment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\nEnvironment check: !`echo \"Deploying to: $1\"`\n\nDeploy application using $1 environment configuration.\nVerify deployment and run smoke tests.\n```\n\n**When to use:** Commands that behave differently per environment\n\n### Pattern 5: Plugin Data Management\n\nCommands that manage plugin-specific data:\n\n```markdown\n---\ndescription: Save analysis results to plugin cache\nallowed-tools: Bash(*), Read, Write\n---\n\nCache directory: ${CLAUDE_PLUGIN_ROOT}/cache/\n\nAnalyze @$1 and save results to cache:\n!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`\n\nStore analysis for future reference and comparison.\n```\n\n**When to use:** Commands that need persistent data storage\n\n## Integration with Plugin Components\n\n### Invoking Plugin Agents\n\nCommands can trigger plugin agents using the Task tool:\n\n```markdown\n---\ndescription: Deep analysis using plugin agent\nargument-hint: [file-path]\n---\n\nInitiate deep code analysis of @$1 using the code-analyzer agent.\n\nThe agent will:\n1. Analyze code structure\n2. Identify patterns\n3. Suggest improvements\n4. Generate detailed report\n\nNote: This uses the Task tool to launch the plugin's code-analyzer agent.\n```\n\n**Key points:**\n- Agent must be defined in plugin's `agents/` directory\n- Claude will automatically use Task tool to launch agent\n- Agent has access to same plugin resources\n\n### Invoking Plugin Skills\n\nCommands can reference plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: API documentation with best practices\nargument-hint: [api-file]\n---\n\nDocument the API in @$1 following our API documentation standards.\n\nUse the api-docs-standards skill to ensure documentation includes:\n- Endpoint descriptions\n- Parameter specifications\n- Response formats\n- Error codes\n- Usage examples\n\nNote: This leverages the plugin's api-docs-standards skill for consistency.\n```\n\n**Key points:**\n- Skill must be defined in plugin's `skills/` directory\n- Mention skill by name to hint Claude should invoke it\n- Skills provide specialized domain knowledge\n\n### Coordinating with Plugin Hooks\n\nCommands can be designed to work with plugin hooks:\n\n```markdown\n---\ndescription: Commit with pre-commit validation\nallowed-tools: Bash(git:*)\n---\n\nStage changes: !\\`git add $1\\`\n\nCommit changes: !\\`git commit -m \"$2\"\\`\n\nNote: This commit will trigger the plugin's pre-commit hook for validation.\nReview hook output for any issues.\n```\n\n**Key points:**\n- Hooks execute automatically on events\n- Commands can prepare state for hooks\n- Document hook interaction in command\n\n### Multi-Component Plugin Commands\n\nCommands that coordinate multiple plugin components:\n\n```markdown\n---\ndescription: Comprehensive code review workflow\nargument-hint: [file-path]\n---\n\nFile to review: @$1\n\nExecute comprehensive review:\n\n1. **Static Analysis** (via plugin scripts)\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\n2. **Deep Review** (via plugin agent)\n Launch the code-reviewer agent for detailed analysis.\n\n3. **Best Practices** (via plugin skill)\n Use the code-standards skill to ensure compliance.\n\n4. **Documentation** (via plugin template)\n Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nGenerate final report combining all outputs.\n```\n\n**When to use:** Complex workflows leveraging multiple plugin capabilities\n\n## Validation Patterns\n\n### Input Validation\n\nCommands should validate inputs before processing:\n\n```markdown\n---\ndescription: Deploy to environment with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\n$IF($1 in [dev, staging, prod],\n Deploy to $1 environment using validated configuration,\n ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod\n)\n```\n\n**Validation approaches:**\n1. Bash validation using grep/test\n2. Inline validation in prompt\n3. Script-based validation\n\n### File Existence Checks\n\nVerify required files exist:\n\n```markdown\n---\ndescription: Process configuration file\nargument-hint: [config-file]\n---\n\nCheck file: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nProcess configuration if file exists: @$1\n\nIf file doesn't exist, explain:\n- Expected location\n- Required format\n- How to create it\n```\n\n### Required Arguments\n\nValidate required arguments provided:\n\n```markdown\n---\ndescription: Create deployment with version\nargument-hint: [environment] [version]\n---\n\nValidate inputs: !`test -n \"$1\" -a -n \"$2\" && echo \"OK\" || echo \"MISSING\"`\n\n$IF($1 AND $2,\n Deploy version $2 to $1 environment,\n ERROR: Both environment and version required. Usage: /deploy [env] [version]\n)\n```\n\n### Plugin Resource Validation\n\nVerify plugin resources available:\n\n```markdown\n---\ndescription: Run analysis with plugin tools\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n- Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo \"✓\" || echo \"✗\"`\n- Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, proceed with analysis.\nOtherwise, report missing components and installation steps.\n```\n\n### Output Validation\n\nValidate command execution results:\n\n```markdown\n---\ndescription: Build and validate output\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\n\nValidate output:\n- Exit code: !`echo $?`\n- Output exists: !`test -d dist && echo \"✓\" || echo \"✗\"`\n- File count: !`find dist -type f | wc -l`\n\nReport build status and any validation failures.\n```\n\n### Graceful Error Handling\n\nHandle errors gracefully with helpful messages:\n\n```markdown\n---\ndescription: Process file with error handling\nargument-hint: [file-path]\n---\n\nTry processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo \"ERROR: $?\"`\n\nIf processing succeeded:\n- Report results\n- Suggest next steps\n\nIf processing failed:\n- Explain likely causes\n- Provide troubleshooting steps\n- Suggest alternative approaches\n```\n\n## Best Practices Summary\n\n### Plugin Commands Should:\n\n1. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths**\n - Scripts, templates, configuration, resources\n\n2. **Validate inputs early**\n - Check required arguments\n - Verify file existence\n - Validate argument formats\n\n3. **Document plugin structure**\n - Explain required files\n - Document script purposes\n - Clarify dependencies\n\n4. **Integrate with plugin components**\n - Reference agents for complex tasks\n - Use skills for specialized knowledge\n - Coordinate with hooks when relevant\n\n5. **Provide helpful error messages**\n - Explain what went wrong\n - Suggest how to fix\n - Offer alternatives\n\n6. **Handle edge cases**\n - Missing files\n - Invalid arguments\n - Failed script execution\n - Missing dependencies\n\n7. **Keep commands focused**\n - One clear purpose per command\n - Delegate complex logic to scripts\n - Use agents for multi-step workflows\n\n8. **Test across installations**\n - Verify paths work everywhere\n - Test with different arguments\n - Validate error cases\n\n---\n\nFor general command development, see main SKILL.md.\nFor command examples, see examples/ directory.\n","plugins/plugin-dev/skills/command-development/references/testing-strategies.md":"# Command Testing Strategies\n\nComprehensive strategies for testing slash commands before deployment and distribution.\n\n## Overview\n\nTesting commands ensures they work correctly, handle edge cases, and provide good user experience. A systematic testing approach catches issues early and builds confidence in command reliability.\n\n## Testing Levels\n\n### Level 1: Syntax and Structure Validation\n\n**What to test:**\n- YAML frontmatter syntax\n- Markdown format\n- File location and naming\n\n**How to test:**\n\n```bash\n# Validate YAML frontmatter\nhead -n 20 .claude/commands/my-command.md | grep -A 10 \"^---\"\n\n# Check for closing frontmatter marker\nhead -n 20 .claude/commands/my-command.md | grep -c \"^---\" # Should be 2\n\n# Verify file has .md extension\nls .claude/commands/*.md\n\n# Check file is in correct location\ntest -f .claude/commands/my-command.md && echo \"Found\" || echo \"Missing\"\n```\n\n**Automated validation script:**\n\n```bash\n#!/bin/bash\n# validate-command.sh\n\nCOMMAND_FILE=\"$1\"\n\nif [ ! -f \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File not found: $COMMAND_FILE\"\n exit 1\nfi\n\n# Check .md extension\nif [[ ! \"$COMMAND_FILE\" =~ \\.md$ ]]; then\n echo \"ERROR: File must have .md extension\"\n exit 1\nfi\n\n# Validate YAML frontmatter if present\nif head -n 1 \"$COMMAND_FILE\" | grep -q \"^---\"; then\n # Count frontmatter markers\n MARKERS=$(head -n 50 \"$COMMAND_FILE\" | grep -c \"^---\")\n if [ \"$MARKERS\" -ne 2 ]; then\n echo \"ERROR: Invalid YAML frontmatter (need exactly 2 '---' markers)\"\n exit 1\n fi\n echo \"✓ YAML frontmatter syntax valid\"\nfi\n\n# Check for empty file\nif [ ! -s \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File is empty\"\n exit 1\nfi\n\necho \"✓ Command file structure valid\"\n```\n\n### Level 2: Frontmatter Field Validation\n\n**What to test:**\n- Field types correct\n- Values in valid ranges\n- Required fields present (if any)\n\n**Validation script:**\n\n```bash\n#!/bin/bash\n# validate-frontmatter.sh\n\nCOMMAND_FILE=\"$1\"\n\n# Extract YAML frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/p' \"$COMMAND_FILE\" | sed '1d;$d')\n\nif [ -z \"$FRONTMATTER\" ]; then\n echo \"No frontmatter to validate\"\n exit 0\nfi\n\n# Check 'model' field if present\nif echo \"$FRONTMATTER\" | grep -q \"^model:\"; then\n MODEL=$(echo \"$FRONTMATTER\" | grep \"^model:\" | cut -d: -f2 | tr -d ' ')\n if ! echo \"sonnet opus haiku\" | grep -qw \"$MODEL\"; then\n echo \"ERROR: Invalid model '$MODEL' (must be sonnet, opus, or haiku)\"\n exit 1\n fi\n echo \"✓ Model field valid: $MODEL\"\nfi\n\n# Check 'allowed-tools' field format\nif echo \"$FRONTMATTER\" | grep -q \"^allowed-tools:\"; then\n echo \"✓ allowed-tools field present\"\n # Could add more sophisticated validation here\nfi\n\n# Check 'description' length\nif echo \"$FRONTMATTER\" | grep -q \"^description:\"; then\n DESC=$(echo \"$FRONTMATTER\" | grep \"^description:\" | cut -d: -f2-)\n LENGTH=${#DESC}\n if [ \"$LENGTH\" -gt 80 ]; then\n echo \"WARNING: Description length $LENGTH (recommend < 60 chars)\"\n else\n echo \"✓ Description length acceptable: $LENGTH chars\"\n fi\nfi\n\necho \"✓ Frontmatter fields valid\"\n```\n\n### Level 3: Manual Command Invocation\n\n**What to test:**\n- Command appears in `/help`\n- Command executes without errors\n- Output is as expected\n\n**Test procedure:**\n\n```bash\n# 1. Start Claude Code\nclaude --debug\n\n# 2. Check command appears in help\n> /help\n# Look for your command in the list\n\n# 3. Invoke command without arguments\n> /my-command\n# Check for reasonable error or behavior\n\n# 4. Invoke with valid arguments\n> /my-command arg1 arg2\n# Verify expected behavior\n\n# 5. Check debug logs\ntail -f ~/.claude/debug-logs/latest\n# Look for errors or warnings\n```\n\n### Level 4: Argument Testing\n\n**What to test:**\n- Positional arguments work ($1, $2, etc.)\n- $ARGUMENTS captures all arguments\n- Missing arguments handled gracefully\n- Invalid arguments detected\n\n**Test matrix:**\n\n| Test Case | Command | Expected Result |\n|-----------|---------|-----------------|\n| No args | `/cmd` | Graceful handling or useful message |\n| One arg | `/cmd arg1` | $1 substituted correctly |\n| Two args | `/cmd arg1 arg2` | $1 and $2 substituted |\n| Extra args | `/cmd a b c d` | All captured or extras ignored appropriately |\n| Special chars | `/cmd \"arg with spaces\"` | Quotes handled correctly |\n| Empty arg | `/cmd \"\"` | Empty string handled |\n\n**Test script:**\n\n```bash\n#!/bin/bash\n# test-command-arguments.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing argument handling for /$COMMAND\"\necho\n\necho \"Test 1: No arguments\"\necho \" Command: /$COMMAND\"\necho \" Expected: [describe expected behavior]\"\necho \" Manual test required\"\necho\n\necho \"Test 2: Single argument\"\necho \" Command: /$COMMAND test-value\"\necho \" Expected: 'test-value' appears in output\"\necho \" Manual test required\"\necho\n\necho \"Test 3: Multiple arguments\"\necho \" Command: /$COMMAND arg1 arg2 arg3\"\necho \" Expected: All arguments used appropriately\"\necho \" Manual test required\"\necho\n\necho \"Test 4: Special characters\"\necho \" Command: /$COMMAND \\\"value with spaces\\\"\"\necho \" Expected: Entire phrase captured\"\necho \" Manual test required\"\n```\n\n### Level 5: File Reference Testing\n\n**What to test:**\n- @ syntax loads file contents\n- Non-existent files handled\n- Large files handled appropriately\n- Multiple file references work\n\n**Test procedure:**\n\n```bash\n# Create test files\necho \"Test content\" > /tmp/test-file.txt\necho \"Second file\" > /tmp/test-file-2.txt\n\n# Test single file reference\n> /my-command /tmp/test-file.txt\n# Verify file content is read\n\n# Test non-existent file\n> /my-command /tmp/nonexistent.txt\n# Verify graceful error handling\n\n# Test multiple files\n> /my-command /tmp/test-file.txt /tmp/test-file-2.txt\n# Verify both files processed\n\n# Test large file\ndd if=/dev/zero of=/tmp/large-file.bin bs=1M count=100\n> /my-command /tmp/large-file.bin\n# Verify reasonable behavior (may truncate or warn)\n\n# Cleanup\nrm /tmp/test-file*.txt /tmp/large-file.bin\n```\n\n### Level 6: Bash Execution Testing\n\n**What to test:**\n- !` commands execute correctly\n- Command output included in prompt\n- Command failures handled\n- Security: only allowed commands run\n\n**Test procedure:**\n\n```bash\n# Create test command with bash execution\ncat > .claude/commands/test-bash.md << 'EOF'\n---\ndescription: Test bash execution\nallowed-tools: Bash(echo:*), Bash(date:*)\n---\n\nCurrent date: !`date`\nTest output: !`echo \"Hello from bash\"`\n\nAnalysis of output above...\nEOF\n\n# Test in Claude Code\n> /test-bash\n# Verify:\n# 1. Date appears correctly\n# 2. Echo output appears\n# 3. No errors in debug logs\n\n# Test with disallowed command (should fail or be blocked)\ncat > .claude/commands/test-forbidden.md << 'EOF'\n---\ndescription: Test forbidden command\nallowed-tools: Bash(echo:*)\n---\n\nTrying forbidden: !`ls -la /`\nEOF\n\n> /test-forbidden\n# Verify: Permission denied or appropriate error\n```\n\n### Level 7: Integration Testing\n\n**What to test:**\n- Commands work with other plugin components\n- Commands interact correctly with each other\n- State management works across invocations\n- Workflow commands execute in sequence\n\n**Test scenarios:**\n\n**Scenario 1: Command + Hook Integration**\n\n```bash\n# Setup: Command that triggers a hook\n# Test: Invoke command, verify hook executes\n\n# Command: .claude/commands/risky-operation.md\n# Hook: PreToolUse that validates the operation\n\n> /risky-operation\n# Verify: Hook executes and validates before command completes\n```\n\n**Scenario 2: Command Sequence**\n\n```bash\n# Setup: Multi-command workflow\n> /workflow-init\n# Verify: State file created\n\n> /workflow-step2\n# Verify: State file read, step 2 executes\n\n> /workflow-complete\n# Verify: State file cleaned up\n```\n\n**Scenario 3: Command + MCP Integration**\n\n```bash\n# Setup: Command uses MCP tools\n# Test: Verify MCP server accessible\n\n> /mcp-command\n# Verify:\n# 1. MCP server starts (if stdio)\n# 2. Tool calls succeed\n# 3. Results included in output\n```\n\n## Automated Testing Approaches\n\n### Command Test Suite\n\nCreate a test suite script:\n\n```bash\n#!/bin/bash\n# test-commands.sh - Command test suite\n\nTEST_DIR=\".claude/commands\"\nFAILED_TESTS=0\n\necho \"Command Test Suite\"\necho \"==================\"\necho\n\nfor cmd_file in \"$TEST_DIR\"/*.md; do\n cmd_name=$(basename \"$cmd_file\" .md)\n echo \"Testing: $cmd_name\"\n\n # Validate structure\n if ./validate-command.sh \"$cmd_file\"; then\n echo \" ✓ Structure valid\"\n else\n echo \" ✗ Structure invalid\"\n ((FAILED_TESTS++))\n fi\n\n # Validate frontmatter\n if ./validate-frontmatter.sh \"$cmd_file\"; then\n echo \" ✓ Frontmatter valid\"\n else\n echo \" ✗ Frontmatter invalid\"\n ((FAILED_TESTS++))\n fi\n\n echo\ndone\n\necho \"==================\"\necho \"Tests complete\"\necho \"Failed: $FAILED_TESTS\"\n\nexit $FAILED_TESTS\n```\n\n### Pre-Commit Hook\n\nValidate commands before committing:\n\n```bash\n#!/bin/bash\n# .git/hooks/pre-commit\n\necho \"Validating commands...\"\n\nCOMMANDS_CHANGED=$(git diff --cached --name-only | grep \"\\.claude/commands/.*\\.md\")\n\nif [ -z \"$COMMANDS_CHANGED\" ]; then\n echo \"No commands changed\"\n exit 0\nfi\n\nfor cmd in $COMMANDS_CHANGED; do\n echo \"Checking: $cmd\"\n\n if ! ./scripts/validate-command.sh \"$cmd\"; then\n echo \"ERROR: Command validation failed: $cmd\"\n exit 1\n fi\ndone\n\necho \"✓ All commands valid\"\n```\n\n### Continuous Testing\n\nTest commands in CI/CD:\n\n```yaml\n# .github/workflows/test-commands.yml\nname: Test Commands\n\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n\n - name: Validate command structure\n run: |\n for cmd in .claude/commands/*.md; do\n echo \"Testing: $cmd\"\n ./scripts/validate-command.sh \"$cmd\"\n done\n\n - name: Validate frontmatter\n run: |\n for cmd in .claude/commands/*.md; do\n ./scripts/validate-frontmatter.sh \"$cmd\"\n done\n\n - name: Check for TODOs\n run: |\n if grep -r \"TODO\" .claude/commands/; then\n echo \"ERROR: TODOs found in commands\"\n exit 1\n fi\n```\n\n## Edge Case Testing\n\n### Test Edge Cases\n\n**Empty arguments:**\n```bash\n> /cmd \"\"\n> /cmd '' ''\n```\n\n**Special characters:**\n```bash\n> /cmd \"arg with spaces\"\n> /cmd arg-with-dashes\n> /cmd arg_with_underscores\n> /cmd arg/with/slashes\n> /cmd 'arg with \"quotes\"'\n```\n\n**Long arguments:**\n```bash\n> /cmd $(python -c \"print('a' * 10000)\")\n```\n\n**Unusual file paths:**\n```bash\n> /cmd ./file\n> /cmd ../file\n> /cmd ~/file\n> /cmd \"/path with spaces/file\"\n```\n\n**Bash command edge cases:**\n```markdown\n# Commands that might fail\n!`exit 1`\n!`false`\n!`command-that-does-not-exist`\n\n# Commands with special output\n!`echo \"\"`\n!`cat /dev/null`\n!`yes | head -n 1000000`\n```\n\n## Performance Testing\n\n### Response Time Testing\n\n```bash\n#!/bin/bash\n# test-command-performance.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing performance of /$COMMAND\"\necho\n\nfor i in {1..5}; do\n echo \"Run $i:\"\n START=$(date +%s%N)\n\n # Invoke command (manual step - record time)\n echo \" Invoke: /$COMMAND\"\n echo \" Start time: $START\"\n echo \" (Record end time manually)\"\n echo\ndone\n\necho \"Analyze results:\"\necho \" - Average response time\"\necho \" - Variance\"\necho \" - Acceptable threshold: < 3 seconds for fast commands\"\n```\n\n### Resource Usage Testing\n\n```bash\n# Monitor Claude Code during command execution\n# In terminal 1:\nclaude --debug\n\n# In terminal 2:\nwatch -n 1 'ps aux | grep claude'\n\n# Execute command and observe:\n# - Memory usage\n# - CPU usage\n# - Process count\n```\n\n## User Experience Testing\n\n### Usability Checklist\n\n- [ ] Command name is intuitive\n- [ ] Description is clear in `/help`\n- [ ] Arguments are well-documented\n- [ ] Error messages are helpful\n- [ ] Output is formatted readably\n- [ ] Long-running commands show progress\n- [ ] Results are actionable\n- [ ] Edge cases have good UX\n\n### User Acceptance Testing\n\nRecruit testers:\n\n```markdown\n# Testing Guide for Beta Testers\n\n## Command: /my-new-command\n\n### Test Scenarios\n\n1. **Basic usage:**\n - Run: `/my-new-command`\n - Expected: [describe]\n - Rate clarity: 1-5\n\n2. **With arguments:**\n - Run: `/my-new-command arg1 arg2`\n - Expected: [describe]\n - Rate usefulness: 1-5\n\n3. **Error case:**\n - Run: `/my-new-command invalid-input`\n - Expected: Helpful error message\n - Rate error message: 1-5\n\n### Feedback Questions\n\n1. Was the command easy to understand?\n2. Did the output meet your expectations?\n3. What would you change?\n4. Would you use this command regularly?\n```\n\n## Testing Checklist\n\nBefore releasing a command:\n\n### Structure\n- [ ] File in correct location\n- [ ] Correct .md extension\n- [ ] Valid YAML frontmatter (if present)\n- [ ] Markdown syntax correct\n\n### Functionality\n- [ ] Command appears in `/help`\n- [ ] Description is clear\n- [ ] Command executes without errors\n- [ ] Arguments work as expected\n- [ ] File references work\n- [ ] Bash execution works (if used)\n\n### Edge Cases\n- [ ] Missing arguments handled\n- [ ] Invalid arguments detected\n- [ ] Non-existent files handled\n- [ ] Special characters work\n- [ ] Long inputs handled\n\n### Integration\n- [ ] Works with other commands\n- [ ] Works with hooks (if applicable)\n- [ ] Works with MCP (if applicable)\n- [ ] State management works\n\n### Quality\n- [ ] Performance acceptable\n- [ ] No security issues\n- [ ] Error messages helpful\n- [ ] Output formatted well\n- [ ] Documentation complete\n\n### Distribution\n- [ ] Tested by others\n- [ ] Feedback incorporated\n- [ ] README updated\n- [ ] Examples provided\n\n## Debugging Failed Tests\n\n### Common Issues and Solutions\n\n**Issue: Command not appearing in /help**\n\n```bash\n# Check file location\nls -la .claude/commands/my-command.md\n\n# Check permissions\nchmod 644 .claude/commands/my-command.md\n\n# Check syntax\nhead -n 20 .claude/commands/my-command.md\n\n# Restart Claude Code\nclaude --debug\n```\n\n**Issue: Arguments not substituting**\n\n```bash\n# Verify syntax\ngrep '\\$1' .claude/commands/my-command.md\ngrep '\\$ARGUMENTS' .claude/commands/my-command.md\n\n# Test with simple command first\necho \"Test: \\$1 and \\$2\" > .claude/commands/test-args.md\n```\n\n**Issue: Bash commands not executing**\n\n```bash\n# Check allowed-tools\ngrep \"allowed-tools\" .claude/commands/my-command.md\n\n# Verify command syntax\ngrep '!\\`' .claude/commands/my-command.md\n\n# Test command manually\ndate\necho \"test\"\n```\n\n**Issue: File references not working**\n\n```bash\n# Check @ syntax\ngrep '@' .claude/commands/my-command.md\n\n# Verify file exists\nls -la /path/to/referenced/file\n\n# Check permissions\nchmod 644 /path/to/referenced/file\n```\n\n## Best Practices\n\n1. **Test early, test often**: Validate as you develop\n2. **Automate validation**: Use scripts for repeatable checks\n3. **Test edge cases**: Don't just test the happy path\n4. **Get feedback**: Have others test before wide release\n5. **Document tests**: Keep test scenarios for regression testing\n6. **Monitor in production**: Watch for issues after release\n7. **Iterate**: Improve based on real usage data\n","plugins/plugin-dev/skills/hook-development/SKILL.md":"---\nname: Hook Development\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse/PostToolUse/Stop hook\", \"validate tool use\", \"implement prompt-based hooks\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"set up event-driven automation\", \"block dangerous commands\", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.\nversion: 0.1.0\n---\n\n# Hook Development for Claude Code Plugins\n\n## Overview\n\nHooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.\n\n**Key capabilities:**\n- Validate tool calls before execution (PreToolUse)\n- React to tool results (PostToolUse)\n- Enforce completion standards (Stop, SubagentStop)\n- Load project context (SessionStart)\n- Automate workflows across the development lifecycle\n\n## Hook Types\n\n### Prompt-Based Hooks (Recommended)\n\nUse LLM-driven decision making for context-aware validation:\n\n```json\n{\n \"type\": \"prompt\",\n \"prompt\": \"Evaluate if this tool use is appropriate: $TOOL_INPUT\",\n \"timeout\": 30\n}\n```\n\n**Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse\n\n**Benefits:**\n- Context-aware decisions based on natural language reasoning\n- Flexible evaluation logic without bash scripting\n- Better edge case handling\n- Easier to maintain and extend\n\n### Command Hooks\n\nExecute bash commands for deterministic checks:\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 60\n}\n```\n\n**Use for:**\n- Fast deterministic validations\n- File system operations\n- External tool integrations\n- Performance-critical checks\n\n## Hook Configuration Formats\n\n### Plugin hooks.json Format\n\n**For plugin hooks** in `hooks/hooks.json`, use wrapper format:\n\n```json\n{\n \"description\": \"Brief explanation of hooks (optional)\",\n \"hooks\": {\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n }\n}\n```\n\n**Key points:**\n- `description` field is optional\n- `hooks` field is required wrapper containing actual hook events\n- This is the **plugin-specific format**\n\n**Example:**\n```json\n{\n \"description\": \"Validation hooks for code quality\",\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh\"\n }\n ]\n }\n ]\n }\n}\n```\n\n### Settings Format (Direct)\n\n**For user settings** in `.claude/settings.json`, use direct format:\n\n```json\n{\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**Key points:**\n- No wrapper - events directly at top level\n- No description field\n- This is the **settings format**\n\n**Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{\"hooks\": {...}}`.\n\n## Hook Events\n\n### PreToolUse\n\nExecute before any tool runs. Use to approve, deny, or modify tool calls.\n\n**Example (prompt-based):**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output for PreToolUse:**\n```json\n{\n \"hookSpecificOutput\": {\n \"permissionDecision\": \"allow|deny|ask\",\n \"updatedInput\": {\"field\": \"modified_value\"}\n },\n \"systemMessage\": \"Explanation for Claude\"\n}\n```\n\n### PostToolUse\n\nExecute after tool completes. Use to react to results, provide feedback, or log.\n\n**Example:**\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output behavior:**\n- Exit 0: stdout shown in transcript\n- Exit 2: stderr fed back to Claude\n- systemMessage included in context\n\n### Stop\n\nExecute when main agent considers stopping. Use to validate completeness.\n\n**Example:**\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue.\"\n }\n ]\n }\n ]\n}\n```\n\n**Decision output:**\n```json\n{\n \"decision\": \"approve|block\",\n \"reason\": \"Explanation\",\n \"systemMessage\": \"Additional context\"\n}\n```\n\n### SubagentStop\n\nExecute when subagent considers stopping. Use to ensure subagent completed its task.\n\nSimilar to Stop hook, but for subagents.\n\n### UserPromptSubmit\n\nExecute when user submits a prompt. Use to add context, validate, or block prompts.\n\n**Example:**\n```json\n{\n \"UserPromptSubmit\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings.\"\n }\n ]\n }\n ]\n}\n```\n\n### SessionStart\n\nExecute when Claude Code session begins. Use to load context and set environment.\n\n**Example:**\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`:\n```bash\necho \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\n```\n\nSee `examples/load-context.sh` for complete example.\n\n### SessionEnd\n\nExecute when session ends. Use for cleanup, logging, and state preservation.\n\n### PreCompact\n\nExecute before context compaction. Use to add critical information to preserve.\n\n### Notification\n\nExecute when Claude sends notifications. Use to react to user notifications.\n\n## Hook Output Format\n\n### Standard Output (All Hooks)\n\n```json\n{\n \"continue\": true,\n \"suppressOutput\": false,\n \"systemMessage\": \"Message for Claude\"\n}\n```\n\n- `continue`: If false, halt processing (default true)\n- `suppressOutput`: Hide output from transcript (default false)\n- `systemMessage`: Message shown to Claude\n\n### Exit Codes\n\n- `0` - Success (stdout shown in transcript)\n- `2` - Blocking error (stderr fed back to Claude)\n- Other - Non-blocking error\n\n## Hook Input Format\n\nAll hooks receive JSON via stdin with common fields:\n\n```json\n{\n \"session_id\": \"abc123\",\n \"transcript_path\": \"/path/to/transcript.txt\",\n \"cwd\": \"/current/working/dir\",\n \"permission_mode\": \"ask|allow\",\n \"hook_event_name\": \"PreToolUse\"\n}\n```\n\n**Event-specific fields:**\n\n- **PreToolUse/PostToolUse:** `tool_name`, `tool_input`, `tool_result`\n- **UserPromptSubmit:** `user_prompt`\n- **Stop/SubagentStop:** `reason`\n\nAccess fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc.\n\n## Environment Variables\n\nAvailable in all command hooks:\n\n- `$CLAUDE_PROJECT_DIR` - Project root path\n- `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths)\n- `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here\n- `$CLAUDE_CODE_REMOTE` - Set if running in remote context\n\n**Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:**\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\"\n}\n```\n\n## Plugin Hook Configuration\n\nIn plugins, define hooks in `hooks/hooks.json`:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\",\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nPlugin hooks merge with user's hooks and run in parallel.\n\n## Matchers\n\n### Tool Name Matching\n\n**Exact match:**\n```json\n\"matcher\": \"Write\"\n```\n\n**Multiple tools:**\n```json\n\"matcher\": \"Read|Write|Edit\"\n```\n\n**Wildcard (all tools):**\n```json\n\"matcher\": \"*\"\n```\n\n**Regex patterns:**\n```json\n\"matcher\": \"mcp__.*__delete.*\" // All MCP delete tools\n```\n\n**Note:** Matchers are case-sensitive.\n\n### Common Patterns\n\n```json\n// All MCP tools\n\"matcher\": \"mcp__.*\"\n\n// Specific plugin's MCP tools\n\"matcher\": \"mcp__plugin_asana_.*\"\n\n// All file operations\n\"matcher\": \"Read|Write|Edit\"\n\n// Bash commands only\n\"matcher\": \"Bash\"\n```\n\n## Security Best Practices\n\n### Input Validation\n\nAlways validate inputs in command hooks:\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Validate tool name format\nif [[ ! \"$tool_name\" =~ ^[a-zA-Z0-9_]+$ ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Invalid tool name\"}' >&2\n exit 2\nfi\n```\n\n### Path Safety\n\nCheck for path traversal and sensitive files:\n\n```bash\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Deny path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Deny sensitive files\nif [[ \"$file_path\" == *\".env\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Sensitive file\"}' >&2\n exit 2\nfi\n```\n\nSee `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples.\n\n### Quote All Variables\n\n```bash\n# GOOD: Quoted\necho \"$file_path\"\ncd \"$CLAUDE_PROJECT_DIR\"\n\n# BAD: Unquoted (injection risk)\necho $file_path\ncd $CLAUDE_PROJECT_DIR\n```\n\n### Set Appropriate Timeouts\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash script.sh\",\n \"timeout\": 10\n}\n```\n\n**Defaults:** Command hooks (60s), Prompt hooks (30s)\n\n## Performance Considerations\n\n### Parallel Execution\n\nAll matching hooks run **in parallel**:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\"type\": \"command\", \"command\": \"check1.sh\"}, // Parallel\n {\"type\": \"command\", \"command\": \"check2.sh\"}, // Parallel\n {\"type\": \"prompt\", \"prompt\": \"Validate...\"} // Parallel\n ]\n }\n ]\n}\n```\n\n**Design implications:**\n- Hooks don't see each other's output\n- Non-deterministic ordering\n- Design for independence\n\n### Optimization\n\n1. Use command hooks for quick deterministic checks\n2. Use prompt hooks for complex reasoning\n3. Cache validation results in temp files\n4. Minimize I/O in hot paths\n\n## Temporarily Active Hooks\n\nCreate hooks that activate conditionally by checking for a flag file or configuration:\n\n**Pattern: Flag file activation**\n```bash\n#!/bin/bash\n# Only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-strict-validation\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Flag not present, skip validation\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\n# ... validation logic ...\n```\n\n**Pattern: Configuration-based activation**\n```bash\n#!/bin/bash\n# Check configuration for activation\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/plugin-config.json\"\n\nif [ -f \"$CONFIG_FILE\" ]; then\n enabled=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n if [ \"$enabled\" != \"true\" ]; then\n exit 0 # Not enabled, skip\n fi\nfi\n\n# Enabled, run hook logic\ninput=$(cat)\n# ... hook logic ...\n```\n\n**Use cases:**\n- Enable strict validation only when needed\n- Temporary debugging hooks\n- Project-specific hook behavior\n- Feature flags for hooks\n\n**Best practice:** Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.\n\n## Hook Lifecycle and Limitations\n\n### Hooks Load at Session Start\n\n**Important:** Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.\n\n**Cannot hot-swap hooks:**\n- Editing `hooks/hooks.json` won't affect current session\n- Adding new hook scripts won't be recognized\n- Changing hook commands/prompts won't update\n- Must restart Claude Code: exit and run `claude` again\n\n**To test hook changes:**\n1. Edit hook configuration or scripts\n2. Exit Claude Code session\n3. Restart: `claude` or `cc`\n4. New hook configuration loads\n5. Test hooks with `claude --debug`\n\n### Hook Validation at Startup\n\nHooks are validated when Claude Code starts:\n- Invalid JSON in hooks.json causes loading failure\n- Missing scripts cause warnings\n- Syntax errors reported in debug mode\n\nUse `/hooks` command to review loaded hooks in current session.\n\n## Debugging Hooks\n\n### Enable Debug Mode\n\n```bash\nclaude --debug\n```\n\nLook for hook registration, execution logs, input/output JSON, and timing information.\n\n### Test Hook Scripts\n\nTest command hooks directly:\n\n```bash\necho '{\"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"/test\"}}' | \\\n bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\n\necho \"Exit code: $?\"\n```\n\n### Validate JSON Output\n\nEnsure hooks output valid JSON:\n\n```bash\noutput=$(./your-hook.sh < test-input.json)\necho \"$output\" | jq .\n```\n\n## Quick Reference\n\n### Hook Events Summary\n\n| Event | When | Use For |\n|-------|------|---------|\n| PreToolUse | Before tool | Validation, modification |\n| PostToolUse | After tool | Feedback, logging |\n| UserPromptSubmit | User input | Context, validation |\n| Stop | Agent stopping | Completeness check |\n| SubagentStop | Subagent done | Task validation |\n| SessionStart | Session begins | Context loading |\n| SessionEnd | Session ends | Cleanup, logging |\n| PreCompact | Before compact | Preserve context |\n| Notification | User notified | Logging, reactions |\n\n### Best Practices\n\n**DO:**\n- ✅ Use prompt-based hooks for complex logic\n- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability\n- ✅ Validate all inputs in command hooks\n- ✅ Quote all bash variables\n- ✅ Set appropriate timeouts\n- ✅ Return structured JSON output\n- ✅ Test hooks thoroughly\n\n**DON'T:**\n- ❌ Use hardcoded paths\n- ❌ Trust user input without validation\n- ❌ Create long-running hooks\n- ❌ Rely on hook execution order\n- ❌ Modify global state unpredictably\n- ❌ Log sensitive information\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed patterns and advanced techniques, consult:\n\n- **`references/patterns.md`** - Common hook patterns (8+ proven patterns)\n- **`references/migration.md`** - Migrating from basic to advanced hooks\n- **`references/advanced.md`** - Advanced use cases and techniques\n\n### Example Hook Scripts\n\nWorking examples in `examples/`:\n\n- **`validate-write.sh`** - File write validation example\n- **`validate-bash.sh`** - Bash command validation example\n- **`load-context.sh`** - SessionStart context loading example\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-hook-schema.sh`** - Validate hooks.json structure and syntax\n- **`test-hook.sh`** - Test hooks with sample input before deployment\n- **`hook-linter.sh`** - Check hook scripts for common issues and best practices\n\n### External Resources\n\n- **Official Docs**: https://docs.claude.com/en/docs/claude-code/hooks\n- **Examples**: See security-guidance plugin in marketplace\n- **Testing**: Use `claude --debug` for detailed logs\n- **Validation**: Use `jq` to validate hook JSON output\n\n## Implementation Workflow\n\nTo implement hooks in a plugin:\n\n1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.)\n2. Decide between prompt-based (flexible) or command (deterministic) hooks\n3. Write hook configuration in `hooks/hooks.json`\n4. For command hooks, create hook scripts\n5. Use ${CLAUDE_PLUGIN_ROOT} for all file references\n6. Validate configuration with `scripts/validate-hook-schema.sh hooks/hooks.json`\n7. Test hooks with `scripts/test-hook.sh` before deployment\n8. Test in Claude Code with `claude --debug`\n9. Document hooks in plugin README\n\nFocus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.\n","plugins/plugin-dev/skills/hook-development/references/advanced.md":"# Advanced Hook Use Cases\n\nThis reference covers advanced hook patterns and techniques for sophisticated automation workflows.\n\n## Multi-Stage Validation\n\nCombine command and prompt hooks for layered validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Use case:** Fast deterministic checks followed by intelligent analysis\n\n**Example quick-check.sh:**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Immediate approval for safe commands\nif [[ \"$command\" =~ ^(ls|pwd|echo|date|whoami)$ ]]; then\n exit 0\nfi\n\n# Let prompt hook handle complex cases\nexit 0\n```\n\nThe command hook quickly approves obviously safe commands, while the prompt hook analyzes everything else.\n\n## Conditional Hook Execution\n\nExecute hooks based on environment or context:\n\n```bash\n#!/bin/bash\n# Only run in CI environment\nif [ -z \"$CI\" ]; then\n echo '{\"continue\": true}' # Skip in non-CI\n exit 0\nfi\n\n# Run validation logic in CI\ninput=$(cat)\n# ... validation code ...\n```\n\n**Use cases:**\n- Different behavior in CI vs local development\n- Project-specific validation\n- User-specific rules\n\n**Example: Skip certain checks for trusted users:**\n```bash\n#!/bin/bash\n# Skip detailed checks for admin users\nif [ \"$USER\" = \"admin\" ]; then\n exit 0\nfi\n\n# Full validation for other users\ninput=$(cat)\n# ... validation code ...\n```\n\n## Hook Chaining via State\n\nShare state between hooks using temporary files:\n\n```bash\n# Hook 1: Analyze and save state\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Analyze command\nrisk_level=$(calculate_risk \"$command\")\necho \"$risk_level\" > /tmp/hook-state-$$\n\nexit 0\n```\n\n```bash\n# Hook 2: Use saved state\n#!/bin/bash\nrisk_level=$(cat /tmp/hook-state-$$ 2>/dev/null || echo \"unknown\")\n\nif [ \"$risk_level\" = \"high\" ]; then\n echo \"High risk operation detected\" >&2\n exit 2\nfi\n```\n\n**Important:** This only works for sequential hook events (e.g., PreToolUse then PostToolUse), not parallel hooks.\n\n## Dynamic Hook Configuration\n\nModify hook behavior based on project configuration:\n\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Read project-specific config\nif [ -f \".claude-hooks-config.json\" ]; then\n strict_mode=$(jq -r '.strict_mode' .claude-hooks-config.json)\n\n if [ \"$strict_mode\" = \"true\" ]; then\n # Apply strict validation\n # ...\n else\n # Apply lenient validation\n # ...\n fi\nfi\n```\n\n**Example .claude-hooks-config.json:**\n```json\n{\n \"strict_mode\": true,\n \"allowed_commands\": [\"ls\", \"pwd\", \"grep\"],\n \"forbidden_paths\": [\"/etc\", \"/sys\"]\n}\n```\n\n## Context-Aware Prompt Hooks\n\nUse transcript and session context for intelligent decisions:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review the full transcript at $TRANSCRIPT_PATH. Check: 1) Were tests run after code changes? 2) Did the build succeed? 3) Were all user questions answered? 4) Is there any unfinished work? Return 'approve' only if everything is complete.\"\n }\n ]\n }\n ]\n}\n```\n\nThe LLM can read the transcript file and make context-aware decisions.\n\n## Performance Optimization\n\n### Caching Validation Results\n\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncache_key=$(echo -n \"$file_path\" | md5sum | cut -d' ' -f1)\ncache_file=\"/tmp/hook-cache-$cache_key\"\n\n# Check cache\nif [ -f \"$cache_file\" ]; then\n cache_age=$(($(date +%s) - $(stat -f%m \"$cache_file\" 2>/dev/null || stat -c%Y \"$cache_file\")))\n if [ \"$cache_age\" -lt 300 ]; then # 5 minute cache\n cat \"$cache_file\"\n exit 0\n fi\nfi\n\n# Perform validation\nresult='{\"decision\": \"approve\"}'\n\n# Cache result\necho \"$result\" > \"$cache_file\"\necho \"$result\"\n```\n\n### Parallel Execution Optimization\n\nSince hooks run in parallel, design them to be independent:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash check-size.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"command\",\n \"command\": \"bash check-path.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check content safety\", // Independent\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nAll three hooks run simultaneously, reducing total latency.\n\n## Cross-Event Workflows\n\nCoordinate hooks across different events:\n\n**SessionStart - Set up tracking:**\n```bash\n#!/bin/bash\n# Initialize session tracking\necho \"0\" > /tmp/test-count-$$\necho \"0\" > /tmp/build-count-$$\n```\n\n**PostToolUse - Track events:**\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\nif [ \"$tool_name\" = \"Bash\" ]; then\n command=$(echo \"$input\" | jq -r '.tool_result')\n if [[ \"$command\" == *\"test\"* ]]; then\n count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n echo $((count + 1)) > /tmp/test-count-$$\n fi\nfi\n```\n\n**Stop - Verify based on tracking:**\n```bash\n#!/bin/bash\ntest_count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n\nif [ \"$test_count\" -eq 0 ]; then\n echo '{\"decision\": \"block\", \"reason\": \"No tests were run\"}' >&2\n exit 2\nfi\n```\n\n## Integration with External Systems\n\n### Slack Notifications\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ndecision=\"blocked\"\n\n# Send notification to Slack\ncurl -X POST \"$SLACK_WEBHOOK\" \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"text\\\": \\\"Hook ${decision} ${tool_name} operation\\\"}\" \\\n 2>/dev/null\n\necho '{\"decision\": \"deny\"}' >&2\nexit 2\n```\n\n### Database Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\n\n# Log to database\npsql \"$DATABASE_URL\" -c \"INSERT INTO hook_logs (event, data) VALUES ('PreToolUse', '$input')\" \\\n 2>/dev/null\n\nexit 0\n```\n\n### Metrics Collection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Send metrics to monitoring system\necho \"hook.pretooluse.${tool_name}:1|c\" | nc -u -w1 statsd.local 8125\n\nexit 0\n```\n\n## Security Patterns\n\n### Rate Limiting\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Track command frequency\nrate_file=\"/tmp/hook-rate-$$\"\ncurrent_minute=$(date +%Y%m%d%H%M)\n\nif [ -f \"$rate_file\" ]; then\n last_minute=$(head -1 \"$rate_file\")\n count=$(tail -1 \"$rate_file\")\n\n if [ \"$current_minute\" = \"$last_minute\" ]; then\n if [ \"$count\" -gt 10 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Rate limit exceeded\"}' >&2\n exit 2\n fi\n count=$((count + 1))\n else\n count=1\n fi\nelse\n count=1\nfi\n\necho \"$current_minute\" > \"$rate_file\"\necho \"$count\" >> \"$rate_file\"\n\nexit 0\n```\n\n### Audit Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ntimestamp=$(date -Iseconds)\n\n# Append to audit log\necho \"$timestamp | $USER | $tool_name | $input\" >> ~/.claude/audit.log\n\nexit 0\n```\n\n### Secret Detection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncontent=$(echo \"$input\" | jq -r '.tool_input.content')\n\n# Check for common secret patterns\nif echo \"$content\" | grep -qE \"(api[_-]?key|password|secret|token).{0,20}['\\\"]?[A-Za-z0-9]{20,}\"; then\n echo '{\"decision\": \"deny\", \"reason\": \"Potential secret detected in content\"}' >&2\n exit 2\nfi\n\nexit 0\n```\n\n## Testing Advanced Hooks\n\n### Unit Testing Hook Scripts\n\n```bash\n# test-hook.sh\n#!/bin/bash\n\n# Test 1: Approve safe command\nresult=$(echo '{\"tool_input\": {\"command\": \"ls\"}}' | bash validate-bash.sh)\nif [ $? -eq 0 ]; then\n echo \"✓ Test 1 passed\"\nelse\n echo \"✗ Test 1 failed\"\nfi\n\n# Test 2: Block dangerous command\nresult=$(echo '{\"tool_input\": {\"command\": \"rm -rf /\"}}' | bash validate-bash.sh)\nif [ $? -eq 2 ]; then\n echo \"✓ Test 2 passed\"\nelse\n echo \"✗ Test 2 failed\"\nfi\n```\n\n### Integration Testing\n\nCreate test scenarios that exercise the full hook workflow:\n\n```bash\n# integration-test.sh\n#!/bin/bash\n\n# Set up test environment\nexport CLAUDE_PROJECT_DIR=\"/tmp/test-project\"\nexport CLAUDE_PLUGIN_ROOT=\"$(pwd)\"\nmkdir -p \"$CLAUDE_PROJECT_DIR\"\n\n# Test SessionStart hook\necho '{}' | bash hooks/session-start.sh\nif [ -f \"/tmp/session-initialized\" ]; then\n echo \"✓ SessionStart hook works\"\nelse\n echo \"✗ SessionStart hook failed\"\nfi\n\n# Clean up\nrm -rf \"$CLAUDE_PROJECT_DIR\"\n```\n\n## Best Practices for Advanced Hooks\n\n1. **Keep hooks independent**: Don't rely on execution order\n2. **Use timeouts**: Set appropriate limits for each hook type\n3. **Handle errors gracefully**: Provide clear error messages\n4. **Document complexity**: Explain advanced patterns in README\n5. **Test thoroughly**: Cover edge cases and failure modes\n6. **Monitor performance**: Track hook execution time\n7. **Version configuration**: Use version control for hook configs\n8. **Provide escape hatches**: Allow users to bypass hooks when needed\n\n## Common Pitfalls\n\n### ❌ Assuming Hook Order\n\n```bash\n# BAD: Assumes hooks run in specific order\n# Hook 1 saves state, Hook 2 reads it\n# This can fail because hooks run in parallel!\n```\n\n### ❌ Long-Running Hooks\n\n```bash\n# BAD: Hook takes 2 minutes to run\nsleep 120\n# This will timeout and block the workflow\n```\n\n### ❌ Uncaught Exceptions\n\n```bash\n# BAD: Script crashes on unexpected input\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncat \"$file_path\" # Fails if file doesn't exist\n```\n\n### ✅ Proper Error Handling\n\n```bash\n# GOOD: Handles errors gracefully\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nif [ ! -f \"$file_path\" ]; then\n echo '{\"continue\": true, \"systemMessage\": \"File not found, skipping check\"}' >&2\n exit 0\nfi\n```\n\n## Conclusion\n\nAdvanced hook patterns enable sophisticated automation while maintaining reliability and performance. Use these techniques when basic hooks are insufficient, but always prioritize simplicity and maintainability.\n","plugins/plugin-dev/skills/hook-development/references/migration.md":"# Migrating from Basic to Advanced Hooks\n\nThis guide shows how to migrate from basic command hooks to advanced prompt-based hooks for better maintainability and flexibility.\n\n## Why Migrate?\n\nPrompt-based hooks offer several advantages:\n\n- **Natural language reasoning**: LLM understands context and intent\n- **Better edge case handling**: Adapts to unexpected scenarios\n- **No bash scripting required**: Simpler to write and maintain\n- **More flexible validation**: Can handle complex logic without coding\n\n## Migration Example: Bash Command Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-bash.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-bash.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Hard-coded validation logic\nif [[ \"$command\" == *\"rm -rf\"* ]]; then\n echo \"Dangerous command detected\" >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Only checks for exact \"rm -rf\" pattern\n- Doesn't catch variations like `rm -fr` or `rm -r -f`\n- Misses other dangerous commands (`dd`, `mkfs`, etc.)\n- No context awareness\n- Requires bash scripting knowledge\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. Analyze for: 1) Destructive operations (rm -rf, dd, mkfs, etc) 2) Privilege escalation (sudo) 3) Network operations without user consent. Return 'approve' or 'deny' with explanation.\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Catches all variations and patterns\n- Understands intent, not just literal strings\n- No script file needed\n- Easy to extend with new criteria\n- Context-aware decisions\n- Natural language explanation in denial\n\n## Migration Example: File Write Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-write.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-write.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Check for path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Check for system paths\nif [[ \"$file_path\" == \"/etc/\"* ]] || [[ \"$file_path\" == \"/sys/\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"System file\"}' >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Hard-coded path patterns\n- Doesn't understand symlinks\n- Missing edge cases (e.g., `/etc` vs `/etc/`)\n- No consideration of file content\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Content preview: $TOOL_INPUT.content (first 200 chars). Verify: 1) Not system directories (/etc, /sys, /usr) 2) Not credentials (.env, tokens, secrets) 3) No path traversal 4) Content doesn't expose secrets. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Context-aware (considers content too)\n- Handles symlinks and edge cases\n- Natural understanding of \"system directories\"\n- Can detect secrets in content\n- Easy to extend criteria\n\n## When to Keep Command Hooks\n\nCommand hooks still have their place:\n\n### 1. Deterministic Performance Checks\n\n```bash\n#!/bin/bash\n# Check file size quickly\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nsize=$(stat -f%z \"$file_path\" 2>/dev/null || stat -c%s \"$file_path\" 2>/dev/null)\n\nif [ \"$size\" -gt 10000000 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File too large\"}' >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Validation is purely mathematical or deterministic.\n\n### 2. External Tool Integration\n\n```bash\n#!/bin/bash\n# Run security scanner\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nscan_result=$(security-scanner \"$file_path\")\n\nif [ \"$?\" -ne 0 ]; then\n echo \"Security scan failed: $scan_result\" >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Integrating with external tools that provide yes/no answers.\n\n### 3. Very Fast Checks (< 50ms)\n\n```bash\n#!/bin/bash\n# Quick regex check\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\nif [[ \"$command\" =~ ^(ls|pwd|echo)$ ]]; then\n exit 0 # Safe commands\nfi\n```\n\n**Use command hooks when:** Performance is critical and logic is simple.\n\n## Hybrid Approach\n\nCombine both for multi-stage validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\nThe command hook does fast deterministic checks, while the prompt hook handles complex reasoning.\n\n## Migration Checklist\n\nWhen migrating hooks:\n\n- [ ] Identify the validation logic in the command hook\n- [ ] Convert hard-coded patterns to natural language criteria\n- [ ] Test with edge cases the old hook missed\n- [ ] Verify LLM understands the intent\n- [ ] Set appropriate timeout (usually 15-30s for prompt hooks)\n- [ ] Document the new hook in README\n- [ ] Remove or archive old script files\n\n## Migration Tips\n\n1. **Start with one hook**: Don't migrate everything at once\n2. **Test thoroughly**: Verify prompt hook catches what command hook caught\n3. **Look for improvements**: Use migration as opportunity to enhance validation\n4. **Keep scripts for reference**: Archive old scripts in case you need to reference the logic\n5. **Document reasoning**: Explain why prompt hook is better in README\n\n## Complete Migration Example\n\n### Original Plugin Structure\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json\n└── scripts/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### After Migration\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json # Now uses prompt hooks\n└── scripts/ # Archive or delete\n └── archive/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### Updated hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety: destructive ops, privilege escalation, network access\"\n }\n ]\n },\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety: system paths, credentials, path traversal, content secrets\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests were run if code was modified\"\n }\n ]\n }\n ]\n}\n```\n\n**Result:** Simpler, more maintainable, more powerful.\n\n## Common Migration Patterns\n\n### Pattern: String Contains → Natural Language\n\n**Before:**\n```bash\nif [[ \"$command\" == *\"sudo\"* ]]; then\n echo \"Privilege escalation\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check for privilege escalation (sudo, su, etc)\"\n```\n\n### Pattern: Regex → Intent\n\n**Before:**\n```bash\nif [[ \"$file\" =~ \\.(env|secret|key|token)$ ]]; then\n echo \"Credential file\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Verify not writing to credential files (.env, secrets, keys, tokens)\"\n```\n\n### Pattern: Multiple Conditions → Criteria List\n\n**Before:**\n```bash\nif [ condition1 ] || [ condition2 ] || [ condition3 ]; then\n echo \"Invalid\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check: 1) condition1 2) condition2 3) condition3. Deny if any fail.\"\n```\n\n## Conclusion\n\nMigrating to prompt-based hooks makes plugins more maintainable, flexible, and powerful. Reserve command hooks for deterministic checks and external tool integration.\n","plugins/plugin-dev/skills/hook-development/references/patterns.md":"# Common Hook Patterns\n\nThis reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases.\n\n## Pattern 1: Security Validation\n\nBlock dangerous file writes using prompt-based hooks:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Preventing writes to sensitive files or system directories.\n\n## Pattern 2: Test Enforcement\n\nEnsure tests run before stopping:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Enforcing quality standards and preventing incomplete work.\n\n## Pattern 3: Context Loading\n\nLoad project-specific context at session start:\n\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (load-context.sh):**\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Detect project type\nif [ -f \"package.json\" ]; then\n echo \"📦 Node.js project detected\"\n echo \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\nelif [ -f \"Cargo.toml\" ]; then\n echo \"🦀 Rust project detected\"\n echo \"export PROJECT_TYPE=rust\" >> \"$CLAUDE_ENV_FILE\"\nfi\n```\n\n**Use for:** Automatically detecting and configuring project-specific settings.\n\n## Pattern 4: Notification Logging\n\nLog all notifications for audit or analysis:\n\n```json\n{\n \"Notification\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Tracking user notifications or integration with external logging systems.\n\n## Pattern 5: MCP Tool Monitoring\n\nMonitor and validate MCP tool usage:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"mcp__.*__delete.*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Protecting against destructive MCP operations.\n\n## Pattern 6: Build Verification\n\nEnsure project builds after code changes:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Catching build errors before committing or stopping work.\n\n## Pattern 7: Permission Confirmation\n\nAsk user before dangerous operations:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** User confirmation on potentially destructive commands.\n\n## Pattern 8: Code Quality Checks\n\nRun linters or formatters on file edits:\n\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (check-quality.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run linter if applicable\nif [[ \"$file_path\" == *.js ]] || [[ \"$file_path\" == *.ts ]]; then\n npx eslint \"$file_path\" 2>&1 || true\nfi\n```\n\n**Use for:** Automatic code quality enforcement.\n\n## Pattern Combinations\n\nCombine multiple patterns for comprehensive protection:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n },\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests run and build succeeded\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\nThis provides multi-layered protection and automation.\n\n## Pattern 9: Temporarily Active Hooks\n\nCreate hooks that only run when explicitly enabled via flag files:\n\n```bash\n#!/bin/bash\n# Hook only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-security-scan\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Quick exit when disabled\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run security scan\nsecurity-scanner \"$file_path\"\n```\n\n**Activation:**\n```bash\n# Enable the hook\ntouch .enable-security-scan\n\n# Disable the hook\nrm .enable-security-scan\n```\n\n**Use for:**\n- Temporary debugging hooks\n- Feature flags for development\n- Project-specific validation that's opt-in\n- Performance-intensive checks only when needed\n\n**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes.\n\n## Pattern 10: Configuration-Driven Hooks\n\nUse JSON configuration to control hook behavior:\n\n```bash\n#!/bin/bash\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json\"\n\n# Read configuration\nif [ -f \"$CONFIG_FILE\" ]; then\n strict_mode=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n max_file_size=$(jq -r '.maxFileSize // 1000000' \"$CONFIG_FILE\")\nelse\n # Defaults\n strict_mode=false\n max_file_size=1000000\nfi\n\n# Skip if not in strict mode\nif [ \"$strict_mode\" != \"true\" ]; then\n exit 0\nfi\n\n# Apply configured limits\ninput=$(cat)\nfile_size=$(echo \"$input\" | jq -r '.tool_input.content | length')\n\nif [ \"$file_size\" -gt \"$max_file_size\" ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File exceeds configured size limit\"}' >&2\n exit 2\nfi\n```\n\n**Configuration file (.claude/my-plugin.local.json):**\n```json\n{\n \"strictMode\": true,\n \"maxFileSize\": 500000,\n \"allowedPaths\": [\"/tmp\", \"/home/user/projects\"]\n}\n```\n\n**Use for:**\n- User-configurable hook behavior\n- Per-project settings\n- Team-specific rules\n- Dynamic validation criteria\n","plugins/plugin-dev/skills/hook-development/scripts/README.md":"","plugins/plugin-dev/skills/mcp-integration/SKILL.md":"---\nname: MCP Integration\ndescription: This skill should be used when the user asks to \"add MCP server\", \"integrate MCP\", \"configure MCP in plugin\", \"use .mcp.json\", \"set up Model Context Protocol\", \"connect external service\", mentions \"${CLAUDE_PLUGIN_ROOT} with MCP\", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.\nversion: 0.1.0\n---\n\n# MCP Integration for Claude Code Plugins\n\n## Overview\n\nModel Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.\n\n**Key capabilities:**\n- Connect to external services (databases, APIs, file systems)\n- Provide 10+ related tools from a single service\n- Handle OAuth and complex authentication flows\n- Bundle MCP servers with plugins for automatic setup\n\n## MCP Server Configuration Methods\n\nPlugins can bundle MCP servers in two ways:\n\n### Method 1: Dedicated .mcp.json (Recommended)\n\nCreate `.mcp.json` at plugin root:\n\n```json\n{\n \"database-tools\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server\",\n \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config.json\"],\n \"env\": {\n \"DB_URL\": \"${DB_URL}\"\n }\n }\n}\n```\n\n**Benefits:**\n- Clear separation of concerns\n- Easier to maintain\n- Better for multiple servers\n\n### Method 2: Inline in plugin.json\n\nAdd `mcpServers` field to plugin.json:\n\n```json\n{\n \"name\": \"my-plugin\",\n \"version\": \"1.0.0\",\n \"mcpServers\": {\n \"plugin-api\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/api-server\",\n \"args\": [\"--port\", \"8080\"]\n }\n }\n}\n```\n\n**Benefits:**\n- Single configuration file\n- Good for simple single-server plugins\n\n## MCP Server Types\n\n### stdio (Local Process)\n\nExecute local MCP servers as child processes. Best for local tools and custom servers.\n\n**Configuration:**\n```json\n{\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/allowed/path\"],\n \"env\": {\n \"LOG_LEVEL\": \"debug\"\n }\n }\n}\n```\n\n**Use cases:**\n- File system access\n- Local database connections\n- Custom MCP servers\n- NPM-packaged MCP servers\n\n**Process management:**\n- Claude Code spawns and manages the process\n- Communicates via stdin/stdout\n- Terminates when Claude Code exits\n\n### SSE (Server-Sent Events)\n\nConnect to hosted MCP servers with OAuth support. Best for cloud services.\n\n**Configuration:**\n```json\n{\n \"asana\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.asana.com/sse\"\n }\n}\n```\n\n**Use cases:**\n- Official hosted MCP servers (Asana, GitHub, etc.)\n- Cloud services with MCP endpoints\n- OAuth-based authentication\n- No local installation needed\n\n**Authentication:**\n- OAuth flows handled automatically\n- User prompted on first use\n- Tokens managed by Claude Code\n\n### HTTP (REST API)\n\nConnect to RESTful MCP servers with token authentication.\n\n**Configuration:**\n```json\n{\n \"api-service\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"X-Custom-Header\": \"value\"\n }\n }\n}\n```\n\n**Use cases:**\n- REST API-based MCP servers\n- Token-based authentication\n- Custom API backends\n- Stateless interactions\n\n### WebSocket (Real-time)\n\nConnect to WebSocket MCP servers for real-time bidirectional communication.\n\n**Configuration:**\n```json\n{\n \"realtime-service\": {\n \"type\": \"ws\",\n \"url\": \"wss://mcp.example.com/ws\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TOKEN}\"\n }\n }\n}\n```\n\n**Use cases:**\n- Real-time data streaming\n- Persistent connections\n- Push notifications from server\n- Low-latency requirements\n\n## Environment Variable Expansion\n\nAll MCP configurations support environment variable substitution:\n\n**${CLAUDE_PLUGIN_ROOT}** - Plugin directory (always use for portability):\n```json\n{\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/my-server\"\n}\n```\n\n**User environment variables** - From user's shell:\n```json\n{\n \"env\": {\n \"API_KEY\": \"${MY_API_KEY}\",\n \"DATABASE_URL\": \"${DB_URL}\"\n }\n}\n```\n\n**Best practice:** Document all required environment variables in plugin README.\n\n## MCP Tool Naming\n\nWhen MCP servers provide tools, they're automatically prefixed:\n\n**Format:** `mcp__plugin____`\n\n**Example:**\n- Plugin: `asana`\n- Server: `asana`\n- Tool: `create_task`\n- **Full name:** `mcp__plugin_asana_asana__asana_create_task`\n\n### Using MCP Tools in Commands\n\nPre-allow specific MCP tools in command frontmatter:\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\",\n \"mcp__plugin_asana_asana__asana_search_tasks\"\n]\n---\n```\n\n**Wildcard (use sparingly):**\n```markdown\n---\nallowed-tools: [\"mcp__plugin_asana_asana__*\"]\n---\n```\n\n**Best practice:** Pre-allow specific tools, not wildcards, for security.\n\n## Lifecycle Management\n\n**Automatic startup:**\n- MCP servers start when plugin enables\n- Connection established before first tool use\n- Restart required for configuration changes\n\n**Lifecycle:**\n1. Plugin loads\n2. MCP configuration parsed\n3. Server process started (stdio) or connection established (SSE/HTTP/WS)\n4. Tools discovered and registered\n5. Tools available as `mcp__plugin_...__...`\n\n**Viewing servers:**\nUse `/mcp` command to see all servers including plugin-provided ones.\n\n## Authentication Patterns\n\n### OAuth (SSE/HTTP)\n\nOAuth handled automatically by Claude Code:\n\n```json\n{\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\"\n}\n```\n\nUser authenticates in browser on first use. No additional configuration needed.\n\n### Token-Based (Headers)\n\nStatic or environment variable tokens:\n\n```json\n{\n \"type\": \"http\",\n \"url\": \"https://api.example.com\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\"\n }\n}\n```\n\nDocument required environment variables in README.\n\n### Environment Variables (stdio)\n\nPass configuration to MCP server:\n\n```json\n{\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\"],\n \"env\": {\n \"DATABASE_URL\": \"${DB_URL}\",\n \"API_KEY\": \"${API_KEY}\",\n \"LOG_LEVEL\": \"info\"\n }\n}\n```\n\n## Integration Patterns\n\n### Pattern 1: Simple Tool Wrapper\n\nCommands use MCP tools with user interaction:\n\n```markdown\n# Command: create-item.md\n---\nallowed-tools: [\"mcp__plugin_name_server__create_item\"]\n---\n\nSteps:\n1. Gather item details from user\n2. Use mcp__plugin_name_server__create_item\n3. Confirm creation\n```\n\n**Use for:** Adding validation or preprocessing before MCP calls.\n\n### Pattern 2: Autonomous Agent\n\nAgents use MCP tools autonomously:\n\n```markdown\n# Agent: data-analyzer.md\n\nAnalysis Process:\n1. Query data via mcp__plugin_db_server__query\n2. Process and analyze results\n3. Generate insights report\n```\n\n**Use for:** Multi-step MCP workflows without user interaction.\n\n### Pattern 3: Multi-Server Plugin\n\nIntegrate multiple MCP servers:\n\n```json\n{\n \"github\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.github.com/sse\"\n },\n \"jira\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.jira.com/sse\"\n }\n}\n```\n\n**Use for:** Workflows spanning multiple services.\n\n## Security Best Practices\n\n### Use HTTPS/WSS\n\nAlways use secure connections:\n\n```json\n✅ \"url\": \"https://mcp.example.com/sse\"\n❌ \"url\": \"http://mcp.example.com/sse\"\n```\n\n### Token Management\n\n**DO:**\n- ✅ Use environment variables for tokens\n- ✅ Document required env vars in README\n- ✅ Let OAuth flow handle authentication\n\n**DON'T:**\n- ❌ Hardcode tokens in configuration\n- ❌ Commit tokens to git\n- ❌ Share tokens in documentation\n\n### Permission Scoping\n\nPre-allow only necessary MCP tools:\n\n```markdown\n✅ allowed-tools: [\n \"mcp__plugin_api_server__read_data\",\n \"mcp__plugin_api_server__create_item\"\n]\n\n❌ allowed-tools: [\"mcp__plugin_api_server__*\"]\n```\n\n## Error Handling\n\n### Connection Failures\n\nHandle MCP server unavailability:\n- Provide fallback behavior in commands\n- Inform user of connection issues\n- Check server URL and configuration\n\n### Tool Call Errors\n\nHandle failed MCP operations:\n- Validate inputs before calling MCP tools\n- Provide clear error messages\n- Check rate limiting and quotas\n\n### Configuration Errors\n\nValidate MCP configuration:\n- Test server connectivity during development\n- Validate JSON syntax\n- Check required environment variables\n\n## Performance Considerations\n\n### Lazy Loading\n\nMCP servers connect on-demand:\n- Not all servers connect at startup\n- First tool use triggers connection\n- Connection pooling managed automatically\n\n### Batching\n\nBatch similar requests when possible:\n\n```\n# Good: Single query with filters\ntasks = search_tasks(project=\"X\", assignee=\"me\", limit=50)\n\n# Avoid: Many individual queries\nfor id in task_ids:\n task = get_task(id)\n```\n\n## Testing MCP Integration\n\n### Local Testing\n\n1. Configure MCP server in `.mcp.json`\n2. Install plugin locally (`.claude-plugin/`)\n3. Run `/mcp` to verify server appears\n4. Test tool calls in commands\n5. Check `claude --debug` logs for connection issues\n\n### Validation Checklist\n\n- [ ] MCP configuration is valid JSON\n- [ ] Server URL is correct and accessible\n- [ ] Required environment variables documented\n- [ ] Tools appear in `/mcp` output\n- [ ] Authentication works (OAuth or tokens)\n- [ ] Tool calls succeed from commands\n- [ ] Error cases handled gracefully\n\n## Debugging\n\n### Enable Debug Logging\n\n```bash\nclaude --debug\n```\n\nLook for:\n- MCP server connection attempts\n- Tool discovery logs\n- Authentication flows\n- Tool call errors\n\n### Common Issues\n\n**Server not connecting:**\n- Check URL is correct\n- Verify server is running (stdio)\n- Check network connectivity\n- Review authentication configuration\n\n**Tools not available:**\n- Verify server connected successfully\n- Check tool names match exactly\n- Run `/mcp` to see available tools\n- Restart Claude Code after config changes\n\n**Authentication failing:**\n- Clear cached auth tokens\n- Re-authenticate\n- Check token scopes and permissions\n- Verify environment variables set\n\n## Quick Reference\n\n### MCP Server Types\n\n| Type | Transport | Best For | Auth |\n|------|-----------|----------|------|\n| stdio | Process | Local tools, custom servers | Env vars |\n| SSE | HTTP | Hosted services, cloud APIs | OAuth |\n| HTTP | REST | API backends, token auth | Tokens |\n| ws | WebSocket | Real-time, streaming | Tokens |\n\n### Configuration Checklist\n\n- [ ] Server type specified (stdio/SSE/HTTP/ws)\n- [ ] Type-specific fields complete (command or url)\n- [ ] Authentication configured\n- [ ] Environment variables documented\n- [ ] HTTPS/WSS used (not HTTP/WS)\n- [ ] ${CLAUDE_PLUGIN_ROOT} used for paths\n\n### Best Practices\n\n**DO:**\n- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths\n- ✅ Document required environment variables\n- ✅ Use secure connections (HTTPS/WSS)\n- ✅ Pre-allow specific MCP tools in commands\n- ✅ Test MCP integration before publishing\n- ✅ Handle connection and tool errors gracefully\n\n**DON'T:**\n- ❌ Hardcode absolute paths\n- ❌ Commit credentials to git\n- ❌ Use HTTP instead of HTTPS\n- ❌ Pre-allow all tools with wildcards\n- ❌ Skip error handling\n- ❌ Forget to document setup\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed information, consult:\n\n- **`references/server-types.md`** - Deep dive on each server type\n- **`references/authentication.md`** - Authentication patterns and OAuth\n- **`references/tool-usage.md`** - Using MCP tools in commands and agents\n\n### Example Configurations\n\nWorking examples in `examples/`:\n\n- **`stdio-server.json`** - Local stdio MCP server\n- **`sse-server.json`** - Hosted SSE server with OAuth\n- **`http-server.json`** - REST API with token auth\n\n### External Resources\n\n- **Official MCP Docs**: https://modelcontextprotocol.io/\n- **Claude Code MCP Docs**: https://docs.claude.com/en/docs/claude-code/mcp\n- **MCP SDK**: @modelcontextprotocol/sdk\n- **Testing**: Use `claude --debug` and `/mcp` command\n\n## Implementation Workflow\n\nTo add MCP integration to a plugin:\n\n1. Choose MCP server type (stdio, SSE, HTTP, ws)\n2. Create `.mcp.json` at plugin root with configuration\n3. Use ${CLAUDE_PLUGIN_ROOT} for all file references\n4. Document required environment variables in README\n5. Test locally with `/mcp` command\n6. Pre-allow MCP tools in relevant commands\n7. Handle authentication (OAuth or tokens)\n8. Test error cases (connection failures, auth errors)\n9. Document MCP integration in plugin README\n\nFocus on stdio for custom/local servers, SSE for hosted services with OAuth.\n","plugins/plugin-dev/skills/mcp-integration/examples/http-server.json":"{\n \"_comment\": \"Example HTTP MCP server configuration for REST APIs\",\n \"rest-api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"Content-Type\": \"application/json\",\n \"X-API-Version\": \"2024-01-01\"\n }\n },\n \"internal-service\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"X-Service-Name\": \"claude-plugin\"\n }\n }\n}\n","plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json":"{\n \"_comment\": \"Example SSE MCP server configuration for hosted cloud services\",\n \"asana\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.asana.com/sse\"\n },\n \"github\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.github.com/sse\"\n },\n \"custom-service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-API-Version\": \"v1\",\n \"X-Client-ID\": \"${CLIENT_ID}\"\n }\n }\n}\n","plugins/plugin-dev/skills/mcp-integration/examples/stdio-server.json":"{\n \"_comment\": \"Example stdio MCP server configuration for local file system access\",\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"${CLAUDE_PROJECT_DIR}\"],\n \"env\": {\n \"LOG_LEVEL\": \"info\"\n }\n },\n \"database\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server.js\",\n \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config/db.json\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_POOL_SIZE\": \"10\"\n }\n },\n \"custom-tools\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\", \"--port\", \"8080\"],\n \"env\": {\n \"API_KEY\": \"${CUSTOM_API_KEY}\",\n \"DEBUG\": \"false\"\n }\n }\n}\n","plugins/plugin-dev/skills/mcp-integration/references/authentication.md":"# MCP Authentication Patterns\n\nComplete guide to authentication methods for MCP servers in Claude Code plugins.\n\n## Overview\n\nMCP servers support multiple authentication methods depending on the server type and service requirements. Choose the method that best matches your use case and security requirements.\n\n## OAuth (Automatic)\n\n### How It Works\n\nClaude Code automatically handles the complete OAuth 2.0 flow for SSE and HTTP servers:\n\n1. User attempts to use MCP tool\n2. Claude Code detects authentication needed\n3. Opens browser for OAuth consent\n4. User authorizes in browser\n5. Tokens stored securely by Claude Code\n6. Automatic token refresh\n\n### Configuration\n\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\"\n }\n}\n```\n\nNo additional auth configuration needed! Claude Code handles everything.\n\n### Supported Services\n\n**Known OAuth-enabled MCP servers:**\n- Asana: `https://mcp.asana.com/sse`\n- GitHub (when available)\n- Google services (when available)\n- Custom OAuth servers\n\n### OAuth Scopes\n\nOAuth scopes are determined by the MCP server. Users see required scopes during the consent flow.\n\n**Document required scopes in your README:**\n```markdown\n## Authentication\n\nThis plugin requires the following Asana permissions:\n- Read tasks and projects\n- Create and update tasks\n- Access workspace data\n```\n\n### Token Storage\n\nTokens are stored securely by Claude Code:\n- Not accessible to plugins\n- Encrypted at rest\n- Automatic refresh\n- Cleared on sign-out\n\n### Troubleshooting OAuth\n\n**Authentication loop:**\n- Clear cached tokens (sign out and sign in)\n- Check OAuth redirect URLs\n- Verify server OAuth configuration\n\n**Scope issues:**\n- User may need to re-authorize for new scopes\n- Check server documentation for required scopes\n\n**Token expiration:**\n- Claude Code auto-refreshes\n- If refresh fails, prompts re-authentication\n\n## Token-Based Authentication\n\n### Bearer Tokens\n\nMost common for HTTP and WebSocket servers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\"\n }\n }\n}\n```\n\n**Environment variable:**\n```bash\nexport API_TOKEN=\"your-secret-token-here\"\n```\n\n### API Keys\n\nAlternative to Bearer tokens, often in custom headers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"X-API-Key\": \"${API_KEY}\",\n \"X-API-Secret\": \"${API_SECRET}\"\n }\n }\n}\n```\n\n### Custom Headers\n\nServices may use custom authentication headers.\n\n**Configuration:**\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-Auth-Token\": \"${AUTH_TOKEN}\",\n \"X-User-ID\": \"${USER_ID}\",\n \"X-Tenant-ID\": \"${TENANT_ID}\"\n }\n }\n}\n```\n\n### Documenting Token Requirements\n\nAlways document in your README:\n\n```markdown\n## Setup\n\n### Required Environment Variables\n\nSet these environment variables before using the plugin:\n\n\\`\\`\\`bash\nexport API_TOKEN=\"your-token-here\"\nexport API_SECRET=\"your-secret-here\"\n\\`\\`\\`\n\n### Obtaining Tokens\n\n1. Visit https://api.example.com/tokens\n2. Create a new API token\n3. Copy the token and secret\n4. Set environment variables as shown above\n\n### Token Permissions\n\nThe API token needs the following permissions:\n- Read access to resources\n- Write access for creating items\n- Delete access (optional, for cleanup operations)\n\\`\\`\\`\n```\n\n## Environment Variable Authentication (stdio)\n\n### Passing Credentials to Server\n\nFor stdio servers, pass credentials via environment variables:\n\n```json\n{\n \"database\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server_db\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_USER\": \"${DB_USER}\",\n \"DB_PASSWORD\": \"${DB_PASSWORD}\"\n }\n }\n}\n```\n\n### User Environment Variables\n\n```bash\n# User sets these in their shell\nexport DATABASE_URL=\"postgresql://localhost/mydb\"\nexport DB_USER=\"myuser\"\nexport DB_PASSWORD=\"mypassword\"\n```\n\n### Documentation Template\n\n```markdown\n## Database Configuration\n\nSet these environment variables:\n\n\\`\\`\\`bash\nexport DATABASE_URL=\"postgresql://host:port/database\"\nexport DB_USER=\"username\"\nexport DB_PASSWORD=\"password\"\n\\`\\`\\`\n\nOr create a `.env` file (add to `.gitignore`):\n\n\\`\\`\\`\nDATABASE_URL=postgresql://localhost:5432/mydb\nDB_USER=myuser\nDB_PASSWORD=mypassword\n\\`\\`\\`\n\nLoad with: \\`source .env\\` or \\`export $(cat .env | xargs)\\`\n\\`\\`\\`\n```\n\n## Dynamic Headers\n\n### Headers Helper Script\n\nFor tokens that change or expire, use a helper script:\n\n```json\n{\n \"api\": {\n \"type\": \"sse\",\n \"url\": \"https://api.example.com\",\n \"headersHelper\": \"${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh\"\n }\n}\n```\n\n**Script (get-headers.sh):**\n```bash\n#!/bin/bash\n# Generate dynamic authentication headers\n\n# Fetch fresh token\nTOKEN=$(get-fresh-token-from-somewhere)\n\n# Output JSON headers\ncat <___`. Use these tools in commands and agents just like built-in Claude Code tools.\n\n## Tool Naming Convention\n\n### Format\n\n```\nmcp__plugin____\n```\n\n### Examples\n\n**Asana plugin with asana server:**\n- `mcp__plugin_asana_asana__asana_create_task`\n- `mcp__plugin_asana_asana__asana_search_tasks`\n- `mcp__plugin_asana_asana__asana_get_project`\n\n**Custom plugin with database server:**\n- `mcp__plugin_myplug_database__query`\n- `mcp__plugin_myplug_database__execute`\n- `mcp__plugin_myplug_database__list_tables`\n\n### Discovering Tool Names\n\n**Use `/mcp` command:**\n```bash\n/mcp\n```\n\nThis shows:\n- All available MCP servers\n- Tools provided by each server\n- Tool schemas and descriptions\n- Full tool names for use in configuration\n\n## Using Tools in Commands\n\n### Pre-Allowing Tools\n\nSpecify MCP tools in command frontmatter:\n\n```markdown\n---\ndescription: Create a new Asana task\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\"\n]\n---\n\n# Create Task Command\n\nTo create a task:\n1. Gather task details from user\n2. Use mcp__plugin_asana_asana__asana_create_task with the details\n3. Confirm creation to user\n```\n\n### Multiple Tools\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\",\n \"mcp__plugin_asana_asana__asana_search_tasks\",\n \"mcp__plugin_asana_asana__asana_get_project\"\n]\n---\n```\n\n### Wildcard (Use Sparingly)\n\n```markdown\n---\nallowed-tools: [\"mcp__plugin_asana_asana__*\"]\n---\n```\n\n**Caution:** Only use wildcards if the command truly needs access to all tools from a server.\n\n### Tool Usage in Command Instructions\n\n**Example command:**\n```markdown\n---\ndescription: Search and create Asana tasks\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_search_tasks\",\n \"mcp__plugin_asana_asana__asana_create_task\"\n]\n---\n\n# Asana Task Management\n\n## Searching Tasks\n\nTo search for tasks:\n1. Use mcp__plugin_asana_asana__asana_search_tasks\n2. Provide search filters (assignee, project, etc.)\n3. Display results to user\n\n## Creating Tasks\n\nTo create a task:\n1. Gather task details:\n - Title (required)\n - Description\n - Project\n - Assignee\n - Due date\n2. Use mcp__plugin_asana_asana__asana_create_task\n3. Show confirmation with task link\n```\n\n## Using Tools in Agents\n\n### Agent Configuration\n\nAgents can use MCP tools autonomously without pre-allowing them:\n\n```markdown\n---\nname: asana-status-updater\ndescription: This agent should be used when the user asks to \"update Asana status\", \"generate project report\", or \"sync Asana tasks\"\nmodel: inherit\ncolor: blue\n---\n\n## Role\n\nAutonomous agent for generating Asana project status reports.\n\n## Process\n\n1. **Query tasks**: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks\n2. **Analyze progress**: Calculate completion rates and identify blockers\n3. **Generate report**: Create formatted status update\n4. **Update Asana**: Use mcp__plugin_asana_asana__asana_create_comment to post report\n\n## Available Tools\n\nThe agent has access to all Asana MCP tools without pre-approval.\n```\n\n### Agent Tool Access\n\nAgents have broader tool access than commands:\n- Can use any tool Claude determines is necessary\n- Don't need pre-allowed lists\n- Should document which tools they typically use\n\n## Tool Call Patterns\n\n### Pattern 1: Simple Tool Call\n\nSingle tool call with validation:\n\n```markdown\nSteps:\n1. Validate user provided required fields\n2. Call mcp__plugin_api_server__create_item with validated data\n3. Check for errors\n4. Display confirmation\n```\n\n### Pattern 2: Sequential Tools\n\nChain multiple tool calls:\n\n```markdown\nSteps:\n1. Search for existing items: mcp__plugin_api_server__search\n2. If not found, create new: mcp__plugin_api_server__create\n3. Add metadata: mcp__plugin_api_server__update_metadata\n4. Return final item ID\n```\n\n### Pattern 3: Batch Operations\n\nMultiple calls with same tool:\n\n```markdown\nSteps:\n1. Get list of items to process\n2. For each item:\n - Call mcp__plugin_api_server__update_item\n - Track success/failure\n3. Report results summary\n```\n\n### Pattern 4: Error Handling\n\nGraceful error handling:\n\n```markdown\nSteps:\n1. Try to call mcp__plugin_api_server__get_data\n2. If error (rate limit, network, etc.):\n - Wait and retry (max 3 attempts)\n - If still failing, inform user\n - Suggest checking configuration\n3. On success, process data\n```\n\n## Tool Parameters\n\n### Understanding Tool Schemas\n\nEach MCP tool has a schema defining its parameters. View with `/mcp`.\n\n**Example schema:**\n```json\n{\n \"name\": \"asana_create_task\",\n \"description\": \"Create a new Asana task\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Task title\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"Task description\"\n },\n \"workspace\": {\n \"type\": \"string\",\n \"description\": \"Workspace GID\"\n }\n },\n \"required\": [\"name\", \"workspace\"]\n }\n}\n```\n\n### Calling Tools with Parameters\n\nClaude automatically structures tool calls based on schema:\n\n```typescript\n// Claude generates this internally\n{\n toolName: \"mcp__plugin_asana_asana__asana_create_task\",\n input: {\n name: \"Review PR #123\",\n notes: \"Code review for new feature\",\n workspace: \"12345\",\n assignee: \"67890\",\n due_on: \"2025-01-15\"\n }\n}\n```\n\n### Parameter Validation\n\n**In commands, validate before calling:**\n\n```markdown\nSteps:\n1. Check required parameters:\n - Title is not empty\n - Workspace ID is provided\n - Due date is valid format (YYYY-MM-DD)\n2. If validation fails, ask user to provide missing data\n3. If validation passes, call MCP tool\n4. Handle tool errors gracefully\n```\n\n## Response Handling\n\n### Success Responses\n\n```markdown\nSteps:\n1. Call MCP tool\n2. On success:\n - Extract relevant data from response\n - Format for user display\n - Provide confirmation message\n - Include relevant links or IDs\n```\n\n### Error Responses\n\n```markdown\nSteps:\n1. Call MCP tool\n2. On error:\n - Check error type (auth, rate limit, validation, etc.)\n - Provide helpful error message\n - Suggest remediation steps\n - Don't expose internal error details to user\n```\n\n### Partial Success\n\n```markdown\nSteps:\n1. Batch operation with multiple MCP calls\n2. Track successes and failures separately\n3. Report summary:\n - \"Successfully processed 8 of 10 items\"\n - \"Failed items: [item1, item2] due to [reason]\"\n - Suggest retry or manual intervention\n```\n\n## Performance Optimization\n\n### Batching Requests\n\n**Good: Single query with filters**\n```markdown\nSteps:\n1. Call mcp__plugin_api_server__search with filters:\n - project_id: \"123\"\n - status: \"active\"\n - limit: 100\n2. Process all results\n```\n\n**Avoid: Many individual queries**\n```markdown\nSteps:\n1. For each item ID:\n - Call mcp__plugin_api_server__get_item\n - Process item\n```\n\n### Caching Results\n\n```markdown\nSteps:\n1. Call expensive MCP operation: mcp__plugin_api_server__analyze\n2. Store results in variable for reuse\n3. Use cached results for subsequent operations\n4. Only re-fetch if data changes\n```\n\n### Parallel Tool Calls\n\nWhen tools don't depend on each other, call in parallel:\n\n```markdown\nSteps:\n1. Make parallel calls (Claude handles this automatically):\n - mcp__plugin_api_server__get_project\n - mcp__plugin_api_server__get_users\n - mcp__plugin_api_server__get_tags\n2. Wait for all to complete\n3. Combine results\n```\n\n## Integration Best Practices\n\n### User Experience\n\n**Provide feedback:**\n```markdown\nSteps:\n1. Inform user: \"Searching Asana tasks...\"\n2. Call mcp__plugin_asana_asana__asana_search_tasks\n3. Show progress: \"Found 15 tasks, analyzing...\"\n4. Present results\n```\n\n**Handle long operations:**\n```markdown\nSteps:\n1. Warn user: \"This may take a minute...\"\n2. Break into smaller steps with updates\n3. Show incremental progress\n4. Final summary when complete\n```\n\n### Error Messages\n\n**Good error messages:**\n```\n❌ \"Could not create task. Please check:\n 1. You're logged into Asana\n 2. You have access to workspace 'Engineering'\n 3. The project 'Q1 Goals' exists\"\n```\n\n**Poor error messages:**\n```\n❌ \"Error: MCP tool returned 403\"\n```\n\n### Documentation\n\n**Document MCP tool usage in command:**\n```markdown\n## MCP Tools Used\n\nThis command uses the following Asana MCP tools:\n- **asana_search_tasks**: Search for tasks matching criteria\n- **asana_create_task**: Create new task with details\n- **asana_update_task**: Update existing task properties\n\nEnsure you're authenticated to Asana before running this command.\n```\n\n## Testing Tool Usage\n\n### Local Testing\n\n1. **Configure MCP server** in `.mcp.json`\n2. **Install plugin locally** in `.claude-plugin/`\n3. **Verify tools available** with `/mcp`\n4. **Test command** that uses tools\n5. **Check debug output**: `claude --debug`\n\n### Test Scenarios\n\n**Test successful calls:**\n```markdown\nSteps:\n1. Create test data in external service\n2. Run command that queries this data\n3. Verify correct results returned\n```\n\n**Test error cases:**\n```markdown\nSteps:\n1. Test with missing authentication\n2. Test with invalid parameters\n3. Test with non-existent resources\n4. Verify graceful error handling\n```\n\n**Test edge cases:**\n```markdown\nSteps:\n1. Test with empty results\n2. Test with maximum results\n3. Test with special characters\n4. Test with concurrent access\n```\n\n## Common Patterns\n\n### Pattern: CRUD Operations\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_api_server__create_item\",\n \"mcp__plugin_api_server__read_item\",\n \"mcp__plugin_api_server__update_item\",\n \"mcp__plugin_api_server__delete_item\"\n]\n---\n\n# Item Management\n\n## Create\nUse create_item with required fields...\n\n## Read\nUse read_item with item ID...\n\n## Update\nUse update_item with item ID and changes...\n\n## Delete\nUse delete_item with item ID (ask for confirmation first)...\n```\n\n### Pattern: Search and Process\n\n```markdown\nSteps:\n1. **Search**: mcp__plugin_api_server__search with filters\n2. **Filter**: Apply additional local filtering if needed\n3. **Transform**: Process each result\n4. **Present**: Format and display to user\n```\n\n### Pattern: Multi-Step Workflow\n\n```markdown\nSteps:\n1. **Setup**: Gather all required information\n2. **Validate**: Check data completeness\n3. **Execute**: Chain of MCP tool calls:\n - Create parent resource\n - Create child resources\n - Link resources together\n - Add metadata\n4. **Verify**: Confirm all steps succeeded\n5. **Report**: Provide summary to user\n```\n\n## Troubleshooting\n\n### Tools Not Available\n\n**Check:**\n- MCP server configured correctly\n- Server connected (check `/mcp`)\n- Tool names match exactly (case-sensitive)\n- Restart Claude Code after config changes\n\n### Tool Calls Failing\n\n**Check:**\n- Authentication is valid\n- Parameters match tool schema\n- Required parameters provided\n- Check `claude --debug` logs\n\n### Performance Issues\n\n**Check:**\n- Batching queries instead of individual calls\n- Caching results when appropriate\n- Not making unnecessary tool calls\n- Parallel calls when possible\n\n## Conclusion\n\nEffective MCP tool usage requires:\n1. **Understanding tool schemas** via `/mcp`\n2. **Pre-allowing tools** in commands appropriately\n3. **Handling errors gracefully**\n4. **Optimizing performance** with batching and caching\n5. **Providing good UX** with feedback and clear errors\n6. **Testing thoroughly** before deployment\n\nFollow these patterns for robust MCP tool integration in your plugin commands and agents.\n","plugins/plugin-dev/skills/plugin-settings/SKILL.md":"---\nname: Plugin Settings\ndescription: This skill should be used when the user asks about \"plugin settings\", \"store plugin configuration\", \"user-configurable plugin\", \".local.md files\", \"plugin state files\", \"read YAML frontmatter\", \"per-project plugin settings\", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.\nversion: 0.1.0\n---\n\n# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store user-configurable settings and state in `.claude/plugin-name.local.md` files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.\n\n**Key characteristics:**\n- File location: `.claude/plugin-name.local.md` in project root\n- Structure: YAML frontmatter + markdown body\n- Purpose: Per-project plugin configuration and state\n- Usage: Read from hooks, commands, and agents\n- Lifecycle: User-managed (not in git, should be in `.gitignore`)\n\n## File Structure\n\n### Basic Template\n\n```markdown\n---\nenabled: true\nsetting1: value1\nsetting2: value2\nnumeric_setting: 42\nlist_setting: [\"item1\", \"item2\"]\n---\n\n# Additional Context\n\nThis markdown body can contain:\n- Task descriptions\n- Additional instructions\n- Prompts to feed back to Claude\n- Documentation or notes\n```\n\n### Example: Plugin State File\n\n**.claude/my-plugin.local.md:**\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_retries: 3\nnotification_level: info\ncoordinator_session: team-leader\n---\n\n# Plugin Configuration\n\nThis plugin is configured for standard validation mode.\nContact @team-lead with questions.\n```\n\n## Reading Settings Files\n\n### From Hooks (Bash Scripts)\n\n**Pattern: Check existence and parse frontmatter**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Define state file path\nSTATE_FILE=\".claude/my-plugin.local.md\"\n\n# Quick exit if file doesn't exist\nif [[ ! -f \"$STATE_FILE\" ]]; then\n exit 0 # Plugin not configured, skip\nfi\n\n# Parse YAML frontmatter (between --- markers)\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$STATE_FILE\")\n\n# Extract individual fields\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0 # Disabled\nfi\n\n# Use configuration in hook logic\nif [[ \"$STRICT_MODE\" == \"true\" ]]; then\n # Apply strict validation\n # ...\nfi\n```\n\nSee `examples/read-settings-hook.sh` for complete working example.\n\n### From Commands\n\nCommands can read settings files to customize behavior:\n\n```markdown\n---\ndescription: Process data with plugin\nallowed-tools: [\"Read\", \"Bash\"]\n---\n\n# Process Command\n\nSteps:\n1. Check if settings exist at `.claude/my-plugin.local.md`\n2. Read configuration using Read tool\n3. Parse YAML frontmatter to extract settings\n4. Apply settings to processing logic\n5. Execute with configured behavior\n```\n\n### From Agents\n\nAgents can reference settings in their instructions:\n\n```markdown\n---\nname: configured-agent\ndescription: Agent that adapts to project settings\n---\n\nCheck for plugin settings at `.claude/my-plugin.local.md`.\nIf present, parse YAML frontmatter and adapt behavior according to:\n- enabled: Whether plugin is active\n- mode: Processing mode (strict, standard, lenient)\n- Additional configuration fields\n```\n\n## Parsing Techniques\n\n### Extract Frontmatter\n\n```bash\n# Extract everything between --- markers\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n```\n\n### Read Individual Fields\n\n**String fields:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n# Compare: if [[ \"$ENABLED\" == \"true\" ]]; then\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n# Use: if [[ $MAX -gt 100 ]]; then\n```\n\n### Read Markdown Body\n\nExtract content after second `---`:\n\n```bash\n# Get everything after closing ---\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n## Common Patterns\n\n### Pattern 1: Temporarily Active Hooks\n\nUse settings file to control hook activation:\n\n```bash\n#!/bin/bash\nSTATE_FILE=\".claude/security-scan.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Read enabled flag\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0 # Disabled\nfi\n\n# Run hook logic\n# ...\n```\n\n**Use case:** Enable/disable hooks without editing hooks.json (requires restart).\n\n### Pattern 2: Agent State Management\n\nStore agent-specific state and configuration:\n\n**.claude/multi-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-agent\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\n---\n\n# Task Assignment\n\nImplement JWT authentication for the API.\n\n**Success Criteria:**\n- Authentication endpoints created\n- Tests passing\n- PR created and CI green\n```\n\nRead from hooks to coordinate agents:\n\n```bash\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's/agent_name: *//')\nCOORDINATOR=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')\n\n# Send notification to coordinator\ntmux send-keys -t \"$COORDINATOR\" \"Agent $AGENT_NAME completed task\" Enter\n```\n\n### Pattern 3: Configuration-Driven Behavior\n\n**.claude/my-plugin.local.md:**\n```markdown\n---\nvalidation_level: strict\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\n---\n\n# Validation Configuration\n\nStrict mode enabled for this project.\nAll writes validated against security policies.\n```\n\nUse in hooks or commands:\n\n```bash\nLEVEL=$(echo \"$FRONTMATTER\" | grep '^validation_level:' | sed 's/validation_level: *//')\n\ncase \"$LEVEL\" in\n strict)\n # Apply strict validation\n ;;\n standard)\n # Apply standard validation\n ;;\n lenient)\n # Apply lenient validation\n ;;\nesac\n```\n\n## Creating Settings Files\n\n### From Commands\n\nCommands can create settings files:\n\n```markdown\n# Setup Command\n\nSteps:\n1. Ask user for configuration preferences\n2. Create `.claude/my-plugin.local.md` with YAML frontmatter\n3. Set appropriate values based on user input\n4. Inform user that settings are saved\n5. Remind user to restart Claude Code for hooks to recognize changes\n```\n\n### Template Generation\n\nProvide template in plugin README:\n\n```markdown\n## Configuration\n\nCreate `.claude/my-plugin.local.md` in your project:\n\n\\`\\`\\`markdown\n---\nenabled: true\nmode: standard\nmax_retries: 3\n---\n\n# Plugin Configuration\n\nYour settings are active.\n\\`\\`\\`\n\nAfter creating or editing, restart Claude Code for changes to take effect.\n```\n\n## Best Practices\n\n### File Naming\n\n✅ **DO:**\n- Use `.claude/plugin-name.local.md` format\n- Match plugin name exactly\n- Use `.local.md` suffix for user-local files\n\n❌ **DON'T:**\n- Use different directory (not `.claude/`)\n- Use inconsistent naming\n- Use `.md` without `.local` (might be committed)\n\n### Gitignore\n\nAlways add to `.gitignore`:\n\n```gitignore\n.claude/*.local.md\n.claude/*.local.json\n```\n\nDocument this in plugin README.\n\n### Defaults\n\nProvide sensible defaults when settings file doesn't exist:\n\n```bash\nif [[ ! -f \"$STATE_FILE\" ]]; then\n # Use defaults\n ENABLED=true\n MODE=standard\nelse\n # Read from file\n # ...\nfi\n```\n\n### Validation\n\nValidate settings values:\n\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n\n# Validate numeric range\nif ! [[ \"$MAX\" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then\n echo \"⚠️ Invalid max_value in settings (must be 1-100)\" >&2\n MAX=10 # Use default\nfi\n```\n\n### Restart Requirement\n\n**Important:** Settings changes require Claude Code restart.\n\nDocument in your README:\n\n```markdown\n## Changing Settings\n\nAfter editing `.claude/my-plugin.local.md`:\n1. Save the file\n2. Exit Claude Code\n3. Restart: `claude` or `cc`\n4. New settings will be loaded\n```\n\nHooks cannot be hot-swapped within a session.\n\n## Security Considerations\n\n### Sanitize User Input\n\nWhen writing settings files from user input:\n\n```bash\n# Escape quotes in user input\nSAFE_VALUE=$(echo \"$USER_INPUT\" | sed 's/\"/\\\\\"/g')\n\n# Write to file\ncat > \"$STATE_FILE\" <&2\n exit 2\nfi\n```\n\n### Permissions\n\nSettings files should be:\n- Readable by user only (`chmod 600`)\n- Not committed to git\n- Not shared between users\n\n## Real-World Examples\n\n### multi-agent-swarm Plugin\n\n**.claude/multi-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: Use JWT tokens, not sessions\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\nCoordinate with auth-agent on shared types.\n```\n\n**Hook usage (agent-stop-notification.sh):**\n- Checks if file exists (line 15-18: quick exit if not)\n- Parses frontmatter to get coordinator_session, agent_name, enabled\n- Sends notifications to coordinator if enabled\n- Allows quick activation/deactivation via `enabled: true/false`\n\n### ralph-wiggum Plugin\n\n**.claude/ralph-loop.local.md:**\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\n```\n\n**Hook usage (stop-hook.sh):**\n- Checks if file exists (line 15-18: quick exit if not active)\n- Reads iteration count and max_iterations\n- Extracts completion_promise for loop termination\n- Reads body as the prompt to feed back\n- Updates iteration count on each loop\n\n## Quick Reference\n\n### File Location\n\n```\nproject-root/\n└── .claude/\n └── plugin-name.local.md\n```\n\n### Frontmatter Parsing\n\n```bash\n# Extract frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Read field\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n### Body Parsing\n\n```bash\n# Extract body (after second ---)\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n### Quick Exit Pattern\n\n```bash\nif [[ ! -f \".claude/my-plugin.local.md\" ]]; then\n exit 0 # Not configured\nfi\n```\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed implementation patterns:\n\n- **`references/parsing-techniques.md`** - Complete guide to parsing YAML frontmatter and markdown bodies\n- **`references/real-world-examples.md`** - Deep dive into multi-agent-swarm and ralph-wiggum implementations\n\n### Example Files\n\nWorking examples in `examples/`:\n\n- **`read-settings-hook.sh`** - Hook that reads and uses settings\n- **`create-settings-command.md`** - Command that creates settings file\n- **`example-settings.md`** - Template settings file\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-settings.sh`** - Validate settings file structure\n- **`parse-frontmatter.sh`** - Extract frontmatter fields\n\n## Implementation Workflow\n\nTo add settings to a plugin:\n\n1. Design settings schema (which fields, types, defaults)\n2. Create template file in plugin documentation\n3. Add gitignore entry for `.claude/*.local.md`\n4. Implement settings parsing in hooks/commands\n5. Use quick-exit pattern (check file exists, check enabled field)\n6. Document settings in plugin README with template\n7. Remind users that changes require Claude Code restart\n\nFocus on keeping settings simple and providing good defaults when settings file doesn't exist.\n","plugins/plugin-dev/skills/plugin-settings/examples/create-settings-command.md":"---\ndescription: \"Create plugin settings file with user preferences\"\nallowed-tools: [\"Write\", \"AskUserQuestion\"]\n---\n\n# Create Plugin Settings\n\nThis command helps users create a `.claude/my-plugin.local.md` settings file.\n\n## Steps\n\n### Step 1: Ask User for Preferences\n\nUse AskUserQuestion to gather configuration:\n\n```json\n{\n \"questions\": [\n {\n \"question\": \"Enable plugin for this project?\",\n \"header\": \"Enable Plugin\",\n \"multiSelect\": false,\n \"options\": [\n {\n \"label\": \"Yes\",\n \"description\": \"Plugin will be active\"\n },\n {\n \"label\": \"No\",\n \"description\": \"Plugin will be disabled\"\n }\n ]\n },\n {\n \"question\": \"Validation mode?\",\n \"header\": \"Mode\",\n \"multiSelect\": false,\n \"options\": [\n {\n \"label\": \"Strict\",\n \"description\": \"Maximum validation and security checks\"\n },\n {\n \"label\": \"Standard\",\n \"description\": \"Balanced validation (recommended)\"\n },\n {\n \"label\": \"Lenient\",\n \"description\": \"Minimal validation only\"\n }\n ]\n }\n ]\n}\n```\n\n### Step 2: Parse Answers\n\nExtract answers from AskUserQuestion result:\n\n- answers[\"0\"]: enabled (Yes/No)\n- answers[\"1\"]: mode (Strict/Standard/Lenient)\n\n### Step 3: Create Settings File\n\nUse Write tool to create `.claude/my-plugin.local.md`:\n\n```markdown\n---\nenabled: \nvalidation_mode: \nmax_file_size: 1000000\nnotify_on_errors: true\n---\n\n# Plugin Configuration\n\nYour plugin is configured with validation mode.\n\nTo modify settings, edit this file and restart Claude Code.\n```\n\n### Step 4: Inform User\n\nTell the user:\n- Settings file created at `.claude/my-plugin.local.md`\n- Current configuration summary\n- How to edit manually if needed\n- Reminder: Restart Claude Code for changes to take effect\n- Settings file is gitignored (won't be committed)\n\n## Implementation Notes\n\nAlways validate user input before writing:\n- Check mode is valid\n- Validate numeric fields are numbers\n- Ensure paths don't have traversal attempts\n- Sanitize any free-text fields\n","plugins/plugin-dev/skills/plugin-settings/examples/example-settings.md":"# Example Plugin Settings File\n\n## Template: Basic Configuration\n\n**.claude/my-plugin.local.md:**\n\n```markdown\n---\nenabled: true\nmode: standard\n---\n\n# My Plugin Configuration\n\nPlugin is active in standard mode.\n```\n\n## Template: Advanced Configuration\n\n**.claude/my-plugin.local.md:**\n\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\nnotification_level: info\nretry_attempts: 3\ntimeout_seconds: 60\ncustom_path: \"/path/to/data\"\n---\n\n# My Plugin Advanced Configuration\n\nThis project uses custom plugin configuration with:\n- Standard validation mode\n- 1MB file size limit\n- JavaScript/TypeScript files allowed\n- Info-level logging\n- 3 retry attempts\n\n## Additional Notes\n\nContact @team-lead with questions about this configuration.\n```\n\n## Template: Agent State File\n\n**.claude/multi-agent-swarm.local.md:**\n\n```markdown\n---\nagent_name: database-implementation\ntask_number: 4.2\npr_number: 5678\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.5\", \"Task 4.1\"]\nadditional_instructions: \"Use PostgreSQL, not MySQL\"\n---\n\n# Task Assignment: Database Schema Implementation\n\nImplement the database schema for the new features module.\n\n## Requirements\n\n- Create migration files\n- Add indexes for performance\n- Write tests for constraints\n- Document schema in README\n\n## Success Criteria\n\n- Migrations run successfully\n- All tests pass\n- PR created with CI green\n- Schema documented\n\n## Coordination\n\nDepends on:\n- Task 3.5: API endpoint definitions\n- Task 4.1: Data model design\n\nReport status to coordinator session 'team-leader'.\n```\n\n## Template: Feature Flag Pattern\n\n**.claude/experimental-features.local.md:**\n\n```markdown\n---\nenabled: true\nfeatures:\n - ai_suggestions\n - auto_formatting\n - advanced_refactoring\nexperimental_mode: false\n---\n\n# Experimental Features Configuration\n\nCurrent enabled features:\n- AI-powered code suggestions\n- Automatic code formatting\n- Advanced refactoring tools\n\nExperimental mode is OFF (stable features only).\n```\n\n## Usage in Hooks\n\nThese templates can be read by hooks:\n\n```bash\n# Check if plugin is configured\nif [[ ! -f \".claude/my-plugin.local.md\" ]]; then\n exit 0 # Not configured, skip hook\nfi\n\n# Read settings\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \".claude/my-plugin.local.md\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Apply settings\nif [[ \"$ENABLED\" == \"true\" ]]; then\n # Hook is active\n # ...\nfi\n```\n\n## Gitignore\n\nAlways add to project `.gitignore`:\n\n```gitignore\n# Plugin settings (user-local, not committed)\n.claude/*.local.md\n.claude/*.local.json\n```\n\n## Editing Settings\n\nUsers can edit settings files manually:\n\n```bash\n# Edit settings\nvim .claude/my-plugin.local.md\n\n# Changes take effect after restart\nexit # Exit Claude Code\nclaude # Restart\n```\n\nChanges require Claude Code restart - hooks can't be hot-swapped.\n","plugins/plugin-dev/skills/plugin-settings/references/parsing-techniques.md":"# Settings File Parsing Techniques\n\nComplete guide to parsing `.claude/plugin-name.local.md` files in bash scripts.\n\n## File Structure\n\nSettings files use markdown with YAML frontmatter:\n\n```markdown\n---\nfield1: value1\nfield2: \"value with spaces\"\nnumeric_field: 42\nboolean_field: true\nlist_field: [\"item1\", \"item2\", \"item3\"]\n---\n\n# Markdown Content\n\nThis body content can be extracted separately.\nIt's useful for prompts, documentation, or additional context.\n```\n\n## Parsing Frontmatter\n\n### Extract Frontmatter Block\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\n\n# Extract everything between --- markers (excluding the markers themselves)\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n```\n\n**How it works:**\n- `sed -n` - Suppress automatic printing\n- `/^---$/,/^---$/` - Range from first `---` to second `---`\n- `{ /^---$/d; p; }` - Delete the `---` lines, print everything else\n\n### Extract Individual Fields\n\n**String fields:**\n```bash\n# Simple value\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//')\n\n# Quoted value (removes surrounding quotes)\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Use in condition\nif [[ \"$ENABLED\" == \"true\" ]]; then\n # Enabled\nfi\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n\n# Validate it's a number\nif [[ \"$MAX\" =~ ^[0-9]+$ ]]; then\n # Use in numeric comparison\n if [[ $MAX -gt 100 ]]; then\n # Too large\n fi\nfi\n```\n\n**List fields (simple):**\n```bash\n# YAML: list: [\"item1\", \"item2\", \"item3\"]\nLIST=$(echo \"$FRONTMATTER\" | grep '^list:' | sed 's/list: *//')\n# Result: [\"item1\", \"item2\", \"item3\"]\n\n# For simple checks:\nif [[ \"$LIST\" == *\"item1\"* ]]; then\n # List contains item1\nfi\n```\n\n**List fields (proper parsing with jq):**\n```bash\n# For proper list handling, use yq or convert to JSON\n# This requires yq to be installed (brew install yq)\n\n# Extract list as JSON array\nLIST=$(echo \"$FRONTMATTER\" | yq -o json '.list' 2>/dev/null)\n\n# Iterate over items\necho \"$LIST\" | jq -r '.[]' | while read -r item; do\n echo \"Processing: $item\"\ndone\n```\n\n## Parsing Markdown Body\n\n### Extract Body Content\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\n\n# Extract everything after the closing ---\n# Counts --- markers: first is opening, second is closing, everything after is body\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n**How it works:**\n- `/^---$/` - Match `---` lines\n- `{i++; next}` - Increment counter and skip the `---` line\n- `i>=2` - Print all lines after second `---`\n\n**Handles edge case:** If `---` appears in the markdown body, it still works because we only count the first two `---` at the start.\n\n### Use Body as Prompt\n\n```bash\n# Extract body\nPROMPT=$(awk '/^---$/{i++; next} i>=2' \"$RALPH_STATE_FILE\")\n\n# Feed back to Claude\necho '{\"decision\": \"block\", \"reason\": \"'\"$PROMPT\"'\"}' | jq .\n```\n\n**Important:** Use `jq -n --arg` for safer JSON construction with user content:\n\n```bash\nPROMPT=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n\n# Safe JSON construction\njq -n --arg prompt \"$PROMPT\" '{\n \"decision\": \"block\",\n \"reason\": $prompt\n}'\n```\n\n## Common Parsing Patterns\n\n### Pattern: Field with Default\n\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Use default if empty\nif [[ -z \"$VALUE\" ]]; then\n VALUE=\"default_value\"\nfi\n```\n\n### Pattern: Optional Field\n\n```bash\nOPTIONAL=$(echo \"$FRONTMATTER\" | grep '^optional_field:' | sed 's/optional_field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Only use if present\nif [[ -n \"$OPTIONAL\" ]] && [[ \"$OPTIONAL\" != \"null\" ]]; then\n # Field is set, use it\n echo \"Optional field: $OPTIONAL\"\nfi\n```\n\n### Pattern: Multiple Fields at Once\n\n```bash\n# Parse all fields in one pass\nwhile IFS=': ' read -r key value; do\n # Remove quotes if present\n value=$(echo \"$value\" | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n case \"$key\" in\n enabled)\n ENABLED=\"$value\"\n ;;\n mode)\n MODE=\"$value\"\n ;;\n max_size)\n MAX_SIZE=\"$value\"\n ;;\n esac\ndone <<< \"$FRONTMATTER\"\n```\n\n## Updating Settings Files\n\n### Atomic Updates\n\nAlways use temp file + atomic move to prevent corruption:\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\nNEW_VALUE=\"updated_value\"\n\n# Create temp file\nTEMP_FILE=\"${FILE}.tmp.$$\"\n\n# Update field using sed\nsed \"s/^field_name: .*/field_name: $NEW_VALUE/\" \"$FILE\" > \"$TEMP_FILE\"\n\n# Atomic replace\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### Update Single Field\n\n```bash\n# Increment iteration counter\nCURRENT=$(echo \"$FRONTMATTER\" | grep '^iteration:' | sed 's/iteration: *//')\nNEXT=$((CURRENT + 1))\n\n# Update file\nTEMP_FILE=\"${FILE}.tmp.$$\"\nsed \"s/^iteration: .*/iteration: $NEXT/\" \"$FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### Update Multiple Fields\n\n```bash\n# Update several fields at once\nTEMP_FILE=\"${FILE}.tmp.$$\"\n\nsed -e \"s/^iteration: .*/iteration: $NEXT_ITERATION/\" \\\n -e \"s/^pr_number: .*/pr_number: $PR_NUMBER/\" \\\n -e \"s/^status: .*/status: $NEW_STATUS/\" \\\n \"$FILE\" > \"$TEMP_FILE\"\n\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n## Validation Techniques\n\n### Validate File Exists and Is Readable\n\n```bash\nFILE=\".claude/my-plugin.local.md\"\n\nif [[ ! -f \"$FILE\" ]]; then\n echo \"Settings file not found\" >&2\n exit 1\nfi\n\nif [[ ! -r \"$FILE\" ]]; then\n echo \"Settings file not readable\" >&2\n exit 1\nfi\n```\n\n### Validate Frontmatter Structure\n\n```bash\n# Count --- markers (should be exactly 2 at start)\nMARKER_COUNT=$(grep -c '^---$' \"$FILE\" 2>/dev/null || echo \"0\")\n\nif [[ $MARKER_COUNT -lt 2 ]]; then\n echo \"Invalid settings file: missing frontmatter markers\" >&2\n exit 1\nfi\n```\n\n### Validate Field Values\n\n```bash\nMODE=$(echo \"$FRONTMATTER\" | grep '^mode:' | sed 's/mode: *//')\n\ncase \"$MODE\" in\n strict|standard|lenient)\n # Valid mode\n ;;\n *)\n echo \"Invalid mode: $MODE (must be strict, standard, or lenient)\" >&2\n exit 1\n ;;\nesac\n```\n\n### Validate Numeric Ranges\n\n```bash\nMAX_SIZE=$(echo \"$FRONTMATTER\" | grep '^max_size:' | sed 's/max_size: *//')\n\nif ! [[ \"$MAX_SIZE\" =~ ^[0-9]+$ ]]; then\n echo \"max_size must be a number\" >&2\n exit 1\nfi\n\nif [[ $MAX_SIZE -lt 1 ]] || [[ $MAX_SIZE -gt 10000000 ]]; then\n echo \"max_size out of range (1-10000000)\" >&2\n exit 1\nfi\n```\n\n## Edge Cases and Gotchas\n\n### Quotes in Values\n\nYAML allows both quoted and unquoted strings:\n\n```yaml\n# These are equivalent:\nfield1: value\nfield2: \"value\"\nfield3: 'value'\n```\n\n**Handle both:**\n```bash\n# Remove surrounding quotes if present\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/' | sed \"s/^'\\\\(.*\\\\)'$/\\\\1/\")\n```\n\n### --- in Markdown Body\n\nIf the markdown body contains `---`, the parsing still works because we only match the first two:\n\n```markdown\n---\nfield: value\n---\n\n# Body\n\nHere's a separator:\n---\n\nMore content after the separator.\n```\n\nThe `awk '/^---$/{i++; next} i>=2'` pattern handles this correctly.\n\n### Empty Values\n\nHandle missing or empty fields:\n\n```yaml\nfield1:\nfield2: \"\"\nfield3: null\n```\n\n**Parsing:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field1:' | sed 's/field1: *//')\n# VALUE will be empty string\n\n# Check for empty/null\nif [[ -z \"$VALUE\" ]] || [[ \"$VALUE\" == \"null\" ]]; then\n VALUE=\"default\"\nfi\n```\n\n### Special Characters\n\nValues with special characters need careful handling:\n\n```yaml\nmessage: \"Error: Something went wrong!\"\npath: \"/path/with spaces/file.txt\"\nregex: \"^[a-zA-Z0-9_]+$\"\n```\n\n**Safe parsing:**\n```bash\n# Always quote variables when using\nMESSAGE=$(echo \"$FRONTMATTER\" | grep '^message:' | sed 's/message: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\necho \"Message: $MESSAGE\" # Quoted!\n```\n\n## Performance Optimization\n\n### Cache Parsed Values\n\nIf reading settings multiple times:\n\n```bash\n# Parse once\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Extract multiple fields from cached frontmatter\nFIELD1=$(echo \"$FRONTMATTER\" | grep '^field1:' | sed 's/field1: *//')\nFIELD2=$(echo \"$FRONTMATTER\" | grep '^field2:' | sed 's/field2: *//')\nFIELD3=$(echo \"$FRONTMATTER\" | grep '^field3:' | sed 's/field3: *//')\n```\n\n**Don't:** Re-parse file for each field.\n\n### Lazy Loading\n\nOnly parse settings when needed:\n\n```bash\n#!/bin/bash\ninput=$(cat)\n\n# Quick checks first (no file I/O)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\nif [[ \"$tool_name\" != \"Write\" ]]; then\n exit 0 # Not a write operation, skip\nfi\n\n# Only now check settings file\nif [[ -f \".claude/my-plugin.local.md\" ]]; then\n # Parse settings\n # ...\nfi\n```\n\n## Debugging\n\n### Print Parsed Values\n\n```bash\n#!/bin/bash\nset -x # Enable debug tracing\n\nFILE=\".claude/my-plugin.local.md\"\n\nif [[ -f \"$FILE\" ]]; then\n echo \"Settings file found\" >&2\n\n FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n echo \"Frontmatter:\" >&2\n echo \"$FRONTMATTER\" >&2\n\n ENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n echo \"Enabled: $ENABLED\" >&2\nfi\n```\n\n### Validate Parsing\n\n```bash\n# Show what was parsed\necho \"Parsed values:\" >&2\necho \" enabled: $ENABLED\" >&2\necho \" mode: $MODE\" >&2\necho \" max_size: $MAX_SIZE\" >&2\n\n# Verify expected values\nif [[ \"$ENABLED\" != \"true\" ]] && [[ \"$ENABLED\" != \"false\" ]]; then\n echo \"⚠️ Unexpected enabled value: $ENABLED\" >&2\nfi\n```\n\n## Alternative: Using yq\n\nFor complex YAML, consider using `yq`:\n\n```bash\n# Install: brew install yq\n\n# Parse YAML properly\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Extract fields with yq\nENABLED=$(echo \"$FRONTMATTER\" | yq '.enabled')\nMODE=$(echo \"$FRONTMATTER\" | yq '.mode')\nLIST=$(echo \"$FRONTMATTER\" | yq -o json '.list_field')\n\n# Iterate list properly\necho \"$LIST\" | jq -r '.[]' | while read -r item; do\n echo \"Item: $item\"\ndone\n```\n\n**Pros:**\n- Proper YAML parsing\n- Handles complex structures\n- Better list/object support\n\n**Cons:**\n- Requires yq installation\n- Additional dependency\n- May not be available on all systems\n\n**Recommendation:** Use sed/grep for simple fields, yq for complex structures.\n\n## Complete Example\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Configuration\nSETTINGS_FILE=\".claude/my-plugin.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$SETTINGS_FILE\" ]]; then\n # Use defaults\n ENABLED=true\n MODE=standard\n MAX_SIZE=1000000\nelse\n # Parse frontmatter\n FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$SETTINGS_FILE\")\n\n # Extract fields with defaults\n ENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n ENABLED=${ENABLED:-true}\n\n MODE=$(echo \"$FRONTMATTER\" | grep '^mode:' | sed 's/mode: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n MODE=${MODE:-standard}\n\n MAX_SIZE=$(echo \"$FRONTMATTER\" | grep '^max_size:' | sed 's/max_size: *//')\n MAX_SIZE=${MAX_SIZE:-1000000}\n\n # Validate values\n if [[ \"$ENABLED\" != \"true\" ]] && [[ \"$ENABLED\" != \"false\" ]]; then\n echo \"⚠️ Invalid enabled value, using default\" >&2\n ENABLED=true\n fi\n\n if ! [[ \"$MAX_SIZE\" =~ ^[0-9]+$ ]]; then\n echo \"⚠️ Invalid max_size, using default\" >&2\n MAX_SIZE=1000000\n fi\nfi\n\n# Quick exit if disabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0\nfi\n\n# Use configuration\necho \"Configuration loaded: mode=$MODE, max_size=$MAX_SIZE\" >&2\n\n# Apply logic based on settings\ncase \"$MODE\" in\n strict)\n # Strict validation\n ;;\n standard)\n # Standard validation\n ;;\n lenient)\n # Lenient validation\n ;;\nesac\n```\n\nThis provides robust settings handling with defaults, validation, and error recovery.\n","plugins/plugin-dev/skills/plugin-settings/references/real-world-examples.md":"# Real-World Plugin Settings Examples\n\nDetailed analysis of how production plugins use the `.claude/plugin-name.local.md` pattern.\n\n## multi-agent-swarm Plugin\n\n### Settings File Structure\n\n**.claude/multi-agent-swarm.local.md:**\n\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: \"Use JWT tokens, not sessions\"\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\n\n## Requirements\n- JWT token generation and validation\n- Refresh token flow\n- Secure password hashing\n\n## Success Criteria\n- Auth endpoints implemented\n- Tests passing (100% coverage)\n- PR created and CI green\n- Documentation updated\n\n## Coordination\nDepends on Task 3.4 (user model).\nReport status to 'team-leader' session.\n```\n\n### How It's Used\n\n**File:** `hooks/agent-stop-notification.sh`\n\n**Purpose:** Send notifications to coordinator when agent becomes idle\n\n**Implementation:**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nSWARM_STATE_FILE=\".claude/multi-agent-swarm.local.md\"\n\n# Quick exit if no swarm active\nif [[ ! -f \"$SWARM_STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Parse frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$SWARM_STATE_FILE\")\n\n# Extract configuration\nCOORDINATOR_SESSION=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's/coordinator_session: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's/agent_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nTASK_NUMBER=$(echo \"$FRONTMATTER\" | grep '^task_number:' | sed 's/task_number: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nPR_NUMBER=$(echo \"$FRONTMATTER\" | grep '^pr_number:' | sed 's/pr_number: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0\nfi\n\n# Send notification to coordinator\nNOTIFICATION=\"🤖 Agent ${AGENT_NAME} (Task ${TASK_NUMBER}, PR #${PR_NUMBER}) is idle.\"\n\nif tmux has-session -t \"$COORDINATOR_SESSION\" 2>/dev/null; then\n tmux send-keys -t \"$COORDINATOR_SESSION\" \"$NOTIFICATION\" Enter\n sleep 0.5\n tmux send-keys -t \"$COORDINATOR_SESSION\" Enter\nfi\n\nexit 0\n```\n\n**Key patterns:**\n1. **Quick exit** (line 7-9): Returns immediately if file doesn't exist\n2. **Field extraction** (lines 11-17): Parses each frontmatter field\n3. **Enabled check** (lines 19-21): Respects enabled flag\n4. **Action based on settings** (lines 23-29): Uses coordinator_session to send notification\n\n### Creation\n\n**File:** `commands/launch-swarm.md`\n\nSettings files are created during swarm launch with:\n\n```bash\ncat > \"$WORKTREE_PATH/.claude/multi-agent-swarm.local.md\" < temp.md\nmv temp.md \".claude/multi-agent-swarm.local.md\"\n```\n\n## ralph-wiggum Plugin\n\n### Settings File Structure\n\n**.claude/ralph-loop.local.md:**\n\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\nstarted_at: \"2025-01-15T14:30:00Z\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\nDocument any changes needed in CLAUDE.md.\n```\n\n### How It's Used\n\n**File:** `hooks/stop-hook.sh`\n\n**Purpose:** Prevent session exit and loop Claude's output back as input\n\n**Implementation:**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nRALPH_STATE_FILE=\".claude/ralph-loop.local.md\"\n\n# Quick exit if no active loop\nif [[ ! -f \"$RALPH_STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Parse frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$RALPH_STATE_FILE\")\n\n# Extract configuration\nITERATION=$(echo \"$FRONTMATTER\" | grep '^iteration:' | sed 's/iteration: *//')\nMAX_ITERATIONS=$(echo \"$FRONTMATTER\" | grep '^max_iterations:' | sed 's/max_iterations: *//')\nCOMPLETION_PROMISE=$(echo \"$FRONTMATTER\" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Check max iterations\nif [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then\n echo \"🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached.\"\n rm \"$RALPH_STATE_FILE\"\n exit 0\nfi\n\n# Get transcript and check for completion promise\nTRANSCRIPT_PATH=$(echo \"$HOOK_INPUT\" | jq -r '.transcript_path')\nLAST_OUTPUT=$(grep '\"role\":\"assistant\"' \"$TRANSCRIPT_PATH\" | tail -1 | jq -r '.message.content | map(select(.type == \"text\")) | map(.text) | join(\"\\n\")')\n\n# Check for completion\nif [[ \"$COMPLETION_PROMISE\" != \"null\" ]] && [[ -n \"$COMPLETION_PROMISE\" ]]; then\n PROMISE_TEXT=$(echo \"$LAST_OUTPUT\" | perl -0777 -pe 's/.*?(.*?)<\\/promise>.*/$1/s; s/^\\s+|\\s+$//g')\n\n if [[ \"$PROMISE_TEXT\" = \"$COMPLETION_PROMISE\" ]]; then\n echo \"✅ Ralph loop: Detected completion\"\n rm \"$RALPH_STATE_FILE\"\n exit 0\n fi\nfi\n\n# Continue loop - increment iteration\nNEXT_ITERATION=$((ITERATION + 1))\n\n# Extract prompt from markdown body\nPROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' \"$RALPH_STATE_FILE\")\n\n# Update iteration counter\nTEMP_FILE=\"${RALPH_STATE_FILE}.tmp.$$\"\nsed \"s/^iteration: .*/iteration: $NEXT_ITERATION/\" \"$RALPH_STATE_FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$RALPH_STATE_FILE\"\n\n# Block exit and feed prompt back\njq -n \\\n --arg prompt \"$PROMPT_TEXT\" \\\n --arg msg \"🔄 Ralph iteration $NEXT_ITERATION\" \\\n '{\n \"decision\": \"block\",\n \"reason\": $prompt,\n \"systemMessage\": $msg\n }'\n\nexit 0\n```\n\n**Key patterns:**\n1. **Quick exit** (line 7-9): Skip if not active\n2. **Iteration tracking** (lines 11-20): Count and enforce max iterations\n3. **Promise detection** (lines 25-33): Check for completion signal in output\n4. **Prompt extraction** (line 38): Read markdown body as next prompt\n5. **State update** (lines 40-43): Increment iteration atomically\n6. **Loop continuation** (lines 45-53): Block exit and feed prompt back\n\n### Creation\n\n**File:** `scripts/setup-ralph-loop.sh`\n\n```bash\n#!/bin/bash\nPROMPT=\"$1\"\nMAX_ITERATIONS=\"${2:-0}\"\nCOMPLETION_PROMISE=\"${3:-}\"\n\n# Create state file\ncat > \".claude/ralph-loop.local.md\" < \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n**Why:** Prevents corruption if process is interrupted.\n\n### 4. Quote Handling\n\nBoth strip surrounding quotes from YAML values:\n\n```bash\nsed 's/^\"\\(.*\\)\"$/\\1/'\n```\n\n**Why:** YAML allows both `field: value` and `field: \"value\"`.\n\n### 5. Error Handling\n\nBoth handle missing/corrupt files gracefully:\n\n```bash\nif [[ ! -f \"$FILE\" ]]; then\n exit 0 # No error, just not configured\nfi\n\nif [[ -z \"$CRITICAL_FIELD\" ]]; then\n echo \"Settings file corrupt\" >&2\n rm \"$FILE\" # Clean up\n exit 0\nfi\n```\n\n**Why:** Fails gracefully instead of crashing.\n\n## Anti-Patterns to Avoid\n\n### ❌ Hardcoded Paths\n\n```bash\n# BAD\nFILE=\"/Users/alice/.claude/my-plugin.local.md\"\n\n# GOOD\nFILE=\".claude/my-plugin.local.md\"\n```\n\n### ❌ Unquoted Variables\n\n```bash\n# BAD\necho $VALUE\n\n# GOOD\necho \"$VALUE\"\n```\n\n### ❌ Non-Atomic Updates\n\n```bash\n# BAD: Can corrupt file if interrupted\nsed -i \"s/field: .*/field: $VALUE/\" \"$FILE\"\n\n# GOOD: Atomic\nTEMP_FILE=\"${FILE}.tmp.$$\"\nsed \"s/field: .*/field: $VALUE/\" \"$FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### ❌ No Default Values\n\n```bash\n# BAD: Fails if field missing\nif [[ $MAX -gt 100 ]]; then\n # MAX might be empty!\nfi\n\n# GOOD: Provide default\nMAX=${MAX:-10}\n```\n\n### ❌ Ignoring Edge Cases\n\n```bash\n# BAD: Assumes exactly 2 --- markers\nsed -n '/^---$/,/^---$/{ /^---$/d; p; }'\n\n# GOOD: Handles --- in body\nawk '/^---$/{i++; next} i>=2' # For body\n```\n\n## Conclusion\n\nThe `.claude/plugin-name.local.md` pattern provides:\n- Simple, human-readable configuration\n- Version-control friendly (gitignored)\n- Per-project settings\n- Easy parsing with standard bash tools\n- Supports both structured config (YAML) and freeform content (markdown)\n\nUse this pattern for any plugin that needs user-configurable behavior or state persistence.\n","plugins/plugin-dev/skills/plugin-structure/README.md":"","plugins/plugin-dev/skills/plugin-structure/SKILL.md":"---\nname: Plugin Structure\ndescription: This skill should be used when the user asks to \"create a plugin\", \"scaffold a plugin\", \"understand plugin structure\", \"organize plugin components\", \"set up plugin.json\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"add commands/agents/skills/hooks\", \"configure auto-discovery\", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.\nversion: 0.1.0\n---\n\n# Plugin Structure for Claude Code\n\n## Overview\n\nClaude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.\n\n**Key concepts:**\n- Conventional directory layout for automatic discovery\n- Manifest-driven configuration in `.claude-plugin/plugin.json`\n- Component-based organization (commands, agents, skills, hooks)\n- Portable path references using `${CLAUDE_PLUGIN_ROOT}`\n- Explicit vs. auto-discovered component loading\n\n## Directory Structure\n\nEvery Claude Code plugin follows this organizational pattern:\n\n```\nplugin-name/\n├── .claude-plugin/\n│ └── plugin.json # Required: Plugin manifest\n├── commands/ # Slash commands (.md files)\n├── agents/ # Subagent definitions (.md files)\n├── skills/ # Agent skills (subdirectories)\n│ └── skill-name/\n│ └── SKILL.md # Required for each skill\n├── hooks/\n│ └── hooks.json # Event handler configuration\n├── .mcp.json # MCP server definitions\n└── scripts/ # Helper scripts and utilities\n```\n\n**Critical rules:**\n\n1. **Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory\n2. **Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`\n3. **Optional components**: Only create directories for components the plugin actually uses\n4. **Naming convention**: Use kebab-case for all directory and file names\n\n## Plugin Manifest (plugin.json)\n\nThe manifest defines plugin metadata and configuration. Located at `.claude-plugin/plugin.json`:\n\n### Required Fields\n\n```json\n{\n \"name\": \"plugin-name\"\n}\n```\n\n**Name requirements:**\n- Use kebab-case format (lowercase with hyphens)\n- Must be unique across installed plugins\n- No spaces or special characters\n- Example: `code-review-assistant`, `test-runner`, `api-docs`\n\n### Recommended Metadata\n\n```json\n{\n \"name\": \"plugin-name\",\n \"version\": \"1.0.0\",\n \"description\": \"Brief explanation of plugin purpose\",\n \"author\": {\n \"name\": \"Author Name\",\n \"email\": \"author@example.com\",\n \"url\": \"https://example.com\"\n },\n \"homepage\": \"https://docs.example.com\",\n \"repository\": \"https://github.com/user/plugin-name\",\n \"license\": \"MIT\",\n \"keywords\": [\"testing\", \"automation\", \"ci-cd\"]\n}\n```\n\n**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)\n**Keywords**: Use for plugin discovery and categorization\n\n### Component Path Configuration\n\nSpecify custom paths for components (supplements default directories):\n\n```json\n{\n \"name\": \"plugin-name\",\n \"commands\": \"./custom-commands\",\n \"agents\": [\"./agents\", \"./specialized-agents\"],\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.\n\n**Path rules:**\n- Must be relative to plugin root\n- Must start with `./`\n- Cannot use absolute paths\n- Support arrays for multiple locations\n\n## Component Organization\n\n### Commands\n\n**Location**: `commands/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `commands/` load automatically\n\n**Example structure**:\n```\ncommands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**File format**:\n```markdown\n---\nname: command-name\ndescription: Command description\n---\n\nCommand implementation instructions...\n```\n\n**Usage**: Commands integrate as native slash commands in Claude Code\n\n### Agents\n\n**Location**: `agents/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `agents/` load automatically\n\n**Example structure**:\n```\nagents/\n├── code-reviewer.md\n├── test-generator.md\n└── refactorer.md\n```\n\n**File format**:\n```markdown\n---\ndescription: Agent role and expertise\ncapabilities:\n - Specific task 1\n - Specific task 2\n---\n\nDetailed agent instructions and knowledge...\n```\n\n**Usage**: Users can invoke agents manually, or Claude Code selects them automatically based on task context\n\n### Skills\n\n**Location**: `skills/` directory with subdirectories per skill\n**Format**: Each skill in its own directory with `SKILL.md` file\n**Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically\n\n**Example structure**:\n```\nskills/\n├── api-testing/\n│ ├── SKILL.md\n│ ├── scripts/\n│ │ └── test-runner.py\n│ └── references/\n│ └── api-spec.md\n└── database-migrations/\n ├── SKILL.md\n └── examples/\n └── migration-template.sql\n```\n\n**SKILL.md format**:\n```markdown\n---\nname: Skill Name\ndescription: When to use this skill\nversion: 1.0.0\n---\n\nSkill instructions and guidance...\n```\n\n**Supporting files**: Skills can include scripts, references, examples, or assets in subdirectories\n\n**Usage**: Claude Code autonomously activates skills based on task context matching the description\n\n### Hooks\n\n**Location**: `hooks/hooks.json` or inline in `plugin.json`\n**Format**: JSON configuration defining event handlers\n**Registration**: Hooks register automatically when plugin enables\n\n**Example structure**:\n```\nhooks/\n├── hooks.json # Hook configuration\n└── scripts/\n ├── validate.sh # Hook script\n └── check-style.sh # Hook script\n```\n\n**Configuration format**:\n```json\n{\n \"PreToolUse\": [{\n \"matcher\": \"Write|Edit\",\n \"hooks\": [{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh\",\n \"timeout\": 30\n }]\n }]\n}\n```\n\n**Available events**: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification\n\n**Usage**: Hooks execute automatically in response to Claude Code events\n\n### MCP Servers\n\n**Location**: `.mcp.json` at plugin root or inline in `plugin.json`\n**Format**: JSON configuration for MCP server definitions\n**Auto-start**: Servers start automatically when plugin enables\n\n**Example format**:\n```json\n{\n \"mcpServers\": {\n \"server-name\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/server.js\"],\n \"env\": {\n \"API_KEY\": \"${API_KEY}\"\n }\n }\n }\n}\n```\n\n**Usage**: MCP servers integrate seamlessly with Claude Code's tool system\n\n## Portable Path References\n\n### ${CLAUDE_PLUGIN_ROOT}\n\nUse `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path references:\n\n```json\n{\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh\"\n}\n```\n\n**Why it matters**: Plugins install in different locations depending on:\n- User installation method (marketplace, local, npm)\n- Operating system conventions\n- User preferences\n\n**Where to use it**:\n- Hook command paths\n- MCP server command arguments\n- Script execution references\n- Resource file paths\n\n**Never use**:\n- Hardcoded absolute paths (`/Users/name/plugins/...`)\n- Relative paths from working directory (`./scripts/...` in commands)\n- Home directory shortcuts (`~/plugins/...`)\n\n### Path Resolution Rules\n\n**In manifest JSON fields** (hooks, MCP servers):\n```json\n\"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh\"\n```\n\n**In component files** (commands, agents, skills):\n```markdown\nReference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py\n```\n\n**In executed scripts**:\n```bash\n#!/bin/bash\n# ${CLAUDE_PLUGIN_ROOT} available as environment variable\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/common.sh\"\n```\n\n## File Naming Conventions\n\n### Component Files\n\n**Commands**: Use kebab-case `.md` files\n- `code-review.md` → `/code-review`\n- `run-tests.md` → `/run-tests`\n- `api-docs.md` → `/api-docs`\n\n**Agents**: Use kebab-case `.md` files describing role\n- `test-generator.md`\n- `code-reviewer.md`\n- `performance-analyzer.md`\n\n**Skills**: Use kebab-case directory names\n- `api-testing/`\n- `database-migrations/`\n- `error-handling/`\n\n### Supporting Files\n\n**Scripts**: Use descriptive kebab-case names with appropriate extensions\n- `validate-input.sh`\n- `generate-report.py`\n- `process-data.js`\n\n**Documentation**: Use kebab-case markdown files\n- `api-reference.md`\n- `migration-guide.md`\n- `best-practices.md`\n\n**Configuration**: Use standard names\n- `hooks.json`\n- `.mcp.json`\n- `plugin.json`\n\n## Auto-Discovery Mechanism\n\nClaude Code automatically discovers and loads components:\n\n1. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables\n2. **Commands**: Scans `commands/` directory for `.md` files\n3. **Agents**: Scans `agents/` directory for `.md` files\n4. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`\n5. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest\n6. **MCP servers**: Loads configuration from `.mcp.json` or manifest\n\n**Discovery timing**:\n- Plugin installation: Components register with Claude Code\n- Plugin enable: Components become available for use\n- No restart required: Changes take effect on next Claude Code session\n\n**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories\n\n## Best Practices\n\n### Organization\n\n1. **Logical grouping**: Group related components together\n - Put test-related commands, agents, and skills together\n - Create subdirectories in `scripts/` for different purposes\n\n2. **Minimal manifest**: Keep `plugin.json` lean\n - Only specify custom paths when necessary\n - Rely on auto-discovery for standard layouts\n - Use inline configuration only for simple cases\n\n3. **Documentation**: Include README files\n - Plugin root: Overall purpose and usage\n - Component directories: Specific guidance\n - Script directories: Usage and requirements\n\n### Naming\n\n1. **Consistency**: Use consistent naming across components\n - If command is `test-runner`, name related agent `test-runner-agent`\n - Match skill directory names to their purpose\n\n2. **Clarity**: Use descriptive names that indicate purpose\n - Good: `api-integration-testing/`, `code-quality-checker.md`\n - Avoid: `utils/`, `misc.md`, `temp.sh`\n\n3. **Length**: Balance brevity with clarity\n - Commands: 2-3 words (`review-pr`, `run-ci`)\n - Agents: Describe role clearly (`code-reviewer`, `test-generator`)\n - Skills: Topic-focused (`error-handling`, `api-design`)\n\n### Portability\n\n1. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths\n2. **Test on multiple systems**: Verify on macOS, Linux, Windows\n3. **Document dependencies**: List required tools and versions\n4. **Avoid system-specific features**: Use portable bash/Python constructs\n\n### Maintenance\n\n1. **Version consistently**: Update version in plugin.json for releases\n2. **Deprecate gracefully**: Mark old components clearly before removal\n3. **Document breaking changes**: Note changes affecting existing users\n4. **Test thoroughly**: Verify all components work after changes\n\n## Common Patterns\n\n### Minimal Plugin\n\nSingle command with no dependencies:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json # Just name field\n└── commands/\n └── hello.md # Single command\n```\n\n### Full-Featured Plugin\n\nComplete plugin with all component types:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/ # User-facing commands\n├── agents/ # Specialized subagents\n├── skills/ # Auto-activating skills\n├── hooks/ # Event handlers\n│ ├── hooks.json\n│ └── scripts/\n├── .mcp.json # External integrations\n└── scripts/ # Shared utilities\n```\n\n### Skill-Focused Plugin\n\nPlugin providing only skills:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n└── skills/\n ├── skill-one/\n │ └── SKILL.md\n └── skill-two/\n └── SKILL.md\n```\n\n## Troubleshooting\n\n**Component not loading**:\n- Verify file is in correct directory with correct extension\n- Check YAML frontmatter syntax (commands, agents, skills)\n- Ensure skill has `SKILL.md` (not `README.md` or other name)\n- Confirm plugin is enabled in Claude Code settings\n\n**Path resolution errors**:\n- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`\n- Verify paths are relative and start with `./` in manifest\n- Check that referenced files exist at specified paths\n- Test with `echo $CLAUDE_PLUGIN_ROOT` in hook scripts\n\n**Auto-discovery not working**:\n- Confirm directories are at plugin root (not in `.claude-plugin/`)\n- Check file naming follows conventions (kebab-case, correct extensions)\n- Verify custom paths in manifest are correct\n- Restart Claude Code to reload plugin configuration\n\n**Conflicts between plugins**:\n- Use unique, descriptive component names\n- Namespace commands with plugin name if needed\n- Document potential conflicts in plugin README\n- Consider command prefixes for related functionality\n\n---\n\nFor detailed examples and advanced patterns, see files in `references/` and `examples/` directories.\n","plugins/plugin-dev/skills/plugin-structure/examples/advanced-plugin.md":"# Advanced Plugin Example\n\nA complex, enterprise-grade plugin with MCP integration and advanced organization.\n\n## Directory Structure\n\n```\nenterprise-devops/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n│ ├── ci/\n│ │ ├── build.md\n│ │ ├── test.md\n│ │ └── deploy.md\n│ ├── monitoring/\n│ │ ├── status.md\n│ │ └── logs.md\n│ └── admin/\n│ ├── configure.md\n│ └── manage.md\n├── agents/\n│ ├── orchestration/\n│ │ ├── deployment-orchestrator.md\n│ │ └── rollback-manager.md\n│ └── specialized/\n│ ├── kubernetes-expert.md\n│ ├── terraform-expert.md\n│ └── security-auditor.md\n├── skills/\n│ ├── kubernetes-ops/\n│ │ ├── SKILL.md\n│ │ ├── references/\n│ │ │ ├── deployment-patterns.md\n│ │ │ ├── troubleshooting.md\n│ │ │ └── security.md\n│ │ ├── examples/\n│ │ │ ├── basic-deployment.yaml\n│ │ │ ├── stateful-set.yaml\n│ │ │ └── ingress-config.yaml\n│ │ └── scripts/\n│ │ ├── validate-manifest.sh\n│ │ └── health-check.sh\n│ ├── terraform-iac/\n│ │ ├── SKILL.md\n│ │ ├── references/\n│ │ │ └── best-practices.md\n│ │ └── examples/\n│ │ └── module-template/\n│ └── ci-cd-pipelines/\n│ ├── SKILL.md\n│ └── references/\n│ └── pipeline-patterns.md\n├── hooks/\n│ ├── hooks.json\n│ └── scripts/\n│ ├── security/\n│ │ ├── scan-secrets.sh\n│ │ ├── validate-permissions.sh\n│ │ └── audit-changes.sh\n│ ├── quality/\n│ │ ├── check-config.sh\n│ │ └── verify-tests.sh\n│ └── workflow/\n│ ├── notify-team.sh\n│ └── update-status.sh\n├── .mcp.json\n├── servers/\n│ ├── kubernetes-mcp/\n│ │ ├── index.js\n│ │ ├── package.json\n│ │ └── lib/\n│ ├── terraform-mcp/\n│ │ ├── main.py\n│ │ └── requirements.txt\n│ └── github-actions-mcp/\n│ ├── server.js\n│ └── package.json\n├── lib/\n│ ├── core/\n│ │ ├── logger.js\n│ │ ├── config.js\n│ │ └── auth.js\n│ ├── integrations/\n│ │ ├── slack.js\n│ │ ├── pagerduty.js\n│ │ └── datadog.js\n│ └── utils/\n│ ├── retry.js\n│ └── validation.js\n└── config/\n ├── environments/\n │ ├── production.json\n │ ├── staging.json\n │ └── development.json\n └── templates/\n ├── deployment.yaml\n └── service.yaml\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"enterprise-devops\",\n \"version\": \"2.3.1\",\n \"description\": \"Comprehensive DevOps automation for enterprise CI/CD pipelines, infrastructure management, and monitoring\",\n \"author\": {\n \"name\": \"DevOps Platform Team\",\n \"email\": \"devops-platform@company.com\",\n \"url\": \"https://company.com/teams/devops\"\n },\n \"homepage\": \"https://docs.company.com/plugins/devops\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/company/devops-plugin.git\"\n },\n \"license\": \"Apache-2.0\",\n \"keywords\": [\n \"devops\",\n \"ci-cd\",\n \"kubernetes\",\n \"terraform\",\n \"automation\",\n \"infrastructure\",\n \"deployment\",\n \"monitoring\"\n ],\n \"commands\": [\n \"./commands/ci\",\n \"./commands/monitoring\",\n \"./commands/admin\"\n ],\n \"agents\": [\n \"./agents/orchestration\",\n \"./agents/specialized\"\n ],\n \"hooks\": \"./hooks/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n### .mcp.json\n\n```json\n{\n \"mcpServers\": {\n \"kubernetes\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/kubernetes-mcp/index.js\"],\n \"env\": {\n \"KUBECONFIG\": \"${KUBECONFIG}\",\n \"K8S_NAMESPACE\": \"${K8S_NAMESPACE:-default}\"\n }\n },\n \"terraform\": {\n \"command\": \"python\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/terraform-mcp/main.py\"],\n \"env\": {\n \"TF_STATE_BUCKET\": \"${TF_STATE_BUCKET}\",\n \"AWS_REGION\": \"${AWS_REGION}\"\n }\n },\n \"github-actions\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/github-actions-mcp/server.js\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\",\n \"GITHUB_ORG\": \"${GITHUB_ORG}\"\n }\n }\n }\n}\n```\n\n### commands/ci/build.md\n\n```markdown\n---\nname: build\ndescription: Trigger and monitor CI build pipeline\n---\n\n# Build Command\n\nTrigger CI/CD build pipeline and monitor progress in real-time.\n\n## Process\n\n1. **Validation**: Check prerequisites\n - Verify branch status\n - Check for uncommitted changes\n - Validate configuration files\n\n2. **Trigger**: Start build via MCP server\n \\`\\`\\`javascript\n // Uses github-actions MCP server\n const build = await tools.github_actions_trigger_workflow({\n workflow: 'build.yml',\n ref: currentBranch\n })\n \\`\\`\\`\n\n3. **Monitor**: Track build progress\n - Display real-time logs\n - Show test results as they complete\n - Alert on failures\n\n4. **Report**: Summarize results\n - Build status\n - Test coverage\n - Performance metrics\n - Deploy readiness\n\n## Integration\n\nAfter successful build:\n- Offer to deploy to staging\n- Suggest performance optimizations\n- Generate deployment checklist\n```\n\n### agents/orchestration/deployment-orchestrator.md\n\n```markdown\n---\ndescription: Orchestrates complex multi-environment deployments with rollback capabilities and health monitoring\ncapabilities:\n - Plan and execute multi-stage deployments\n - Coordinate service dependencies\n - Monitor deployment health\n - Execute automated rollbacks\n - Manage deployment approvals\n---\n\n# Deployment Orchestrator Agent\n\nSpecialized agent for orchestrating complex deployments across multiple environments.\n\n## Expertise\n\n- **Deployment strategies**: Blue-green, canary, rolling updates\n- **Dependency management**: Service startup ordering, dependency injection\n- **Health monitoring**: Service health checks, metric validation\n- **Rollback automation**: Automatic rollback on failure detection\n- **Approval workflows**: Multi-stage approval processes\n\n## Orchestration Process\n\n1. **Planning Phase**\n - Analyze deployment requirements\n - Identify service dependencies\n - Generate deployment plan\n - Calculate rollback strategy\n\n2. **Validation Phase**\n - Verify environment readiness\n - Check resource availability\n - Validate configurations\n - Run pre-deployment tests\n\n3. **Execution Phase**\n - Deploy services in dependency order\n - Monitor health after each stage\n - Validate metrics and logs\n - Proceed to next stage on success\n\n4. **Verification Phase**\n - Run smoke tests\n - Validate service integration\n - Check performance metrics\n - Confirm deployment success\n\n5. **Rollback Phase** (if needed)\n - Detect failure conditions\n - Execute rollback plan\n - Restore previous state\n - Notify stakeholders\n\n## MCP Integration\n\nUses multiple MCP servers:\n- `kubernetes`: Deploy and manage containers\n- `terraform`: Provision infrastructure\n- `github-actions`: Trigger deployment pipelines\n\n## Monitoring Integration\n\nIntegrates with monitoring tools via lib:\n\\`\\`\\`javascript\nconst { DatadogClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/datadog')\nconst metrics = await DatadogClient.getMetrics(service, timeRange)\n\\`\\`\\`\n\n## Notification Integration\n\nSends updates via Slack and PagerDuty:\n\\`\\`\\`javascript\nconst { SlackClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/slack')\nawait SlackClient.notify({\n channel: '#deployments',\n message: 'Deployment started',\n metadata: deploymentPlan\n})\n\\`\\`\\`\n```\n\n### skills/kubernetes-ops/SKILL.md\n\n```markdown\n---\nname: Kubernetes Operations\ndescription: This skill should be used when deploying to Kubernetes, managing K8s resources, troubleshooting cluster issues, configuring ingress/services, scaling deployments, or working with Kubernetes manifests. Provides comprehensive Kubernetes operational knowledge and best practices.\nversion: 2.0.0\n---\n\n# Kubernetes Operations\n\nComprehensive operational knowledge for managing Kubernetes clusters and workloads.\n\n## Overview\n\nManage Kubernetes infrastructure effectively through:\n- Deployment strategies and patterns\n- Resource configuration and optimization\n- Troubleshooting and debugging\n- Security best practices\n- Performance tuning\n\n## Core Concepts\n\n### Resource Management\n\n**Deployments**: Use for stateless applications\n- Rolling updates for zero-downtime deployments\n- Rollback capabilities for failed deployments\n- Replica management for scaling\n\n**StatefulSets**: Use for stateful applications\n- Stable network identities\n- Persistent storage\n- Ordered deployment and scaling\n\n**DaemonSets**: Use for node-level services\n- Log collectors\n- Monitoring agents\n- Network plugins\n\n### Configuration\n\n**ConfigMaps**: Store non-sensitive configuration\n- Environment-specific settings\n- Application configuration files\n- Feature flags\n\n**Secrets**: Store sensitive data\n- API keys and tokens\n- Database credentials\n- TLS certificates\n\nUse external secret management (Vault, AWS Secrets Manager) for production.\n\n### Networking\n\n**Services**: Expose applications internally\n- ClusterIP for internal communication\n- NodePort for external access (non-production)\n- LoadBalancer for external access (production)\n\n**Ingress**: HTTP/HTTPS routing\n- Path-based routing\n- Host-based routing\n- TLS termination\n- Load balancing\n\n## Deployment Strategies\n\n### Rolling Update\n\nDefault strategy, gradual replacement:\n\\`\\`\\`yaml\nstrategy:\n type: RollingUpdate\n rollingUpdate:\n maxSurge: 1\n maxUnavailable: 0\n\\`\\`\\`\n\n**When to use**: Standard deployments, minor updates\n\n### Recreate\n\nStop all pods, then create new ones:\n\\`\\`\\`yaml\nstrategy:\n type: Recreate\n\\`\\`\\`\n\n**When to use**: Stateful apps that can't run multiple versions\n\n### Blue-Green\n\nRun two complete environments, switch traffic:\n1. Deploy new version (green)\n2. Test green environment\n3. Switch traffic to green\n4. Keep blue for quick rollback\n\n**When to use**: Critical services, need instant rollback\n\n### Canary\n\nGradually roll out to subset of users:\n1. Deploy canary version (10% traffic)\n2. Monitor metrics and errors\n3. Increase traffic gradually\n4. Complete rollout or rollback\n\n**When to use**: High-risk changes, want gradual validation\n\n## Resource Configuration\n\n### Resource Requests and Limits\n\nAlways set for production workloads:\n\\`\\`\\`yaml\nresources:\n requests:\n memory: \"256Mi\"\n cpu: \"250m\"\n limits:\n memory: \"512Mi\"\n cpu: \"500m\"\n\\`\\`\\`\n\n**Requests**: Guaranteed resources\n**Limits**: Maximum allowed resources\n\n### Health Checks\n\nEssential for reliability:\n\\`\\`\\`yaml\nlivenessProbe:\n httpGet:\n path: /health\n port: 8080\n initialDelaySeconds: 30\n periodSeconds: 10\n\nreadinessProbe:\n httpGet:\n path: /ready\n port: 8080\n initialDelaySeconds: 5\n periodSeconds: 5\n\\`\\`\\`\n\n**Liveness**: Restart unhealthy pods\n**Readiness**: Remove unready pods from service\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Pods not starting**\n - Check: `kubectl describe pod `\n - Look for: Image pull errors, resource constraints\n - Fix: Verify image name, increase resources\n\n2. **Service not reachable**\n - Check: `kubectl get svc`, `kubectl get endpoints`\n - Look for: No endpoints, wrong selector\n - Fix: Verify pod labels match service selector\n\n3. **High memory usage**\n - Check: `kubectl top pods`\n - Look for: Pods near memory limit\n - Fix: Increase limits, optimize application\n\n4. **Frequent restarts**\n - Check: `kubectl get pods`, `kubectl logs `\n - Look for: Liveness probe failures, OOMKilled\n - Fix: Adjust health checks, increase memory\n\n### Debugging Commands\n\nGet pod details:\n\\`\\`\\`bash\nkubectl describe pod \nkubectl logs \nkubectl logs --previous # logs from crashed container\n\\`\\`\\`\n\nExecute commands in pod:\n\\`\\`\\`bash\nkubectl exec -it -- /bin/sh\nkubectl exec -- env\n\\`\\`\\`\n\nCheck resource usage:\n\\`\\`\\`bash\nkubectl top nodes\nkubectl top pods\n\\`\\`\\`\n\n## Security Best Practices\n\n### Pod Security\n\n- Run as non-root user\n- Use read-only root filesystem\n- Drop unnecessary capabilities\n- Use security contexts\n\nExample:\n\\`\\`\\`yaml\nsecurityContext:\n runAsNonRoot: true\n runAsUser: 1000\n readOnlyRootFilesystem: true\n capabilities:\n drop:\n - ALL\n\\`\\`\\`\n\n### Network Policies\n\nRestrict pod communication:\n\\`\\`\\`yaml\napiVersion: networking.k8s.io/v1\nkind: NetworkPolicy\nmetadata:\n name: api-allow\nspec:\n podSelector:\n matchLabels:\n app: api\n ingress:\n - from:\n - podSelector:\n matchLabels:\n app: frontend\n\\`\\`\\`\n\n### Secrets Management\n\n- Never commit secrets to git\n- Use external secret managers\n- Rotate secrets regularly\n- Limit secret access with RBAC\n\n## Performance Optimization\n\n### Resource Tuning\n\n1. **Start conservative**: Set low limits initially\n2. **Monitor usage**: Track actual resource consumption\n3. **Adjust gradually**: Increase based on metrics\n4. **Set appropriate requests**: Match typical usage\n5. **Set safe limits**: 2x requests for headroom\n\n### Horizontal Pod Autoscaling\n\nAutomatically scale based on metrics:\n\\`\\`\\`yaml\napiVersion: autoscaling/v2\nkind: HorizontalPodAutoscaler\nmetadata:\n name: api-hpa\nspec:\n scaleTargetRef:\n apiVersion: apps/v1\n kind: Deployment\n name: api\n minReplicas: 2\n maxReplicas: 10\n metrics:\n - type: Resource\n resource:\n name: cpu\n target:\n type: Utilization\n averageUtilization: 70\n\\`\\`\\`\n\n## MCP Server Integration\n\nThis skill works with the kubernetes MCP server for operations:\n\n**List pods**:\n\\`\\`\\`javascript\nconst pods = await tools.k8s_list_pods({ namespace: 'default' })\n\\`\\`\\`\n\n**Get pod logs**:\n\\`\\`\\`javascript\nconst logs = await tools.k8s_get_logs({ pod: 'api-xyz', container: 'app' })\n\\`\\`\\`\n\n**Apply manifests**:\n\\`\\`\\`javascript\nconst result = await tools.k8s_apply_manifest({ file: 'deployment.yaml' })\n\\`\\`\\`\n\n## Detailed References\n\nFor in-depth information:\n- **Deployment patterns**: `references/deployment-patterns.md`\n- **Troubleshooting guide**: `references/troubleshooting.md`\n- **Security hardening**: `references/security.md`\n\n## Example Manifests\n\nFor copy-paste examples:\n- **Basic deployment**: `examples/basic-deployment.yaml`\n- **StatefulSet**: `examples/stateful-set.yaml`\n- **Ingress config**: `examples/ingress-config.yaml`\n\n## Validation Scripts\n\nFor manifest validation:\n\\`\\`\\`bash\nbash ${CLAUDE_PLUGIN_ROOT}/skills/kubernetes-ops/scripts/validate-manifest.sh deployment.yaml\n\\`\\`\\`\n```\n\n### hooks/hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/scan-secrets.sh\",\n \"timeout\": 30\n }\n ]\n },\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Evaluate if this bash command is safe for production environment. Check for destructive operations, missing safeguards, and potential security issues. Commands should be idempotent and reversible.\",\n \"timeout\": 20\n }\n ]\n }\n ],\n \"PostToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/update-status.sh\",\n \"timeout\": 15\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quality/check-config.sh\",\n \"timeout\": 45\n },\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/notify-team.sh\",\n \"timeout\": 30\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/validate-permissions.sh\",\n \"timeout\": 20\n }\n ]\n }\n ]\n}\n```\n\n## Key Features\n\n### Multi-Level Organization\n\n**Commands**: Organized by function (CI, monitoring, admin)\n**Agents**: Separated by role (orchestration vs. specialized)\n**Skills**: Rich resources (references, examples, scripts)\n\n### MCP Integration\n\nThree custom MCP servers:\n- **Kubernetes**: Cluster operations\n- **Terraform**: Infrastructure provisioning\n- **GitHub Actions**: CI/CD automation\n\n### Shared Libraries\n\nReusable code in `lib/`:\n- **Core**: Common utilities (logging, config, auth)\n- **Integrations**: External services (Slack, Datadog)\n- **Utils**: Helper functions (retry, validation)\n\n### Configuration Management\n\nEnvironment-specific configs in `config/`:\n- **Environments**: Per-environment settings\n- **Templates**: Reusable deployment templates\n\n### Security Automation\n\nMultiple security hooks:\n- Secret scanning before writes\n- Permission validation on session start\n- Configuration auditing on completion\n\n### Monitoring Integration\n\nBuilt-in monitoring via lib integrations:\n- Datadog for metrics\n- PagerDuty for alerts\n- Slack for notifications\n\n## Use Cases\n\n1. **Multi-environment deployments**: Orchestrated rollouts across dev/staging/prod\n2. **Infrastructure as code**: Terraform automation with state management\n3. **CI/CD automation**: Build, test, deploy pipelines\n4. **Monitoring and observability**: Integrated metrics and alerting\n5. **Security enforcement**: Automated security scanning and validation\n6. **Team collaboration**: Slack notifications and status updates\n\n## When to Use This Pattern\n\n- Large-scale enterprise deployments\n- Multiple environment management\n- Complex CI/CD workflows\n- Integrated monitoring requirements\n- Security-critical infrastructure\n- Team collaboration needs\n\n## Scaling Considerations\n\n- **Performance**: Separate MCP servers for parallel operations\n- **Organization**: Multi-level directories for scalability\n- **Maintainability**: Shared libraries reduce duplication\n- **Flexibility**: Environment configs enable customization\n- **Security**: Layered security hooks and validation\n","plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md":"# Minimal Plugin Example\n\nA bare-bones plugin with a single command.\n\n## Directory Structure\n\n```\nhello-world/\n├── .claude-plugin/\n│ └── plugin.json\n└── commands/\n └── hello.md\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"hello-world\"\n}\n```\n\n### commands/hello.md\n\n```markdown\n---\nname: hello\ndescription: Prints a friendly greeting message\n---\n\n# Hello Command\n\nPrint a friendly greeting to the user.\n\n## Implementation\n\nOutput the following message to the user:\n\n> Hello! This is a simple command from the hello-world plugin.\n>\n> Use this as a starting point for building more complex plugins.\n\nInclude the current timestamp in the greeting to show the command executed successfully.\n```\n\n## Usage\n\nAfter installing the plugin:\n\n```\n$ claude\n> /hello\nHello! This is a simple command from the hello-world plugin.\n\nUse this as a starting point for building more complex plugins.\n\nExecuted at: 2025-01-15 14:30:22 UTC\n```\n\n## Key Points\n\n1. **Minimal manifest**: Only the required `name` field\n2. **Single command**: One markdown file in `commands/` directory\n3. **Auto-discovery**: Claude Code finds the command automatically\n4. **No dependencies**: No scripts, hooks, or external resources\n\n## When to Use This Pattern\n\n- Quick prototypes\n- Single-purpose utilities\n- Learning plugin development\n- Internal team tools with one specific function\n\n## Extending This Plugin\n\nTo add more functionality:\n\n1. **Add commands**: Create more `.md` files in `commands/`\n2. **Add metadata**: Update `plugin.json` with version, description, author\n3. **Add agents**: Create `agents/` directory with agent definitions\n4. **Add hooks**: Create `hooks/hooks.json` for event handling\n","plugins/plugin-dev/skills/plugin-structure/examples/standard-plugin.md":"# Standard Plugin Example\n\nA well-structured plugin with commands, agents, and skills.\n\n## Directory Structure\n\n```\ncode-quality/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n│ ├── lint.md\n│ ├── test.md\n│ └── review.md\n├── agents/\n│ ├── code-reviewer.md\n│ └── test-generator.md\n├── skills/\n│ ├── code-standards/\n│ │ ├── SKILL.md\n│ │ └── references/\n│ │ └── style-guide.md\n│ └── testing-patterns/\n│ ├── SKILL.md\n│ └── examples/\n│ ├── unit-test.js\n│ └── integration-test.js\n├── hooks/\n│ ├── hooks.json\n│ └── scripts/\n│ └── validate-commit.sh\n└── scripts/\n ├── run-linter.sh\n └── generate-report.py\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"code-quality\",\n \"version\": \"1.0.0\",\n \"description\": \"Comprehensive code quality tools including linting, testing, and review automation\",\n \"author\": {\n \"name\": \"Quality Team\",\n \"email\": \"quality@example.com\"\n },\n \"homepage\": \"https://docs.example.com/plugins/code-quality\",\n \"repository\": \"https://github.com/example/code-quality-plugin\",\n \"license\": \"MIT\",\n \"keywords\": [\"code-quality\", \"linting\", \"testing\", \"code-review\", \"automation\"]\n}\n```\n\n### commands/lint.md\n\n```markdown\n---\nname: lint\ndescription: Run linting checks on the codebase\n---\n\n# Lint Command\n\nRun comprehensive linting checks on the project codebase.\n\n## Process\n\n1. Detect project type and installed linters\n2. Run appropriate linters (ESLint, Pylint, RuboCop, etc.)\n3. Collect and format results\n4. Report issues with file locations and severity\n\n## Implementation\n\nExecute the linting script:\n\n\\`\\`\\`bash\nbash ${CLAUDE_PLUGIN_ROOT}/scripts/run-linter.sh\n\\`\\`\\`\n\nParse the output and present issues organized by:\n- Critical issues (must fix)\n- Warnings (should fix)\n- Style suggestions (optional)\n\nFor each issue, show:\n- File path and line number\n- Issue description\n- Suggested fix (if available)\n```\n\n### commands/test.md\n\n```markdown\n---\nname: test\ndescription: Run test suite with coverage reporting\n---\n\n# Test Command\n\nExecute the project test suite and generate coverage reports.\n\n## Process\n\n1. Identify test framework (Jest, pytest, RSpec, etc.)\n2. Run all tests\n3. Generate coverage report\n4. Identify untested code\n\n## Output\n\nPresent results in structured format:\n- Test summary (passed/failed/skipped)\n- Coverage percentage by file\n- Critical untested areas\n- Failed test details\n\n## Integration\n\nAfter test completion, offer to:\n- Fix failing tests\n- Generate tests for untested code (using test-generator agent)\n- Update documentation based on test changes\n```\n\n### agents/code-reviewer.md\n\n```markdown\n---\ndescription: Expert code reviewer specializing in identifying bugs, security issues, and improvement opportunities\ncapabilities:\n - Analyze code for potential bugs and logic errors\n - Identify security vulnerabilities\n - Suggest performance improvements\n - Ensure code follows project standards\n - Review test coverage adequacy\n---\n\n# Code Reviewer Agent\n\nSpecialized agent for comprehensive code review.\n\n## Expertise\n\n- **Bug detection**: Logic errors, edge cases, error handling\n- **Security analysis**: Injection vulnerabilities, authentication issues, data exposure\n- **Performance**: Algorithm efficiency, resource usage, optimization opportunities\n- **Standards compliance**: Style guide adherence, naming conventions, documentation\n- **Test coverage**: Adequacy of test cases, missing scenarios\n\n## Review Process\n\n1. **Initial scan**: Quick pass for obvious issues\n2. **Deep analysis**: Line-by-line review of changed code\n3. **Context evaluation**: Check impact on related code\n4. **Best practices**: Compare against project and language standards\n5. **Recommendations**: Prioritized list of improvements\n\n## Integration with Skills\n\nAutomatically loads `code-standards` skill for project-specific guidelines.\n\n## Output Format\n\nFor each file reviewed:\n- Overall assessment\n- Critical issues (must fix before merge)\n- Important issues (should fix)\n- Suggestions (nice to have)\n- Positive feedback (what was done well)\n```\n\n### agents/test-generator.md\n\n```markdown\n---\ndescription: Generates comprehensive test suites from code analysis\ncapabilities:\n - Analyze code structure and logic flow\n - Generate unit tests for functions and methods\n - Create integration tests for modules\n - Design edge case and error condition tests\n - Suggest test fixtures and mocks\n---\n\n# Test Generator Agent\n\nSpecialized agent for generating comprehensive test suites.\n\n## Expertise\n\n- **Unit testing**: Individual function/method tests\n- **Integration testing**: Module interaction tests\n- **Edge cases**: Boundary conditions, error paths\n- **Test organization**: Proper test structure and naming\n- **Mocking**: Appropriate use of mocks and stubs\n\n## Generation Process\n\n1. **Code analysis**: Understand function purpose and logic\n2. **Path identification**: Map all execution paths\n3. **Input design**: Create test inputs covering all paths\n4. **Assertion design**: Define expected outputs\n5. **Test generation**: Write tests in project's framework\n\n## Integration with Skills\n\nAutomatically loads `testing-patterns` skill for project-specific test conventions.\n\n## Test Quality\n\nGenerated tests include:\n- Happy path scenarios\n- Edge cases and boundary conditions\n- Error handling verification\n- Mock data for external dependencies\n- Clear test descriptions\n```\n\n### skills/code-standards/SKILL.md\n\n```markdown\n---\nname: Code Standards\ndescription: This skill should be used when reviewing code, enforcing style guidelines, checking naming conventions, or ensuring code quality standards. Provides project-specific coding standards and best practices.\nversion: 1.0.0\n---\n\n# Code Standards\n\nComprehensive coding standards and best practices for maintaining code quality.\n\n## Overview\n\nEnforce consistent code quality through standardized conventions for:\n- Code style and formatting\n- Naming conventions\n- Documentation requirements\n- Error handling patterns\n- Security practices\n\n## Style Guidelines\n\n### Formatting\n\n- **Indentation**: 2 spaces (JavaScript/TypeScript), 4 spaces (Python)\n- **Line length**: Maximum 100 characters\n- **Braces**: Same line for opening brace (K&R style)\n- **Whitespace**: Space after commas, around operators\n\n### Naming Conventions\n\n- **Variables**: camelCase for JavaScript, snake_case for Python\n- **Functions**: camelCase, descriptive verb-noun pairs\n- **Classes**: PascalCase\n- **Constants**: UPPER_SNAKE_CASE\n- **Files**: kebab-case for modules\n\n## Documentation Requirements\n\n### Function Documentation\n\nEvery function must include:\n- Purpose description\n- Parameter descriptions with types\n- Return value description with type\n- Example usage (for public functions)\n\n### Module Documentation\n\nEvery module must include:\n- Module purpose\n- Public API overview\n- Usage examples\n- Dependencies\n\n## Error Handling\n\n### Required Practices\n\n- Never swallow errors silently\n- Always log errors with context\n- Use specific error types\n- Provide actionable error messages\n- Clean up resources in finally blocks\n\n### Example Pattern\n\n\\`\\`\\`javascript\nasync function processData(data) {\n try {\n const result = await transform(data)\n return result\n } catch (error) {\n logger.error('Data processing failed', {\n data: sanitize(data),\n error: error.message,\n stack: error.stack\n })\n throw new DataProcessingError('Failed to process data', { cause: error })\n }\n}\n\\`\\`\\`\n\n## Security Practices\n\n- Validate all external input\n- Sanitize data before output\n- Use parameterized queries\n- Never log sensitive information\n- Keep dependencies updated\n\n## Detailed Guidelines\n\nFor comprehensive style guides by language, see:\n- `references/style-guide.md`\n```\n\n### skills/code-standards/references/style-guide.md\n\n```markdown\n# Comprehensive Style Guide\n\nDetailed style guidelines for all supported languages.\n\n## JavaScript/TypeScript\n\n### Variable Declarations\n\nUse `const` by default, `let` when reassignment needed, never `var`:\n\n\\`\\`\\`javascript\n// Good\nconst MAX_RETRIES = 3\nlet currentTry = 0\n\n// Bad\nvar MAX_RETRIES = 3\n\\`\\`\\`\n\n### Function Declarations\n\nUse function expressions for consistency:\n\n\\`\\`\\`javascript\n// Good\nconst calculateTotal = (items) => {\n return items.reduce((sum, item) => sum + item.price, 0)\n}\n\n// Bad (inconsistent style)\nfunction calculateTotal(items) {\n return items.reduce((sum, item) => sum + item.price, 0)\n}\n\\`\\`\\`\n\n### Async/Await\n\nPrefer async/await over promise chains:\n\n\\`\\`\\`javascript\n// Good\nasync function fetchUserData(userId) {\n const user = await db.getUser(userId)\n const orders = await db.getOrders(user.id)\n return { user, orders }\n}\n\n// Bad\nfunction fetchUserData(userId) {\n return db.getUser(userId)\n .then(user => db.getOrders(user.id)\n .then(orders => ({ user, orders })))\n}\n\\`\\`\\`\n\n## Python\n\n### Import Organization\n\nOrder imports: standard library, third-party, local:\n\n\\`\\`\\`python\n# Good\nimport os\nimport sys\n\nimport numpy as np\nimport pandas as pd\n\nfrom app.models import User\nfrom app.utils import helper\n\n# Bad - mixed order\nfrom app.models import User\nimport numpy as np\nimport os\n\\`\\`\\`\n\n### Type Hints\n\nUse type hints for all function signatures:\n\n\\`\\`\\`python\n# Good\ndef calculate_average(numbers: list[float]) -> float:\n return sum(numbers) / len(numbers)\n\n# Bad\ndef calculate_average(numbers):\n return sum(numbers) / len(numbers)\n\\`\\`\\`\n\n## Additional Languages\n\nSee language-specific guides for:\n- Go: `references/go-style.md`\n- Rust: `references/rust-style.md`\n- Ruby: `references/ruby-style.md`\n```\n\n### hooks/hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Before modifying code, verify it meets our coding standards from the code-standards skill. Check formatting, naming conventions, and documentation. If standards aren't met, suggest improvements.\",\n \"timeout\": 30\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate-commit.sh\",\n \"timeout\": 45\n }\n ]\n }\n ]\n}\n```\n\n### hooks/scripts/validate-commit.sh\n\n```bash\n#!/bin/bash\n# Validate code quality before task completion\n\nset -e\n\n# Check if there are any uncommitted changes\nif [[ -z $(git status -s) ]]; then\n echo '{\"systemMessage\": \"No changes to validate. Task complete.\"}'\n exit 0\nfi\n\n# Run linter on changed files\nCHANGED_FILES=$(git diff --name-only --cached | grep -E '\\.(js|ts|py)$' || true)\n\nif [[ -z \"$CHANGED_FILES\" ]]; then\n echo '{\"systemMessage\": \"No code files changed. Validation passed.\"}'\n exit 0\nfi\n\n# Run appropriate linters\nISSUES=0\n\nfor file in $CHANGED_FILES; do\n case \"$file\" in\n *.js|*.ts)\n if ! npx eslint \"$file\" --quiet; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n *.py)\n if ! python -m pylint \"$file\" --errors-only; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n esac\ndone\n\nif [[ $ISSUES -gt 0 ]]; then\n echo \"{\\\"systemMessage\\\": \\\"Found $ISSUES code quality issues. Please fix before completing.\\\"}\"\n exit 1\nfi\n\necho '{\"systemMessage\": \"Code quality checks passed. Ready to commit.\"}'\nexit 0\n```\n\n## Usage Examples\n\n### Running Commands\n\n```\n$ claude\n> /lint\nRunning linter checks...\n\nCritical Issues (2):\n src/api/users.js:45 - SQL injection vulnerability\n src/utils/helpers.js:12 - Unhandled promise rejection\n\nWarnings (5):\n src/components/Button.tsx:23 - Missing PropTypes\n ...\n\nStyle Suggestions (8):\n src/index.js:1 - Use const instead of let\n ...\n\n> /test\nRunning test suite...\n\nTest Results:\n ✓ 245 passed\n ✗ 3 failed\n ○ 2 skipped\n\nCoverage: 87.3%\n\nUntested Files:\n src/utils/cache.js - 0% coverage\n src/api/webhooks.js - 23% coverage\n\nFailed Tests:\n 1. User API › GET /users › should handle pagination\n Expected 200, received 500\n ...\n```\n\n### Using Agents\n\n```\n> Review the changes in src/api/users.js\n\n[code-reviewer agent selected automatically]\n\nCode Review: src/api/users.js\n\nCritical Issues:\n 1. Line 45: SQL injection vulnerability\n - Using string concatenation for SQL query\n - Replace with parameterized query\n - Priority: CRITICAL\n\n 2. Line 67: Missing error handling\n - Database query without try/catch\n - Could crash server on DB error\n - Priority: HIGH\n\nSuggestions:\n 1. Line 23: Consider caching user data\n - Frequent DB queries for same users\n - Add Redis caching layer\n - Priority: MEDIUM\n```\n\n## Key Points\n\n1. **Complete manifest**: All recommended metadata fields\n2. **Multiple components**: Commands, agents, skills, hooks\n3. **Rich skills**: References and examples for detailed information\n4. **Automation**: Hooks enforce standards automatically\n5. **Integration**: Components work together cohesively\n\n## When to Use This Pattern\n\n- Production plugins for distribution\n- Team collaboration tools\n- Plugins requiring consistency enforcement\n- Complex workflows with multiple entry points\n","plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md":"# Component Organization Patterns\n\nAdvanced patterns for organizing plugin components effectively.\n\n## Component Lifecycle\n\n### Discovery Phase\n\nWhen Claude Code starts:\n\n1. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each\n2. **Discover components**: Look in default and custom paths\n3. **Parse definitions**: Read YAML frontmatter and configurations\n4. **Register components**: Make available to Claude Code\n5. **Initialize**: Start MCP servers, register hooks\n\n**Timing**: Component registration happens during Claude Code initialization, not continuously.\n\n### Activation Phase\n\nWhen components are used:\n\n**Commands**: User types slash command → Claude Code looks up → Executes\n**Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent\n**Skills**: Task context matches description → Claude Code loads skill\n**Hooks**: Event occurs → Claude Code calls matching hooks\n**MCP Servers**: Tool call matches server capability → Forwards to server\n\n## Command Organization Patterns\n\n### Flat Structure\n\nSingle directory with all commands:\n\n```\ncommands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**When to use**:\n- 5-15 commands total\n- All commands at same abstraction level\n- No clear categorization\n\n**Advantages**:\n- Simple, easy to navigate\n- No configuration needed\n- Fast discovery\n\n### Categorized Structure\n\nMultiple directories for different command types:\n\n```\ncommands/ # Core commands\n├── build.md\n└── test.md\n\nadmin-commands/ # Administrative\n├── configure.md\n└── manage.md\n\nworkflow-commands/ # Workflow automation\n├── review.md\n└── deploy.md\n```\n\n**Manifest configuration**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./workflow-commands\"\n ]\n}\n```\n\n**When to use**:\n- 15+ commands\n- Clear functional categories\n- Different permission levels\n\n**Advantages**:\n- Organized by purpose\n- Easier to maintain\n- Can restrict access by directory\n\n### Hierarchical Structure\n\nNested organization for complex plugins:\n\n```\ncommands/\n├── ci/\n│ ├── build.md\n│ ├── test.md\n│ └── lint.md\n├── deployment/\n│ ├── staging.md\n│ └── production.md\n└── management/\n ├── config.md\n └── status.md\n```\n\n**Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths:\n\n```json\n{\n \"commands\": [\n \"./commands/ci\",\n \"./commands/deployment\",\n \"./commands/management\"\n ]\n}\n```\n\n**When to use**:\n- 20+ commands\n- Multi-level categorization\n- Complex workflows\n\n**Advantages**:\n- Maximum organization\n- Clear boundaries\n- Scalable structure\n\n## Agent Organization Patterns\n\n### Role-Based Organization\n\nOrganize agents by their primary role:\n\n```\nagents/\n├── code-reviewer.md # Reviews code\n├── test-generator.md # Generates tests\n├── documentation-writer.md # Writes docs\n└── refactorer.md # Refactors code\n```\n\n**When to use**:\n- Agents have distinct, non-overlapping roles\n- Users invoke agents manually\n- Clear agent responsibilities\n\n### Capability-Based Organization\n\nOrganize by specific capabilities:\n\n```\nagents/\n├── python-expert.md # Python-specific\n├── typescript-expert.md # TypeScript-specific\n├── api-specialist.md # API design\n└── database-specialist.md # Database work\n```\n\n**When to use**:\n- Technology-specific agents\n- Domain expertise focus\n- Automatic agent selection\n\n### Workflow-Based Organization\n\nOrganize by workflow stage:\n\n```\nagents/\n├── planning-agent.md # Planning phase\n├── implementation-agent.md # Coding phase\n├── testing-agent.md # Testing phase\n└── deployment-agent.md # Deployment phase\n```\n\n**When to use**:\n- Sequential workflows\n- Stage-specific expertise\n- Pipeline automation\n\n## Skill Organization Patterns\n\n### Topic-Based Organization\n\nEach skill covers a specific topic:\n\n```\nskills/\n├── api-design/\n│ └── SKILL.md\n├── error-handling/\n│ └── SKILL.md\n├── testing-strategies/\n│ └── SKILL.md\n└── performance-optimization/\n └── SKILL.md\n```\n\n**When to use**:\n- Knowledge-based skills\n- Educational or reference content\n- Broad applicability\n\n### Tool-Based Organization\n\nSkills for specific tools or technologies:\n\n```\nskills/\n├── docker/\n│ ├── SKILL.md\n│ └── references/\n│ └── dockerfile-best-practices.md\n├── kubernetes/\n│ ├── SKILL.md\n│ └── examples/\n│ └── deployment.yaml\n└── terraform/\n ├── SKILL.md\n └── scripts/\n └── validate-config.sh\n```\n\n**When to use**:\n- Tool-specific expertise\n- Complex tool configurations\n- Tool best practices\n\n### Workflow-Based Organization\n\nSkills for complete workflows:\n\n```\nskills/\n├── code-review-workflow/\n│ ├── SKILL.md\n│ └── references/\n│ ├── checklist.md\n│ └── standards.md\n├── deployment-workflow/\n│ ├── SKILL.md\n│ └── scripts/\n│ ├── pre-deploy.sh\n│ └── post-deploy.sh\n└── testing-workflow/\n ├── SKILL.md\n └── examples/\n └── test-structure.md\n```\n\n**When to use**:\n- Multi-step processes\n- Company-specific workflows\n- Process automation\n\n### Skill with Rich Resources\n\nComprehensive skill with all resource types:\n\n```\nskills/\n└── api-testing/\n ├── SKILL.md # Core skill (1500 words)\n ├── references/\n │ ├── rest-api-guide.md\n │ ├── graphql-guide.md\n │ └── authentication.md\n ├── examples/\n │ ├── basic-test.js\n │ ├── authenticated-test.js\n │ └── integration-test.js\n ├── scripts/\n │ ├── run-tests.sh\n │ └── generate-report.py\n └── assets/\n └── test-template.json\n```\n\n**Resource usage**:\n- **SKILL.md**: Overview and when to use resources\n- **references/**: Detailed guides (loaded as needed)\n- **examples/**: Copy-paste code samples\n- **scripts/**: Executable test runners\n- **assets/**: Templates and configurations\n\n## Hook Organization Patterns\n\n### Monolithic Configuration\n\nSingle hooks.json with all hooks:\n\n```\nhooks/\n├── hooks.json # All hook definitions\n└── scripts/\n ├── validate-write.sh\n ├── validate-bash.sh\n └── load-context.sh\n```\n\n**hooks.json**:\n```json\n{\n \"PreToolUse\": [...],\n \"PostToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**When to use**:\n- 5-10 hooks total\n- Simple hook logic\n- Centralized configuration\n\n### Event-Based Organization\n\nSeparate files per event type:\n\n```\nhooks/\n├── hooks.json # Combines all\n├── pre-tool-use.json # PreToolUse hooks\n├── post-tool-use.json # PostToolUse hooks\n├── stop.json # Stop hooks\n└── scripts/\n ├── validate/\n │ ├── write.sh\n │ └── bash.sh\n └── context/\n └── load.sh\n```\n\n**hooks.json** (combines):\n```json\n{\n \"PreToolUse\": ${file:./pre-tool-use.json},\n \"PostToolUse\": ${file:./post-tool-use.json},\n \"Stop\": ${file:./stop.json}\n}\n```\n\n**Note**: Use build script to combine files, Claude Code doesn't support file references.\n\n**When to use**:\n- 10+ hooks\n- Different teams managing different events\n- Complex hook configurations\n\n### Purpose-Based Organization\n\nGroup by functional purpose:\n\n```\nhooks/\n├── hooks.json\n└── scripts/\n ├── security/\n │ ├── validate-paths.sh\n │ ├── check-credentials.sh\n │ └── scan-malware.sh\n ├── quality/\n │ ├── lint-code.sh\n │ ├── check-tests.sh\n │ └── verify-docs.sh\n └── workflow/\n ├── notify-team.sh\n └── update-status.sh\n```\n\n**When to use**:\n- Many hook scripts\n- Clear functional boundaries\n- Team specialization\n\n## Script Organization Patterns\n\n### Flat Scripts\n\nAll scripts in single directory:\n\n```\nscripts/\n├── build.sh\n├── test.py\n├── deploy.sh\n├── validate.js\n└── report.py\n```\n\n**When to use**:\n- 5-10 scripts\n- All scripts related\n- Simple plugin\n\n### Categorized Scripts\n\nGroup by purpose:\n\n```\nscripts/\n├── build/\n│ ├── compile.sh\n│ └── package.sh\n├── test/\n│ ├── run-unit.sh\n│ └── run-integration.sh\n├── deploy/\n│ ├── staging.sh\n│ └── production.sh\n└── utils/\n ├── log.sh\n └── notify.sh\n```\n\n**When to use**:\n- 10+ scripts\n- Clear categories\n- Reusable utilities\n\n### Language-Based Organization\n\nGroup by programming language:\n\n```\nscripts/\n├── bash/\n│ ├── build.sh\n│ └── deploy.sh\n├── python/\n│ ├── analyze.py\n│ └── report.py\n└── javascript/\n ├── bundle.js\n └── optimize.js\n```\n\n**When to use**:\n- Multi-language scripts\n- Different runtime requirements\n- Language-specific dependencies\n\n## Cross-Component Patterns\n\n### Shared Resources\n\nComponents sharing common resources:\n\n```\nplugin/\n├── commands/\n│ ├── test.md # Uses lib/test-utils.sh\n│ └── deploy.md # Uses lib/deploy-utils.sh\n├── agents/\n│ └── tester.md # References lib/test-utils.sh\n├── hooks/\n│ └── scripts/\n│ └── pre-test.sh # Sources lib/test-utils.sh\n└── lib/\n ├── test-utils.sh\n └── deploy-utils.sh\n```\n\n**Usage in components**:\n```bash\n#!/bin/bash\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh\"\nrun_tests\n```\n\n**Benefits**:\n- Code reuse\n- Consistent behavior\n- Easier maintenance\n\n### Layered Architecture\n\nSeparate concerns into layers:\n\n```\nplugin/\n├── commands/ # User interface layer\n├── agents/ # Orchestration layer\n├── skills/ # Knowledge layer\n└── lib/\n ├── core/ # Core business logic\n ├── integrations/ # External services\n └── utils/ # Helper functions\n```\n\n**When to use**:\n- Large plugins (100+ files)\n- Multiple developers\n- Clear separation of concerns\n\n### Plugin Within Plugin\n\nNested plugin structure:\n\n```\nplugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── core/ # Core functionality\n│ ├── commands/\n│ └── agents/\n└── extensions/ # Optional extensions\n ├── extension-a/\n │ ├── commands/\n │ └── agents/\n └── extension-b/\n ├── commands/\n └── agents/\n```\n\n**Manifest**:\n```json\n{\n \"commands\": [\n \"./core/commands\",\n \"./extensions/extension-a/commands\",\n \"./extensions/extension-b/commands\"\n ]\n}\n```\n\n**When to use**:\n- Modular functionality\n- Optional features\n- Plugin families\n\n## Best Practices\n\n### Naming\n\n1. **Consistent naming**: Match file names to component purpose\n2. **Descriptive names**: Indicate what component does\n3. **Avoid abbreviations**: Use full words for clarity\n\n### Organization\n\n1. **Start simple**: Use flat structure, reorganize when needed\n2. **Group related items**: Keep related components together\n3. **Separate concerns**: Don't mix unrelated functionality\n\n### Scalability\n\n1. **Plan for growth**: Choose structure that scales\n2. **Refactor early**: Reorganize before it becomes painful\n3. **Document structure**: Explain organization in README\n\n### Maintainability\n\n1. **Consistent patterns**: Use same structure throughout\n2. **Minimize nesting**: Keep directory depth manageable\n3. **Use conventions**: Follow community standards\n\n### Performance\n\n1. **Avoid deep nesting**: Impacts discovery time\n2. **Minimize custom paths**: Use defaults when possible\n3. **Keep configurations small**: Large configs slow loading\n","plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md":"# Plugin Manifest Reference\n\nComplete reference for `plugin.json` configuration.\n\n## File Location\n\n**Required path**: `.claude-plugin/plugin.json`\n\nThe manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location.\n\n## Complete Field Reference\n\n### Core Fields\n\n#### name (required)\n\n**Type**: String\n**Format**: kebab-case\n**Example**: `\"test-automation-suite\"`\n\nThe unique identifier for the plugin. Used for:\n- Plugin identification in Claude Code\n- Conflict detection with other plugins\n- Command namespacing (optional)\n\n**Requirements**:\n- Must be unique across all installed plugins\n- Use only lowercase letters, numbers, and hyphens\n- No spaces or special characters\n- Start with a letter\n- End with a letter or number\n\n**Validation**:\n```javascript\n/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/\n```\n\n**Examples**:\n- ✅ Good: `api-tester`, `code-review`, `git-workflow-automation`\n- ❌ Bad: `API Tester`, `code_review`, `-git-workflow`, `test-`\n\n#### version\n\n**Type**: String\n**Format**: Semantic versioning (MAJOR.MINOR.PATCH)\n**Example**: `\"2.1.0\"`\n**Default**: `\"0.1.0\"` if not specified\n\nSemantic versioning guidelines:\n- **MAJOR**: Incompatible API changes, breaking changes\n- **MINOR**: New functionality, backward-compatible\n- **PATCH**: Bug fixes, backward-compatible\n\n**Pre-release versions**:\n- `\"1.0.0-alpha.1\"` - Alpha release\n- `\"1.0.0-beta.2\"` - Beta release\n- `\"1.0.0-rc.1\"` - Release candidate\n\n**Examples**:\n- `\"0.1.0\"` - Initial development\n- `\"1.0.0\"` - First stable release\n- `\"1.2.3\"` - Patch update to 1.2\n- `\"2.0.0\"` - Major version with breaking changes\n\n#### description\n\n**Type**: String\n**Length**: 50-200 characters recommended\n**Example**: `\"Automates code review workflows with style checks and automated feedback\"`\n\nBrief explanation of plugin purpose and functionality.\n\n**Best practices**:\n- Focus on what the plugin does, not how\n- Use active voice\n- Mention key features or benefits\n- Keep under 200 characters for marketplace display\n\n**Examples**:\n- ✅ \"Generates comprehensive test suites from code analysis and coverage reports\"\n- ✅ \"Integrates with Jira for automatic issue tracking and sprint management\"\n- ❌ \"A plugin that helps you do testing stuff\"\n- ❌ \"This is a very long description that goes on and on about every single feature...\"\n\n### Metadata Fields\n\n#### author\n\n**Type**: Object\n**Fields**: name (required), email (optional), url (optional)\n\n```json\n{\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"jane@example.com\",\n \"url\": \"https://janedeveloper.com\"\n }\n}\n```\n\n**Alternative format** (string only):\n```json\n{\n \"author\": \"Jane Developer (https://janedeveloper.com)\"\n}\n```\n\n**Use cases**:\n- Credit and attribution\n- Contact for support or questions\n- Marketplace display\n- Community recognition\n\n#### homepage\n\n**Type**: String (URL)\n**Example**: `\"https://docs.example.com/plugins/my-plugin\"`\n\nLink to plugin documentation or landing page.\n\n**Should point to**:\n- Plugin documentation site\n- Project homepage\n- Detailed usage guide\n- Installation instructions\n\n**Not for**:\n- Source code (use `repository` field)\n- Issue tracker (include in documentation)\n- Personal websites (use `author.url`)\n\n#### repository\n\n**Type**: String (URL) or Object\n**Example**: `\"https://github.com/user/plugin-name\"`\n\nSource code repository location.\n\n**String format**:\n```json\n{\n \"repository\": \"https://github.com/user/plugin-name\"\n}\n```\n\n**Object format** (detailed):\n```json\n{\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/user/plugin-name.git\",\n \"directory\": \"packages/plugin-name\"\n }\n}\n```\n\n**Use cases**:\n- Source code access\n- Issue reporting\n- Community contributions\n- Transparency and trust\n\n#### license\n\n**Type**: String\n**Format**: SPDX identifier\n**Example**: `\"MIT\"`\n\nSoftware license identifier.\n\n**Common licenses**:\n- `\"MIT\"` - Permissive, popular choice\n- `\"Apache-2.0\"` - Permissive with patent grant\n- `\"GPL-3.0\"` - Copyleft\n- `\"BSD-3-Clause\"` - Permissive\n- `\"ISC\"` - Permissive, similar to MIT\n- `\"UNLICENSED\"` - Proprietary, not open source\n\n**Full list**: https://spdx.org/licenses/\n\n**Multiple licenses**:\n```json\n{\n \"license\": \"(MIT OR Apache-2.0)\"\n}\n```\n\n#### keywords\n\n**Type**: Array of strings\n**Example**: `[\"testing\", \"automation\", \"ci-cd\", \"quality-assurance\"]`\n\nTags for plugin discovery and categorization.\n\n**Best practices**:\n- Use 5-10 keywords\n- Include functionality categories\n- Add technology names\n- Use common search terms\n- Avoid duplicating plugin name\n\n**Categories to consider**:\n- Functionality: `testing`, `debugging`, `documentation`, `deployment`\n- Technologies: `typescript`, `python`, `docker`, `aws`\n- Workflows: `ci-cd`, `code-review`, `git-workflow`\n- Domains: `web-development`, `data-science`, `devops`\n\n### Component Path Fields\n\n#### commands\n\n**Type**: String or Array of strings\n**Default**: `[\"./commands\"]`\n**Example**: `\"./cli-commands\"`\n\nAdditional directories or files containing command definitions.\n\n**Single path**:\n```json\n{\n \"commands\": \"./custom-commands\"\n}\n```\n\n**Multiple paths**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./experimental-commands\"\n ]\n}\n```\n\n**Behavior**: Supplements default `commands/` directory (does not replace)\n\n**Use cases**:\n- Organizing commands by category\n- Separating stable from experimental commands\n- Loading commands from shared locations\n\n#### agents\n\n**Type**: String or Array of strings\n**Default**: `[\"./agents\"]`\n**Example**: `\"./specialized-agents\"`\n\nAdditional directories or files containing agent definitions.\n\n**Format**: Same as `commands` field\n\n**Use cases**:\n- Grouping agents by specialization\n- Separating general-purpose from task-specific agents\n- Loading agents from plugin dependencies\n\n#### hooks\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `\"./hooks/hooks.json\"`\n\nHook configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"hooks\": \"./config/hooks.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 30\n }\n ]\n }\n ]\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Inline configuration (< 50 lines)\n- Complex plugins: External JSON file\n- Multiple hook sets: Separate files for different contexts\n\n#### mcpServers\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `./.mcp.json`\n\nMCP server configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\"\n }\n }\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Single inline server (< 20 lines)\n- Complex plugins: External `.mcp.json` file\n- Multiple servers: Always use external file\n\n## Path Resolution\n\n### Relative Path Rules\n\nAll paths in component fields must follow these rules:\n\n1. **Must be relative**: No absolute paths\n2. **Must start with `./`**: Indicates relative to plugin root\n3. **Cannot use `../`**: No parent directory navigation\n4. **Forward slashes only**: Even on Windows\n\n**Examples**:\n- ✅ `\"./commands\"`\n- ✅ `\"./src/commands\"`\n- ✅ `\"./configs/hooks.json\"`\n- ❌ `\"/Users/name/plugin/commands\"`\n- ❌ `\"commands\"` (missing `./`)\n- ❌ `\"../shared/commands\"`\n- ❌ `\".\\\\commands\"` (backslash)\n\n### Resolution Order\n\nWhen Claude Code loads components:\n\n1. **Default directories**: Scans standard locations first\n - `./commands/`\n - `./agents/`\n - `./skills/`\n - `./hooks/hooks.json`\n - `./.mcp.json`\n\n2. **Custom paths**: Scans paths specified in manifest\n - Paths from `commands` field\n - Paths from `agents` field\n - Files from `hooks` and `mcpServers` fields\n\n3. **Merge behavior**: Components from all locations load\n - No overwriting\n - All discovered components register\n - Name conflicts cause errors\n\n## Validation\n\n### Manifest Validation\n\nClaude Code validates the manifest on plugin load:\n\n**Syntax validation**:\n- Valid JSON format\n- No syntax errors\n- Correct field types\n\n**Field validation**:\n- `name` field present and valid format\n- `version` follows semantic versioning (if present)\n- Paths are relative with `./` prefix\n- URLs are valid (if present)\n\n**Component validation**:\n- Referenced paths exist\n- Hook and MCP configurations are valid\n- No circular dependencies\n\n### Common Validation Errors\n\n**Invalid name format**:\n```json\n{\n \"name\": \"My Plugin\" // ❌ Contains spaces\n}\n```\nFix: Use kebab-case\n```json\n{\n \"name\": \"my-plugin\" // ✅\n}\n```\n\n**Absolute path**:\n```json\n{\n \"commands\": \"/Users/name/commands\" // ❌ Absolute path\n}\n```\nFix: Use relative path\n```json\n{\n \"commands\": \"./commands\" // ✅\n}\n```\n\n**Missing ./ prefix**:\n```json\n{\n \"hooks\": \"hooks/hooks.json\" // ❌ No ./\n}\n```\nFix: Add ./ prefix\n```json\n{\n \"hooks\": \"./hooks/hooks.json\" // ✅\n}\n```\n\n**Invalid version**:\n```json\n{\n \"version\": \"1.0\" // ❌ Not semantic versioning\n}\n```\nFix: Use MAJOR.MINOR.PATCH\n```json\n{\n \"version\": \"1.0.0\" // ✅\n}\n```\n\n## Minimal vs. Complete Examples\n\n### Minimal Plugin\n\nBare minimum for a working plugin:\n\n```json\n{\n \"name\": \"hello-world\"\n}\n```\n\nRelies entirely on default directory discovery.\n\n### Recommended Plugin\n\nGood metadata for distribution:\n\n```json\n{\n \"name\": \"code-review-assistant\",\n \"version\": \"1.0.0\",\n \"description\": \"Automates code review with style checks and suggestions\",\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"jane@example.com\"\n },\n \"homepage\": \"https://docs.example.com/code-review\",\n \"repository\": \"https://github.com/janedev/code-review-assistant\",\n \"license\": \"MIT\",\n \"keywords\": [\"code-review\", \"automation\", \"quality\", \"ci-cd\"]\n}\n```\n\n### Complete Plugin\n\nFull configuration with all features:\n\n```json\n{\n \"name\": \"enterprise-devops\",\n \"version\": \"2.3.1\",\n \"description\": \"Comprehensive DevOps automation for enterprise CI/CD pipelines\",\n \"author\": {\n \"name\": \"DevOps Team\",\n \"email\": \"devops@company.com\",\n \"url\": \"https://company.com/devops\"\n },\n \"homepage\": \"https://docs.company.com/plugins/devops\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/company/devops-plugin.git\"\n },\n \"license\": \"Apache-2.0\",\n \"keywords\": [\n \"devops\",\n \"ci-cd\",\n \"automation\",\n \"kubernetes\",\n \"docker\",\n \"deployment\"\n ],\n \"commands\": [\n \"./commands\",\n \"./admin-commands\"\n ],\n \"agents\": \"./specialized-agents\",\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n## Best Practices\n\n### Metadata\n\n1. **Always include version**: Track changes and updates\n2. **Write clear descriptions**: Help users understand plugin purpose\n3. **Provide contact information**: Enable user support\n4. **Link to documentation**: Reduce support burden\n5. **Choose appropriate license**: Match project goals\n\n### Paths\n\n1. **Use defaults when possible**: Minimize configuration\n2. **Organize logically**: Group related components\n3. **Document custom paths**: Explain why non-standard layout used\n4. **Test path resolution**: Verify on multiple systems\n\n### Maintenance\n\n1. **Bump version on changes**: Follow semantic versioning\n2. **Update keywords**: Reflect new functionality\n3. **Keep description current**: Match actual capabilities\n4. **Maintain changelog**: Track version history\n5. **Update repository links**: Keep URLs current\n\n### Distribution\n\n1. **Complete metadata before publishing**: All fields filled\n2. **Test on clean install**: Verify plugin works without dev environment\n3. **Validate manifest**: Use validation tools\n4. **Include README**: Document installation and usage\n5. **Specify license file**: Include LICENSE file in plugin root\n","plugins/plugin-dev/skills/skill-development/SKILL.md":"---\nname: Skill Development\ndescription: This skill should be used when the user wants to \"create a skill\", \"add a skill to plugin\", \"write a new skill\", \"improve skill description\", \"organize skill content\", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.\nversion: 0.1.0\n---\n\n# Skill Development for Claude Code Plugins\n\nThis skill provides guidance for creating effective skills for Claude Code plugins.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Claude's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Claude from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\n**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. \"This skill should be used when...\" instead of \"Use this skill when...\").\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.\n\n- **When to include**: For documentation that Claude should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Claude produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Claude (Unlimited*)\n\n*Unlimited because scripts can be executed without reading into context window.\n\n## Skill Creation Process\n\nTo create a skill, follow the \"Skill Creation Process\" in order, skipping steps only if there is a clear reason why they are not applicable.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\n**For Claude Code plugins:** When building a hooks skill, the analysis shows:\n1. Developers repeatedly need to validate hooks.json and test hook scripts\n2. `scripts/validate-hook-schema.sh` and `scripts/test-hook.sh` utilities would be helpful\n3. `references/patterns.md` for detailed hook patterns to avoid bloating SKILL.md\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Create Skill Structure\n\nFor Claude Code plugins, create the skill directory structure:\n\n```bash\nmkdir -p plugin-name/skills/skill-name/{references,examples,scripts}\ntouch plugin-name/skills/skill-name/SKILL.md\n```\n\n**Note:** Unlike the generic skill-creator which uses `init_skill.py`, plugin skills are created directly in the plugin's `skills/` directory with a simpler manual structure.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-created or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAlso, delete any example files and directories not needed for the skill. Create only the directories you actually need (references/, examples/, scripts/).\n\n#### Update SKILL.md\n\n**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., \"To accomplish X, do Y\" rather than \"You should do X\" or \"If you need to do X\"). This maintains consistency and clarity for AI consumption.\n\n**Description (Frontmatter):** Use third-person format with specific trigger phrases:\n\n```yaml\n---\nname: Skill Name\ndescription: This skill should be used when the user asks to \"specific phrase 1\", \"specific phrase 2\", \"specific phrase 3\". Include exact phrases users would say that should trigger this skill. Be concrete and specific.\nversion: 0.1.0\n---\n```\n\n**Good description examples:**\n```yaml\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse hook\", \"validate tool use\", \"implement prompt-based hooks\", or mentions hook events (PreToolUse, PostToolUse, Stop).\n```\n\n**Bad description examples:**\n```yaml\ndescription: Use this skill when working with hooks. # Wrong person, vague\ndescription: Load when user needs hook help. # Not third person\ndescription: Provides hook guidance. # No trigger phrases\n```\n\nTo complete SKILL.md body, answer the following questions:\n\n1. What is the purpose of the skill, in a few sentences?\n2. When should the skill be used? (Include this in frontmatter description with specific triggers)\n3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.\n\n**Keep SKILL.md lean:** Target 1,500-2,000 words for the body. Move detailed content to references/:\n- Detailed patterns → `references/patterns.md`\n- Advanced techniques → `references/advanced.md`\n- Migration guides → `references/migration.md`\n- API references → `references/api-reference.md`\n\n**Reference resources in SKILL.md:**\n```markdown\n## Additional Resources\n\n### Reference Files\n\nFor detailed patterns and techniques, consult:\n- **`references/patterns.md`** - Common patterns\n- **`references/advanced.md`** - Advanced use cases\n\n### Example Files\n\nWorking examples in `examples/`:\n- **`example-script.sh`** - Working example\n```\n\n### Step 5: Validate and Test\n\n**For plugin skills, validation is different from generic skills:**\n\n1. **Check structure**: Skill directory in `plugin-name/skills/skill-name/`\n2. **Validate SKILL.md**: Has frontmatter with name and description\n3. **Check trigger phrases**: Description includes specific user queries\n4. **Verify writing style**: Body uses imperative/infinitive form, not second person\n5. **Test progressive disclosure**: SKILL.md is lean (~1,500-2,000 words), detailed content in references/\n6. **Check references**: All referenced files exist\n7. **Validate examples**: Examples are complete and correct\n8. **Test scripts**: Scripts are executable and work correctly\n\n**Use the skill-reviewer agent:**\n```\nAsk: \"Review my skill and check if it follows best practices\"\n```\n\nThe skill-reviewer agent will check description quality, content organization, and progressive disclosure.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n\n**Common improvements:**\n- Strengthen trigger phrases in description\n- Move long sections from SKILL.md to references/\n- Add missing examples or scripts\n- Clarify ambiguous instructions\n- Add edge case handling\n\n## Plugin-Specific Considerations\n\n### Skill Location in Plugins\n\nPlugin skills live in the plugin's `skills/` directory:\n\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n├── agents/\n└── skills/\n └── my-skill/\n ├── SKILL.md\n ├── references/\n ├── examples/\n └── scripts/\n```\n\n### Auto-Discovery\n\nClaude Code automatically discovers skills:\n- Scans `skills/` directory\n- Finds subdirectories containing `SKILL.md`\n- Loads skill metadata (name + description) always\n- Loads SKILL.md body when skill triggers\n- Loads references/examples when needed\n\n### No Packaging Needed\n\nPlugin skills are distributed as part of the plugin, not as separate ZIP files. Users get skills when they install the plugin.\n\n### Testing in Plugins\n\nTest skills by installing plugin locally:\n\n```bash\n# Test with --plugin-dir\ncc --plugin-dir /path/to/plugin\n\n# Ask questions that should trigger the skill\n# Verify skill loads correctly\n```\n\n## Examples from Plugin-Dev\n\nStudy the skills in this plugin as examples of best practices:\n\n**hook-development skill:**\n- Excellent trigger phrases: \"create a hook\", \"add a PreToolUse hook\", etc.\n- Lean SKILL.md (1,651 words)\n- 3 references/ files for detailed content\n- 3 examples/ of working hooks\n- 3 scripts/ utilities\n\n**agent-development skill:**\n- Strong triggers: \"create an agent\", \"agent frontmatter\", etc.\n- Focused SKILL.md (1,438 words)\n- References include the AI generation prompt from Claude Code\n- Complete agent examples\n\n**plugin-settings skill:**\n- Specific triggers: \"plugin settings\", \".local.md files\", \"YAML frontmatter\"\n- References show real implementations (multi-agent-swarm, ralph-wiggum)\n- Working parsing scripts\n\nEach demonstrates progressive disclosure and strong triggering.\n\n## Progressive Disclosure in Practice\n\n### What Goes in SKILL.md\n\n**Include (always loaded when skill triggers):**\n- Core concepts and overview\n- Essential procedures and workflows\n- Quick reference tables\n- Pointers to references/examples/scripts\n- Most common use cases\n\n**Keep under 3,000 words, ideally 1,500-2,000 words**\n\n### What Goes in references/\n\n**Move to references/ (loaded as needed):**\n- Detailed patterns and advanced techniques\n- Comprehensive API documentation\n- Migration guides\n- Edge cases and troubleshooting\n- Extensive examples and walkthroughs\n\n**Each reference file can be large (2,000-5,000+ words)**\n\n### What Goes in examples/\n\n**Working code examples:**\n- Complete, runnable scripts\n- Configuration files\n- Template files\n- Real-world usage examples\n\n**Users can copy and adapt these directly**\n\n### What Goes in scripts/\n\n**Utility scripts:**\n- Validation tools\n- Testing helpers\n- Parsing utilities\n- Automation scripts\n\n**Should be executable and documented**\n\n## Writing Style Requirements\n\n### Imperative/Infinitive Form\n\nWrite using verb-first instructions, not second person:\n\n**Correct (imperative):**\n```\nTo create a hook, define the event type.\nConfigure the MCP server with authentication.\nValidate settings before use.\n```\n\n**Incorrect (second person):**\n```\nYou should create a hook by defining the event type.\nYou need to configure the MCP server.\nYou must validate settings before use.\n```\n\n### Third-Person in Description\n\nThe frontmatter description must use third person:\n\n**Correct:**\n```yaml\ndescription: This skill should be used when the user asks to \"create X\", \"configure Y\"...\n```\n\n**Incorrect:**\n```yaml\ndescription: Use this skill when you want to create X...\ndescription: Load this skill when user asks...\n```\n\n### Objective, Instructional Language\n\nFocus on what to do, not who should do it:\n\n**Correct:**\n```\nParse the frontmatter using sed.\nExtract fields with grep.\nValidate values before use.\n```\n\n**Incorrect:**\n```\nYou can parse the frontmatter...\nClaude should extract fields...\nThe user might validate values...\n```\n\n## Validation Checklist\n\nBefore finalizing a skill:\n\n**Structure:**\n- [ ] SKILL.md file exists with valid YAML frontmatter\n- [ ] Frontmatter has `name` and `description` fields\n- [ ] Markdown body is present and substantial\n- [ ] Referenced files actually exist\n\n**Description Quality:**\n- [ ] Uses third person (\"This skill should be used when...\")\n- [ ] Includes specific trigger phrases users would say\n- [ ] Lists concrete scenarios (\"create X\", \"configure Y\")\n- [ ] Not vague or generic\n\n**Content Quality:**\n- [ ] SKILL.md body uses imperative/infinitive form\n- [ ] Body is focused and lean (1,500-2,000 words ideal, <5k max)\n- [ ] Detailed content moved to references/\n- [ ] Examples are complete and working\n- [ ] Scripts are executable and documented\n\n**Progressive Disclosure:**\n- [ ] Core concepts in SKILL.md\n- [ ] Detailed docs in references/\n- [ ] Working code in examples/\n- [ ] Utilities in scripts/\n- [ ] SKILL.md references these resources\n\n**Testing:**\n- [ ] Skill triggers on expected user queries\n- [ ] Content is helpful for intended tasks\n- [ ] No duplicated information across files\n- [ ] References load when needed\n\n## Common Mistakes to Avoid\n\n### Mistake 1: Weak Trigger Description\n\n❌ **Bad:**\n```yaml\ndescription: Provides guidance for working with hooks.\n```\n\n**Why bad:** Vague, no specific trigger phrases, not third person\n\n✅ **Good:**\n```yaml\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse hook\", \"validate tool use\", or mentions hook events. Provides comprehensive hooks API guidance.\n```\n\n**Why good:** Third person, specific phrases, concrete scenarios\n\n### Mistake 2: Too Much in SKILL.md\n\n❌ **Bad:**\n```\nskill-name/\n└── SKILL.md (8,000 words - everything in one file)\n```\n\n**Why bad:** Bloats context when skill loads, detailed content always loaded\n\n✅ **Good:**\n```\nskill-name/\n├── SKILL.md (1,800 words - core essentials)\n└── references/\n ├── patterns.md (2,500 words)\n └── advanced.md (3,700 words)\n```\n\n**Why good:** Progressive disclosure, detailed content loaded only when needed\n\n### Mistake 3: Second Person Writing\n\n❌ **Bad:**\n```markdown\nYou should start by reading the configuration file.\nYou need to validate the input.\nYou can use the grep tool to search.\n```\n\n**Why bad:** Second person, not imperative form\n\n✅ **Good:**\n```markdown\nStart by reading the configuration file.\nValidate the input before processing.\nUse the grep tool to search for patterns.\n```\n\n**Why good:** Imperative form, direct instructions\n\n### Mistake 4: Missing Resource References\n\n❌ **Bad:**\n```markdown\n# SKILL.md\n\n[Core content]\n\n[No mention of references/ or examples/]\n```\n\n**Why bad:** Claude doesn't know references exist\n\n✅ **Good:**\n```markdown\n# SKILL.md\n\n[Core content]\n\n## Additional Resources\n\n### Reference Files\n- **`references/patterns.md`** - Detailed patterns\n- **`references/advanced.md`** - Advanced techniques\n\n### Examples\n- **`examples/script.sh`** - Working example\n```\n\n**Why good:** Claude knows where to find additional information\n\n## Quick Reference\n\n### Minimal Skill\n\n```\nskill-name/\n└── SKILL.md\n```\n\nGood for: Simple knowledge, no complex resources needed\n\n### Standard Skill (Recommended)\n\n```\nskill-name/\n├── SKILL.md\n├── references/\n│ └── detailed-guide.md\n└── examples/\n └── working-example.sh\n```\n\nGood for: Most plugin skills with detailed documentation\n\n### Complete Skill\n\n```\nskill-name/\n├── SKILL.md\n├── references/\n│ ├── patterns.md\n│ └── advanced.md\n├── examples/\n│ ├── example1.sh\n│ └── example2.json\n└── scripts/\n └── validate.sh\n```\n\nGood for: Complex domains with validation utilities\n\n## Best Practices Summary\n\n✅ **DO:**\n- Use third-person in description (\"This skill should be used when...\")\n- Include specific trigger phrases (\"create X\", \"configure Y\")\n- Keep SKILL.md lean (1,500-2,000 words)\n- Use progressive disclosure (move details to references/)\n- Write in imperative/infinitive form\n- Reference supporting files clearly\n- Provide working examples\n- Create utility scripts for common operations\n- Study plugin-dev's skills as templates\n\n❌ **DON'T:**\n- Use second person anywhere\n- Have vague trigger conditions\n- Put everything in SKILL.md (>3,000 words without references/)\n- Write in second person (\"You should...\")\n- Leave resources unreferenced\n- Include broken or incomplete examples\n- Skip validation\n\n## Additional Resources\n\n### Study These Skills\n\nPlugin-dev's skills demonstrate best practices:\n- `../hook-development/` - Progressive disclosure, utilities\n- `../agent-development/` - AI-assisted creation, references\n- `../mcp-integration/` - Comprehensive references\n- `../plugin-settings/` - Real-world examples\n- `../command-development/` - Clear critical concepts\n- `../plugin-structure/` - Good organization\n\n### Reference Files\n\nFor complete skill-creator methodology:\n- **`references/skill-creator-original.md`** - Full original skill-creator content\n\n## Implementation Workflow\n\nTo create a skill for your plugin:\n\n1. **Understand use cases**: Identify concrete examples of skill usage\n2. **Plan resources**: Determine what scripts/references/examples needed\n3. **Create structure**: `mkdir -p skills/skill-name/{references,examples,scripts}`\n4. **Write SKILL.md**:\n - Frontmatter with third-person description and trigger phrases\n - Lean body (1,500-2,000 words) in imperative form\n - Reference supporting files\n5. **Add resources**: Create references/, examples/, scripts/ as needed\n6. **Validate**: Check description, writing style, organization\n7. **Test**: Verify skill loads on expected triggers\n8. **Iterate**: Improve based on usage\n\nFocus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.\n","plugins/plugin-dev/skills/skill-development/references/skill-creator-original.md":"---\nname: skill-creator\ndescription: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.\nlicense: Complete terms in LICENSE.txt\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Claude's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Claude from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\n**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. \"This skill should be used when...\" instead of \"Use this skill when...\").\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.\n\n- **When to include**: For documentation that Claude should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Claude produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Claude (Unlimited*)\n\n*Unlimited because scripts can be executed without reading into context window.\n\n## Skill Creation Process\n\nTo create a skill, follow the \"Skill Creation Process\" in order, skipping steps only if there is a clear reason why they are not applicable.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.\n\nUsage:\n\n```bash\nscripts/init_skill.py --path \n```\n\nThe script:\n\n- Creates the skill directory at the specified path\n- Generates a SKILL.md template with proper frontmatter and TODO placeholders\n- Creates example resource directories: `scripts/`, `references/`, and `assets/`\n- Adds example files in each directory that can be customized or deleted\n\nAfter initialization, customize or remove the generated SKILL.md and example files as needed.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAlso, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.\n\n#### Update SKILL.md\n\n**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., \"To accomplish X, do Y\" rather than \"You should do X\" or \"If you need to do X\"). This maintains consistency and clarity for AI consumption.\n\nTo complete SKILL.md, answer the following questions:\n\n1. What is the purpose of the skill, in a few sentences?\n2. When should the skill be used?\n3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.\n\n### Step 5: Packaging a Skill\n\nOnce the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:\n\n```bash\nscripts/package_skill.py \n```\n\nOptional output directory specification:\n\n```bash\nscripts/package_skill.py ./dist\n```\n\nThe packaging script will:\n\n1. **Validate** the skill automatically, checking:\n - YAML frontmatter format and required fields\n - Skill naming conventions and directory structure\n - Description completeness and quality\n - File organization and resource references\n\n2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.\n\nIf validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n","plugins/pr-review-toolkit/.claude-plugin/plugin.json":"","plugins/pr-review-toolkit/README.md":"","plugins/ralph-wiggum/.claude-plugin/plugin.json":"","plugins/ralph-wiggum/README.md":"","plugins/security-guidance/.claude-plugin/plugin.json":"","plugins/security-guidance/README.md":""},"files":{".claude-plugin/marketplace.json":"{\n \"$schema\": \"https://json.schemastore.org/claude-code-marketplace.json\",\n \"name\": \"claude-code-plugins\",\n \"version\": \"1.0.0\",\n \"description\": \"Bundled plugins for Claude Code including Agent SDK development tools, PR review toolkit, and commit workflows\",\n \"owner\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"plugins\": [\n {\n \"name\": \"agent-sdk-dev\",\n \"description\": \"Development kit for working with the Claude Agent SDK\",\n \"source\": \"./plugins/agent-sdk-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"claude-opus-4-5-migration\",\n \"description\": \"Migrate your code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"William Hu\",\n \"email\": \"whu@anthropic.com\"\n },\n \"source\": \"./plugins/claude-opus-4-5-migration\",\n \"category\": \"development\"\n },\n {\n \"name\": \"code-review\",\n \"description\": \"Automated code review for pull requests using multiple specialized agents with confidence-based scoring to filter false positives\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Boris Cherny\",\n \"email\": \"boris@anthropic.com\"\n },\n \"source\": \"./plugins/code-review\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"commit-commands\",\n \"description\": \"Commands for git commit workflows including commit, push, and PR creation\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"source\": \"./plugins/commit-commands\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"explanatory-output-style\",\n \"description\": \"Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Dickson Tsai\",\n \"email\": \"dickson@anthropic.com\"\n },\n \"source\": \"./plugins/explanatory-output-style\",\n \"category\": \"learning\"\n },\n {\n \"name\": \"feature-dev\",\n \"description\": \"Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Siddharth Bidasaria\",\n \"email\": \"sbidasaria@anthropic.com\"\n },\n \"source\": \"./plugins/feature-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"frontend-design\",\n \"description\": \"Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics.\",\n \"version\": \"1.1.0\",\n \"author\": {\n \"name\": \"Prithvi Rajasekaran & Alexander Bricken\",\n \"email\": \"prithvi@anthropic.com\"\n },\n \"source\": \"./plugins/frontend-design\",\n \"category\": \"development\"\n },\n {\n \"name\": \"hookify\",\n \"description\": \"Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. Define rules via simple markdown files.\",\n \"version\": \"0.1.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/hookify\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"learning-output-style\",\n \"description\": \"Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style)\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Boris Cherny\",\n \"email\": \"boris@anthropic.com\"\n },\n \"source\": \"./plugins/learning-output-style\",\n \"category\": \"learning\"\n },\n {\n \"name\": \"plugin-dev\",\n \"description\": \"Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.\",\n \"version\": \"0.1.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/plugin-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"pr-review-toolkit\",\n \"description\": \"Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"source\": \"./plugins/pr-review-toolkit\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"ralph-wiggum\",\n \"description\": \"Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly, seeing its previous work, until completion.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/ralph-wiggum\",\n \"category\": \"development\"\n },\n {\n \"name\": \"security-guidance\",\n \"description\": \"Security reminder hook that warns about potential security issues when editing files, including command injection, XSS, and unsafe code patterns\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"David Dworken\",\n \"email\": \"dworken@anthropic.com\"\n },\n \"source\": \"./plugins/security-guidance\",\n \"category\": \"security\"\n }\n ]\n}\n",".claude/commands/commit-push-pr.md":"---\nallowed-tools: Bash(git checkout --branch:*), Bash(git add:*), Bash(git status:*), Bash(git push:*), Bash(git commit:*), Bash(gh pr create:*)\ndescription: Commit, push, and open a PR\n---\n\n## Context\n\n- Current git status: !`git status`\n- Current git diff (staged and unstaged changes): !`git diff HEAD`\n- Current branch: !`git branch --show-current`\n\n## Your task\n\nBased on the above changes:\n1. Create a new branch if on main\n2. Create a single commit with an appropriate message\n3. Push the branch to origin\n4. Create a pull request using `gh pr create`\n5. You have the capability to call multiple tools in a single response. You MUST do all of the above in a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls.\n",".claude/commands/dedupe.md":"---\nallowed-tools: Bash(./scripts/gh.sh:*), Bash(./scripts/comment-on-duplicates.sh:*)\ndescription: Find duplicate GitHub issues\n---\n\nFind up to 3 likely duplicate issues for a given GitHub issue.\n\nTo do this, follow these steps precisely:\n\n1. Use an agent to check if the Github issue (a) is closed, (b) does not need to be deduped (eg. because it is broad product feedback without a specific solution, or positive feedback), or (c) already has a duplicates comment that you made earlier. If so, do not proceed.\n2. Use an agent to view a Github issue, and ask the agent to return a summary of the issue\n3. Then, launch 5 parallel agents to search Github for duplicates of this issue, using diverse keywords and search approaches, using the summary from #1\n4. Next, feed the results from #1 and #2 into another agent, so that it can filter out false positives, that are likely not actually duplicates of the original issue. If there are no duplicates remaining, do not proceed.\n5. Finally, use the comment script to post duplicates:\n ```\n ./scripts/comment-on-duplicates.sh --potential-duplicates \n ```\n\nNotes (be sure to tell this to your agents, too):\n\n- Use `./scripts/gh.sh` to interact with Github, rather than web fetch or raw `gh`. Examples:\n - `./scripts/gh.sh issue view 123` — view an issue\n - `./scripts/gh.sh issue view 123 --comments` — view with comments\n - `./scripts/gh.sh issue list --state open --limit 20` — list issues\n - `./scripts/gh.sh search issues \"query\" --limit 10` — search for issues\n- Do not use other tools, beyond `./scripts/gh.sh` and the comment script (eg. don't use other MCP servers, file edit, etc.)\n- Make a todo list first\n",".claude/commands/triage-issue.md":"---\nallowed-tools: Bash(./scripts/gh.sh:*),Bash(./scripts/edit-issue-labels.sh:*)\ndescription: Triage GitHub issues by analyzing and applying labels\n---\n\nYou're an issue triage assistant. Analyze the issue and manage labels.\n\nIMPORTANT: Don't post any comments or messages to the issue. Your only actions are adding or removing labels.\n\nContext:\n\n$ARGUMENTS\n\nTOOLS:\n- `./scripts/gh.sh` — wrapper for `gh` CLI. Only supports these subcommands and flags:\n - `./scripts/gh.sh label list` — fetch all available labels\n - `./scripts/gh.sh label list --limit 100` — fetch with limit\n - `./scripts/gh.sh issue view 123` — read issue title, body, and labels\n - `./scripts/gh.sh issue view 123 --comments` — read the conversation\n - `./scripts/gh.sh issue list --state open --limit 20` — list issues\n - `./scripts/gh.sh search issues \"query\"` — find similar or duplicate issues\n - `./scripts/gh.sh search issues \"query\" --limit 10` — search with limit\n- `./scripts/edit-issue-labels.sh --add-label LABEL --remove-label LABEL` — add or remove labels (issue number is read from the workflow event)\n\nTASK:\n\n1. Run `./scripts/gh.sh label list` to fetch the available labels. You may ONLY use labels from this list. Never invent new labels.\n2. Run `./scripts/gh.sh issue view ISSUE_NUMBER` to read the issue details.\n3. Run `./scripts/gh.sh issue view ISSUE_NUMBER --comments` to read the conversation.\n\n**If EVENT is \"issues\" (new issue):**\n\n4. First, check if this issue is actually about Claude Code.\n - Look for Claude Code signals in the issue BODY: a `Claude Code Version` field or `claude --version` output, references to the `claude` CLI command, terminal sessions, the VS Code/JetBrains extensions, `CLAUDE.md` files, `.claude/` directories, MCP servers, Cowork, Remote Control, or the web UI at claude.ai/code. If ANY such signal is present, this IS a Claude Code issue — proceed to step 5.\n - Only if NO Claude Code signals are present: check whether a different Anthropic product (claude.ai chat, Claude Desktop/Mobile apps, the raw Anthropic API/SDK, or account billing with no CLI involvement) is the *subject* of the complaint, not merely mentioned for context. If so, apply `invalid` and stop. If ambiguous, proceed to step 5 WITHOUT applying `invalid`.\n - The body text is authoritative. If a form dropdown (e.g. Platform) contradicts evidence in the body, trust the body — dropdowns are often mis-selected.\n\n5. Analyze and apply category labels:\n - Type (bug, enhancement, question, etc.)\n - Technical areas and platform\n - Check for duplicates with `./scripts/gh.sh search issues`. Only mark as duplicate of OPEN issues.\n\n6. Evaluate lifecycle labels:\n - `needs-repro` (bugs only, 7 days): Bug reports without clear steps to reproduce. A good repro has specific, followable steps that someone else could use to see the same issue.\n Do NOT apply if the user already provided error messages, logs, file paths, or a description of what they did. Don't require a specific format — narrative descriptions count.\n For model behavior issues (e.g. \"Claude does X when it should do Y\"), don't require traditional repro steps — examples and patterns are sufficient.\n - `needs-info` (bugs only, 7 days): The issue needs something from the community before it can progress — e.g. error messages, versions, environment details, or answers to follow-up questions. Don't apply to questions or enhancements.\n Do NOT apply if the user already provided version, environment, and error details. If the issue just needs engineering investigation, that's not `needs-info`.\n\n Issues with these labels are automatically closed after the timeout if there's no response.\n The goal is to avoid issues lingering without a clear next step.\n\n7. Apply all selected labels:\n `./scripts/edit-issue-labels.sh --add-label \"label1\" --add-label \"label2\"`\n\n**If EVENT is \"issue_comment\" (comment on existing issue):**\n\n4. Evaluate lifecycle labels based on the full conversation:\n - If the issue has `stale` or `autoclose`, remove the label — a new human comment means the issue is still active:\n `./scripts/edit-issue-labels.sh --remove-label \"stale\" --remove-label \"autoclose\"`\n - If the issue has `needs-repro` or `needs-info` and the missing information has now been provided, remove the label:\n `./scripts/edit-issue-labels.sh --remove-label \"needs-repro\"`\n - If the issue doesn't have lifecycle labels but clearly needs them (e.g., a maintainer asked for repro steps or more details), add the appropriate label.\n - Comments like \"+1\", \"me too\", \"same here\", or emoji reactions are NOT the missing information. Only remove `needs-repro` or `needs-info` when substantive details are actually provided.\n - Do NOT add or remove category labels (bug, enhancement, etc.) on comment events.\n\nGUIDELINES:\n- ONLY use labels from `./scripts/gh.sh label list` — never create or guess label names\n- DO NOT post any comments to the issue\n- Be conservative with lifecycle labels — only apply when clearly warranted\n- Only apply lifecycle labels (`needs-repro`, `needs-info`) to bugs — never to questions or enhancements\n- When in doubt, don't apply a lifecycle label — false positives are worse than missing labels\n- On new issues (EVENT \"issues\"), always apply exactly one of `bug`, `enhancement`, `question`, `invalid`, or `duplicate`. If unsure, pick the closest fit — an imperfect category label is better than none.\n- On comment events, it's okay to make no changes if nothing applies.\n","CLAUDE.md":"# CLAUDE.md\n\nGuidance for Claude Code and other coding agents working in this repository.\n\n## Security hardening for GitHub Actions\n\nWorkflow jobs in this repository that call Claude run with three protections.\nKeep them when you add or edit a workflow.\n\n1. **Egress-firewall runner.** The job has `runs-on: ubuntu-24.04-firewall`,\n a GitHub-hosted runner that filters the job's outbound network traffic. Do\n not move a job that calls Claude to another runner.\n2. **Network allow list.** `.github/egress-firewall.yaml` lists the hosts\n those jobs may reach, besides any that GitHub's firewall allows by default.\n Keep `mode: enforce`, which is what makes the firewall block the rest. Follow\n that file's header when you add a host.\n3. **Auto permission mode.** Every step that runs the Claude Code action\n (`uses: anthropics/claude-code-action`, or a local action with a\n `claude_args` input) passes `--permission-mode auto` in `claude_args`. A tool\n call that needs permission and that the allowed tools do not cover then runs\n only if Claude Code's safety review passes it. Allow only the tools the job\n needs, and keep any `--disallowedTools` list a step has. Use `claude-opus-4-6`\n or a newer model: on an older one Claude Code falls back to its default\n permission mode.\n\n`claude.yml` answers `@claude` mentions. The Claude Code action sets\n`--permission-mode acceptEdits` for those, and the `--permission-mode auto` in\nthe workflow's `claude_args`, which comes after it, replaces it.\n\n`.github/workflows/workflow-hardening.yml` fails when a job that runs the Claude\nCode action or mentions `ANTHROPIC_FEDERATION_RULE_ID` breaks protection 1 or 3,\nor when the allow list is missing, empty, not `mode: enforce`, or names a host\nwith `*`. It cannot see a job that calls Claude another way, so check new\nworkflows by hand too. If a job cannot meet protection 1 or 3, add it with the\nreason to the matching exemption table in\n`.github/scripts/check_workflow_hardening.py`. A job in `EXEMPT_FROM_AUTO_MODE`\nmust set no permission mode at all. Do not skip or weaken the check.\n\nKeep each workflow's `permissions:` block minimal, and never print tokens or\nenvironment variables in workflow logs.\n","mods/agents-md/.claude-plugin/plugin.json":"","mods/diff/.claude-plugin/plugin.json":"","mods/sec-default/.claude-plugin/plugin.json":"","mods/telemetry/.claude-plugin/plugin.json":"","plugins/README.md":"","plugins/agent-sdk-dev/.claude-plugin/plugin.json":"","plugins/agent-sdk-dev/README.md":"","plugins/claude-opus-4-5-migration/.claude-plugin/plugin.json":"","plugins/claude-opus-4-5-migration/README.md":"","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/SKILL.md":"---\nname: claude-opus-4-5-migration\ndescription: Migrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5. Use when the user wants to update their codebase, prompts, or API calls to use Opus 4.5. Handles model string updates and prompt adjustments for known Opus 4.5 behavioral differences. Does NOT migrate Haiku 4.5.\n---\n\n# Opus 4.5 Migration Guide\n\nOne-shot migration from Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5.\n\n## Migration Workflow\n\n1. Search codebase for model strings and API calls\n2. Update model strings to Opus 4.5 (see platform-specific strings below)\n3. Remove unsupported beta headers\n4. Add effort parameter set to `\"high\"` (see `references/effort.md`)\n5. Summarize all changes made\n6. Tell the user: \"If you encounter any issues with Opus 4.5, let me know and I can help adjust your prompts.\"\n\n## Model String Updates\n\nIdentify which platform the codebase uses, then replace model strings accordingly.\n\n### Unsupported Beta Headers\n\nRemove the `context-1m-2025-08-07` beta header if present—it is not yet supported with Opus 4.5. Leave a comment noting this:\n\n```python\n# Note: 1M context beta (context-1m-2025-08-07) not yet supported with Opus 4.5\n```\n\n### Target Model Strings (Opus 4.5)\n\n| Platform | Opus 4.5 Model String |\n|----------|----------------------|\n| Anthropic API (1P) | `claude-opus-4-5-20251101` |\n| AWS Bedrock | `anthropic.claude-opus-4-5-20251101-v1:0` |\n| Google Vertex AI | `claude-opus-4-5@20251101` |\n| Azure AI Foundry | `claude-opus-4-5-20251101` |\n\n### Source Model Strings to Replace\n\n| Source Model | Anthropic API (1P) | AWS Bedrock | Google Vertex AI |\n|--------------|-------------------|-------------|------------------|\n| Sonnet 4.0 | `claude-sonnet-4-20250514` | `anthropic.claude-sonnet-4-20250514-v1:0` | `claude-sonnet-4@20250514` |\n| Sonnet 4.5 | `claude-sonnet-4-5-20250929` | `anthropic.claude-sonnet-4-5-20250929-v1:0` | `claude-sonnet-4-5@20250929` |\n| Opus 4.1 | `claude-opus-4-1-20250422` | `anthropic.claude-opus-4-1-20250422-v1:0` | `claude-opus-4-1@20250422` |\n\n**Do NOT migrate**: Any Haiku models (e.g., `claude-haiku-4-5-20251001`).\n\n## Prompt Adjustments\n\nOpus 4.5 has known behavioral differences from previous models. **Only apply these fixes if the user explicitly requests them or reports a specific issue.** By default, just update model strings.\n\n**Integration guidelines**: When adding snippets, don't just append them to prompts. Integrate them thoughtfully:\n- Use XML tags (e.g., ``, ``) to organize additions\n- Match the style and structure of the existing prompt\n- Place snippets in logical locations (e.g., coding guidelines near other coding instructions)\n- If the prompt already uses XML tags, add new content within appropriate existing tags or create consistent new ones\n\n### 1. Tool Overtriggering\n\nOpus 4.5 is more responsive to system prompts. Aggressive language that prevented undertriggering on previous models may now cause overtriggering.\n\n**Apply if**: User reports tools being called too frequently or unnecessarily.\n\n**Find and soften**:\n- `CRITICAL:` → remove or soften\n- `You MUST...` → `You should...`\n- `ALWAYS do X` → `Do X`\n- `NEVER skip...` → `Don't skip...`\n- `REQUIRED` → remove or soften\n\nOnly apply to tool-triggering instructions. Leave other uses of emphasis alone.\n\n### 2. Over-Engineering Prevention\n\nOpus 4.5 tends to create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**Apply if**: User reports unwanted files, excessive abstraction, or unrequested features. Add the snippet from `references/prompt-snippets.md`.\n\n### 3. Code Exploration\n\nOpus 4.5 can be overly conservative about exploring code, proposing solutions without reading files.\n\n**Apply if**: User reports the model proposing fixes without inspecting relevant code. Add the snippet from `references/prompt-snippets.md`.\n\n### 4. Frontend Design\n\n**Apply if**: User requests improved frontend design quality or reports generic-looking outputs.\n\nAdd the frontend aesthetics snippet from `references/prompt-snippets.md`.\n\n### 5. Thinking Sensitivity\n\nWhen extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants. Extended thinking is enabled only if the API request contains a `thinking` parameter.\n\n**Apply if**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in request).\n\nReplace \"think\" with alternatives like \"consider,\" \"believe,\" or \"evaluate.\"\n\n## Reference\n\nSee `references/prompt-snippets.md` for the full text of each snippet to add.\n\nSee `references/effort.md` for configuring the effort parameter (only if user requests it).\n","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/effort.md":"# Effort Parameter (Beta)\n\n**Add effort set to `\"high\"` during migration.** This is the default configuration for best performance with Opus 4.5.\n\n## Overview\n\nEffort controls how eagerly Claude spends tokens. It affects all tokens: thinking, text responses, and function calls.\n\n| Effort | Use Case |\n|--------|----------|\n| `high` | Best performance, deep reasoning (default) |\n| `medium` | Balance of cost/latency vs. performance |\n| `low` | Simple, high-volume queries; significant token savings |\n\n## Implementation\n\nRequires beta flag `effort-2025-11-24` in API calls.\n\n**Python SDK:**\n```python\nresponse = client.messages.create(\n model=\"claude-opus-4-5-20251101\",\n max_tokens=1024,\n betas=[\"effort-2025-11-24\"],\n output_config={\n \"effort\": \"high\" # or \"medium\" or \"low\"\n },\n messages=[...]\n)\n```\n\n**TypeScript SDK:**\n```typescript\nconst response = await client.messages.create({\n model: \"claude-opus-4-5-20251101\",\n max_tokens: 1024,\n betas: [\"effort-2025-11-24\"],\n output_config: {\n effort: \"high\" // or \"medium\" or \"low\"\n },\n messages: [...]\n});\n```\n\n**Raw API:**\n```json\n{\n \"model\": \"claude-opus-4-5-20251101\",\n \"max_tokens\": 1024,\n \"anthropic-beta\": \"effort-2025-11-24\",\n \"output_config\": {\n \"effort\": \"high\"\n },\n \"messages\": [...]\n}\n```\n\n## Effort vs. Thinking Budget\n\nEffort is independent of thinking budget:\n\n- High effort + no thinking = more tokens, but no thinking tokens\n- High effort + 32k thinking = more tokens, but thinking capped at 32k\n\n## Recommendations\n\n1. First determine effort level, then set thinking budget\n2. Best performance: high effort + high thinking budget\n3. Cost/latency optimization: medium effort\n4. Simple high-volume queries: low effort\n","plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/prompt-snippets.md":"# Prompt Snippets for Opus 4.5\n\nOnly apply these snippets if the user explicitly requests them or reports a specific issue. By default, the migration should only update model strings.\n\n## 1. Tool Overtriggering\n\n**Problem**: Prompts designed to reduce undertriggering on previous models may cause Opus 4.5 to overtrigger.\n\n**When to add**: User reports tools being called too frequently or unnecessarily.\n\n**Solution**: Replace aggressive language with normal phrasing.\n\n| Before | After |\n|--------|-------|\n| `CRITICAL: You MUST use this tool when...` | `Use this tool when...` |\n| `ALWAYS call the search function before...` | `Call the search function before...` |\n| `You are REQUIRED to...` | `You should...` |\n| `NEVER skip this step` | `Don't skip this step` |\n\n## 2. Over-Engineering Prevention\n\n**Problem**: Opus 4.5 may create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**When to add**: User reports unwanted files, excessive abstraction, or unrequested features.\n\n**Snippet to add to system prompt**:\n\n```\n- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.\n- Don't add features, refactor code, or make \"improvements\" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.\n- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.\n- Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.\n```\n\n## 3. Code Exploration\n\n**Problem**: Opus 4.5 may propose solutions without reading code or make assumptions about unread files.\n\n**When to add**: User reports the model proposing fixes without inspecting relevant code.\n\n**Snippet to add to system prompt**:\n\n```\nALWAYS read and understand relevant files before proposing code edits. Do not speculate about code you have not inspected. If the user references a specific file/path, you MUST open and inspect it before explaining or proposing fixes. Be rigorous and persistent in searching code for key facts. Thoroughly review the style, conventions, and abstractions of the codebase before implementing new features or abstractions.\n```\n\n## 4. Frontend Design Quality\n\n**Problem**: Default frontend outputs may look generic (\"AI slop\" aesthetic).\n\n**When to add**: User requests improved frontend design quality or reports generic-looking outputs.\n\n**Snippet to add to system prompt**:\n\n```xml\n\nYou tend to converge toward generic, \"on distribution\" outputs. In frontend design, this creates what users call the \"AI slop\" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight.\n\nFocus on:\n- Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.\n- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.\n- Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.\n- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.\n\nAvoid generic AI-generated aesthetics:\n- Overused font families (Inter, Roboto, Arial, system fonts)\n- Clichéd color schemes (particularly purple gradients on white backgrounds)\n- Predictable layouts and component patterns\n- Cookie-cutter design that lacks context-specific character\n\nInterpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!\n\n```\n\n## 5. Thinking Sensitivity\n\n**Problem**: When extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants.\n\nExtended thinking is not enabled by default. It is only enabled if the API request contains a `thinking` parameter:\n```json\n\"thinking\": {\n \"type\": \"enabled\",\n \"budget_tokens\": 10000\n}\n```\n\n**When to apply**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in their request).\n\n**Solution**: Replace \"think\" with alternative words.\n\n| Before | After |\n|--------|-------|\n| `think about` | `consider` |\n| `think through` | `evaluate` |\n| `I think` | `I believe` |\n| `think carefully` | `consider carefully` |\n| `thinking` | `reasoning` / `considering` |\n\n## Usage Guidelines\n\n1. **Integrate thoughtfully** - Don't just append snippets; weave them into the existing prompt structure\n2. **Use XML tags** - Wrap additions in descriptive tags (e.g., ``, ``) that match or complement existing prompt structure\n3. **Match prompt style** - If the prompt is concise, trim the snippet; if verbose, keep full detail\n4. **Place logically** - Put coding snippets near other coding instructions, tool guidance near tool definitions, etc.\n5. **Preserve existing content** - Insert snippets without removing functional content\n6. **Summarize changes** - After migration, list all model string updates and prompt modifications made\n","plugins/code-review/.claude-plugin/plugin.json":"","plugins/code-review/README.md":"","plugins/commit-commands/.claude-plugin/plugin.json":"","plugins/commit-commands/README.md":"","plugins/explanatory-output-style/.claude-plugin/plugin.json":"","plugins/explanatory-output-style/README.md":"","plugins/feature-dev/.claude-plugin/plugin.json":"","plugins/feature-dev/README.md":"","plugins/frontend-design/.claude-plugin/plugin.json":"","plugins/frontend-design/README.md":"","plugins/frontend-design/skills/frontend-design/SKILL.md":"---\nname: frontend-design\ndescription: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.\nlicense: Complete terms in LICENSE.txt\n---\n\n# Frontend Design\n\nApproach this as the design lead at a design studio known for giving every client a distinct visual identity that is not mistaken for anyone else's. This client has already rejected proposals that felt cliché or templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take aesthetic risk if justified.\n\n## Ground your designs in the subject matter\n\nIf the brief does not identify what the product or subject matter is, identify it yourself before designing, and confirm with the client. You can come up with one concrete subject, the design's audience, and the design's primary job, as a proposal. If there's any information in your memory about the client's preferences or context about what they're building, use that as a hint. The subject's industry, subject matter, materials, and vernacular are where distinctive visual choices come from — a design for a toy for girls aged 8–11 will be very aesthetically different from a dashboard for financial analysts. Build with the brief's real content and subject matter throughout.\n\n## Design principles\n\nFor web designs, the hero is the first thing viewers will see. Open with the most characteristic thing in the subject's world, in the form that is most appropriate: a headline, an image, an animation, a live demo, an interactive moment, or other treatments. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the default treatment, so only use it if that's truly the best option.\n\nTypography carries the personality of the page. You don't need a different typeface for display or headline text and body content: use one family or two, and if two, make them clearly distinct.\n\nChoose your typefaces deliberately, not the default families you would reach for on any other project, and set a clear type scale following the default guidance of The Elements of Typographic Style with intentional weights, widths, and spacing. When type is used as a headline or visual element, use the type treatment itself as an active part of the design, not a neutral delivery vehicle for the content.\n\nDefault to line lengths of less than 80 characters. Serif typefaces can have slightly longer line lengths; give serif body text slightly more line-height than a sans-serif.\n\nAvoid these default typographic treatments; they are the commonest tells of a generated page:\n- Accenting just a single word or phrase in a headline, like putting one word in italic/bold or a different color.\n- Using all caps for labels.\n- Adding unnecessary typographic labels above content.\n\nVisual structure is information. Structural devices like outlines, borders, numbering, eyebrows, dividers, labels, etc., encode useful information about the content rather than decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence — like a stepped process or a timeline. Before adding numbered markers, check the content really is a sequence.\n\nUse non-user-triggered motion sparingly and deliberately, only to draw attention. A single orchestrated moment — one page-load sequence or one reveal — lands better than scattered effects; fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as AI-generated. Motion that answers a person's action (opening, expanding, confirming) is welcome when it shows what changed.\n\nConsider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy and placeholder content. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.\n\n## Process: plan, review against the brief, build, critique\n\nFor calibration, AI-generated design right now clusters around some traits:\n1. a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta or warm-clay accent (often near #D97757 — Anthropic's own Claude-interaction accent, so on a user's brief it reads as a tell);\n2. a near-black background with a single bright acid-green or vermilion accent;\n3. a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns;\n4. the SaaS-card kit: content chopped into identical rounded cards, one border-radius on everything regardless of hierarchy, the same soft grey shadow (rgba(0,0,0,.1)) under each, and gradient washes as decoration;\n5. template chrome that appears whatever the subject: a tracked-out ALL-CAPS eyebrow label above every heading; meta strings joined with middle dots ('A · B · C'); labels built as 'WORD — fragment' with a spaced em dash; tinted near-black (#0B0B0B, #111) standing in for black; a monospace face for small data labels; a '→' appended to link and button text.\n\nAll traits are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. As with a hired human designer, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.\n\nWork in two passes. First, brainstorm a short design plan based on the client's design brief: create a compact token system with color, type, layout, and principles.\n- Color: describe the core base palette as 4–6 named hex values.\n- Type: the typefaces and their roles.\n- Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Include alignment guidance; should the content be left aligned, center aligned, justified?\n- Principles: the high-level guidance for what makes this page unique.\n\nThen review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan.\n\nWhen writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and an element-based selector like .cta). This can happen often with padding/margin between sections.\n\n## Restraint and self-critique\n\nSpend your boldness in one place. Let one element be the memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected, visually accessible, harmonious color palettes. Critique your own work as you build, taking screenshots to review if your environment supports it — a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creatives have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.\n\n## More on writing in design\n\nWords appear in a design for one reason: to make it easier to understand and use. They are design content, not decoration. Bring the same intentionality and minimalism to copywriting that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.\n\nWrite from the end user's perspective. Name things by what users will understand in simple language, not by how the system is built. A user manages notifications, not webhook config. Describe what something is or does in plain terms rather than selling it. Being specific and legible to new users is always better than being clever.\n\nUse active voice as default. A CTA says exactly what happens when it is used: \"Save changes,\" not \"Submit.\" An action keeps the same name through the whole flow, so the button that says \"Publish\" produces a toast that says \"Published.\" The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.\n\nTreat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.\n\nKeep the tone conversational: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each written element do exactly one job.\n","plugins/hookify/.claude-plugin/plugin.json":"","plugins/hookify/README.md":"","plugins/hookify/skills/writing-rules/SKILL.md":"---\nname: Writing Hookify Rules\ndescription: This skill should be used when the user asks to \"create a hookify rule\", \"write a hook rule\", \"configure hookify\", \"add a hookify rule\", or needs guidance on hookify rule syntax and patterns.\nversion: 0.1.0\n---\n\n# Writing Hookify Rules\n\n## Overview\n\nHookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to show when those patterns match. Rules are stored in `.claude/hookify.{rule-name}.local.md` files.\n\n## Rule File Format\n\n### Basic Structure\n\n```markdown\n---\nname: rule-identifier\nenabled: true\nevent: bash|file|stop|prompt|all\npattern: regex-pattern-here\n---\n\nMessage to show Claude when this rule triggers.\nCan include markdown formatting, warnings, suggestions, etc.\n```\n\n### Frontmatter Fields\n\n**name** (required): Unique identifier for the rule\n- Use kebab-case: `warn-dangerous-rm`, `block-console-log`\n- Be descriptive and action-oriented\n- Start with verb: warn, prevent, block, require, check\n\n**enabled** (required): Boolean to activate/deactivate\n- `true`: Rule is active\n- `false`: Rule is disabled (won't trigger)\n- Can toggle without deleting rule\n\n**event** (required): Which hook event to trigger on\n- `bash`: Bash tool commands\n- `file`: Edit, Write, MultiEdit tools\n- `stop`: When agent wants to stop\n- `prompt`: When user submits a prompt\n- `all`: All events\n\n**action** (optional): What to do when rule matches\n- `warn`: Show message but allow operation (default)\n- `block`: Prevent operation (PreToolUse) or stop session (Stop events)\n- If omitted, defaults to `warn`\n\n**pattern** (simple format): Regex pattern to match\n- Used for simple single-condition rules\n- Matches against command (bash) or new_text (file)\n- Python regex syntax\n\n**Example:**\n```yaml\nevent: bash\npattern: rm\\s+-rf\n```\n\n### Advanced Format (Multiple Conditions)\n\nFor complex rules with multiple conditions:\n\n```markdown\n---\nname: warn-env-file-edits\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.env$\n - field: new_text\n operator: contains\n pattern: API_KEY\n---\n\nYou're adding an API key to a .env file. Ensure this file is in .gitignore!\n```\n\n**Condition fields:**\n- `field`: Which field to check\n - For bash: `command`\n - For file: `file_path`, `new_text`, `old_text`, `content`\n- `operator`: How to match\n - `regex_match`: Regex pattern matching\n - `contains`: Substring check\n - `equals`: Exact match\n - `not_contains`: Substring must NOT be present\n - `starts_with`: Prefix check\n - `ends_with`: Suffix check\n- `pattern`: Pattern or string to match\n\n**All conditions must match for rule to trigger.**\n\n## Message Body\n\nThe markdown content after frontmatter is shown to Claude when the rule triggers.\n\n**Good messages:**\n- Explain what was detected\n- Explain why it's problematic\n- Suggest alternatives or best practices\n- Use formatting for clarity (bold, lists, etc.)\n\n**Example:**\n```markdown\n⚠️ **Console.log detected!**\n\nYou're adding console.log to production code.\n\n**Why this matters:**\n- Debug logs shouldn't ship to production\n- Console.log can expose sensitive data\n- Impacts browser performance\n\n**Alternatives:**\n- Use a proper logging library\n- Remove before committing\n- Use conditional debug builds\n```\n\n## Event Type Guide\n\n### bash Events\n\nMatch Bash command patterns:\n\n```markdown\n---\nevent: bash\npattern: sudo\\s+|rm\\s+-rf|chmod\\s+777\n---\n\nDangerous command detected!\n```\n\n**Common patterns:**\n- Dangerous commands: `rm\\s+-rf`, `dd\\s+if=`, `mkfs`\n- Privilege escalation: `sudo\\s+`, `su\\s+`\n- Permission issues: `chmod\\s+777`, `chown\\s+root`\n\n### file Events\n\nMatch Edit/Write/MultiEdit operations:\n\n```markdown\n---\nevent: file\npattern: console\\.log\\(|eval\\(|innerHTML\\s*=\n---\n\nPotentially problematic code pattern detected!\n```\n\n**Match on different fields:**\n```markdown\n---\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.tsx?$\n - field: new_text\n operator: regex_match\n pattern: console\\.log\\(\n---\n\nConsole.log in TypeScript file!\n```\n\n**Common patterns:**\n- Debug code: `console\\.log\\(`, `debugger`, `print\\(`\n- Security risks: `eval\\(`, `innerHTML\\s*=`, `dangerouslySetInnerHTML`\n- Sensitive files: `\\.env$`, `credentials`, `\\.pem$`\n- Generated files: `node_modules/`, `dist/`, `build/`\n\n### stop Events\n\nMatch when agent wants to stop (completion checks):\n\n```markdown\n---\nevent: stop\npattern: .*\n---\n\nBefore stopping, verify:\n- [ ] Tests were run\n- [ ] Build succeeded\n- [ ] Documentation updated\n```\n\n**Use for:**\n- Reminders about required steps\n- Completion checklists\n- Process enforcement\n\n### prompt Events\n\nMatch user prompt content (advanced):\n\n```markdown\n---\nevent: prompt\nconditions:\n - field: user_prompt\n operator: contains\n pattern: deploy to production\n---\n\nProduction deployment checklist:\n- [ ] Tests passing?\n- [ ] Reviewed by team?\n- [ ] Monitoring ready?\n```\n\n## Pattern Writing Tips\n\n### Regex Basics\n\n**Literal characters:** Most characters match themselves\n- `rm` matches \"rm\"\n- `console.log` matches \"console.log\"\n\n**Special characters need escaping:**\n- `.` (any char) → `\\.` (literal dot)\n- `(` `)` → `\\(` `\\)` (literal parens)\n- `[` `]` → `\\[` `\\]` (literal brackets)\n\n**Common metacharacters:**\n- `\\s` - whitespace (space, tab, newline)\n- `\\d` - digit (0-9)\n- `\\w` - word character (a-z, A-Z, 0-9, _)\n- `.` - any character\n- `+` - one or more\n- `*` - zero or more\n- `?` - zero or one\n- `|` - OR\n\n**Examples:**\n```\nrm\\s+-rf Matches: rm -rf, rm -rf\nconsole\\.log\\( Matches: console.log(\n(eval|exec)\\( Matches: eval( or exec(\nchmod\\s+777 Matches: chmod 777, chmod 777\nAPI_KEY\\s*= Matches: API_KEY=, API_KEY =\n```\n\n### Testing Patterns\n\nTest regex patterns before using:\n\n```bash\npython3 -c \"import re; print(re.search(r'your_pattern', 'test text'))\"\n```\n\nOr use online regex testers (regex101.com with Python flavor).\n\n### Common Pitfalls\n\n**Too broad:**\n```yaml\npattern: log # Matches \"log\", \"login\", \"dialog\", \"catalog\"\n```\nBetter: `console\\.log\\(|logger\\.`\n\n**Too specific:**\n```yaml\npattern: rm -rf /tmp # Only matches exact path\n```\nBetter: `rm\\s+-rf`\n\n**Escaping issues:**\n- YAML quoted strings: `\"pattern\"` requires double backslashes `\\\\s`\n- YAML unquoted: `pattern: \\s` works as-is\n- **Recommendation**: Use unquoted patterns in YAML\n\n## File Organization\n\n**Location:** All rules in `.claude/` directory\n**Naming:** `.claude/hookify.{descriptive-name}.local.md`\n**Gitignore:** Add `.claude/*.local.md` to `.gitignore`\n\n**Good names:**\n- `hookify.dangerous-rm.local.md`\n- `hookify.console-log.local.md`\n- `hookify.require-tests.local.md`\n- `hookify.sensitive-files.local.md`\n\n**Bad names:**\n- `hookify.rule1.local.md` (not descriptive)\n- `hookify.md` (missing .local)\n- `danger.local.md` (missing hookify prefix)\n\n## Workflow\n\n### Creating a Rule\n\n1. Identify unwanted behavior\n2. Determine which tool is involved (Bash, Edit, etc.)\n3. Choose event type (bash, file, stop, etc.)\n4. Write regex pattern\n5. Create `.claude/hookify.{name}.local.md` file in project root\n6. Test immediately - rules are read dynamically on next tool use\n\n### Refining a Rule\n\n1. Edit the `.local.md` file\n2. Adjust pattern or message\n3. Test immediately - changes take effect on next tool use\n\n### Disabling a Rule\n\n**Temporary:** Set `enabled: false` in frontmatter\n**Permanent:** Delete the `.local.md` file\n\n## Examples\n\nSee `${CLAUDE_PLUGIN_ROOT}/examples/` for complete examples:\n- `dangerous-rm.local.md` - Block dangerous rm commands\n- `console-log-warning.local.md` - Warn about console.log\n- `sensitive-files-warning.local.md` - Warn about editing .env files\n\n## Quick Reference\n\n**Minimum viable rule:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: bash\npattern: dangerous_command\n---\n\nWarning message here\n```\n\n**Rule with conditions:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.ts$\n - field: new_text\n operator: contains\n pattern: any\n---\n\nWarning message\n```\n\n**Event types:**\n- `bash` - Bash commands\n- `file` - File edits\n- `stop` - Completion checks\n- `prompt` - User input\n- `all` - All events\n\n**Field options:**\n- Bash: `command`\n- File: `file_path`, `new_text`, `old_text`, `content`\n- Prompt: `user_prompt`\n\n**Operators:**\n- `regex_match`, `contains`, `equals`, `not_contains`, `starts_with`, `ends_with`\n","plugins/learning-output-style/.claude-plugin/plugin.json":"","plugins/learning-output-style/README.md":"","plugins/plugin-dev/README.md":"","plugins/plugin-dev/skills/agent-development/SKILL.md":"---\nname: Agent Development\ndescription: This skill should be used when the user asks to \"create an agent\", \"add an agent\", \"write a subagent\", \"agent frontmatter\", \"when to use description\", \"agent examples\", \"agent tools\", \"agent colors\", \"autonomous agent\", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.\nversion: 0.1.0\n---\n\n# Agent Development for Claude Code Plugins\n\n## Overview\n\nAgents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.\n\n**Key concepts:**\n- Agents are FOR autonomous work, commands are FOR user-initiated actions\n- Markdown file format with YAML frontmatter\n- Triggering via description field with examples\n- System prompt defines agent behavior\n- Model and color customization\n\n## Agent File Structure\n\n### Complete Format\n\n```markdown\n---\nname: agent-identifier\ndescription: Use this agent when [triggering conditions]. Examples:\n\n\nContext: [Situation description]\nuser: \"[User request]\"\nassistant: \"[How assistant should respond and use this agent]\"\n\n[Why this agent should be triggered]\n\n\n\n\n[Additional example...]\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Write\", \"Grep\"]\n---\n\nYou are [agent role description]...\n\n**Your Core Responsibilities:**\n1. [Responsibility 1]\n2. [Responsibility 2]\n\n**Analysis Process:**\n[Step-by-step workflow]\n\n**Output Format:**\n[What to return]\n```\n\n## Frontmatter Fields\n\n### name (required)\n\nAgent identifier used for namespacing and invocation.\n\n**Format:** lowercase, numbers, hyphens only\n**Length:** 3-50 characters\n**Pattern:** Must start and end with alphanumeric\n\n**Good examples:**\n- `code-reviewer`\n- `test-generator`\n- `api-docs-writer`\n- `security-analyzer`\n\n**Bad examples:**\n- `helper` (too generic)\n- `-agent-` (starts/ends with hyphen)\n- `my_agent` (underscores not allowed)\n- `ag` (too short, < 3 chars)\n\n### description (required)\n\nDefines when Claude should trigger this agent. **This is the most critical field.**\n\n**Must include:**\n1. Triggering conditions (\"Use this agent when...\")\n2. Multiple `` blocks showing usage\n3. Context, user request, and assistant response in each example\n4. `` explaining why agent triggers\n\n**Format:**\n```\nUse this agent when [conditions]. Examples:\n\n\nContext: [Scenario description]\nuser: \"[What user says]\"\nassistant: \"[How Claude should respond]\"\n\n[Why this agent is appropriate]\n\n\n\n[More examples...]\n```\n\n**Best practices:**\n- Include 2-4 concrete examples\n- Show proactive and reactive triggering\n- Cover different phrasings of same intent\n- Explain reasoning in commentary\n- Be specific about when NOT to use the agent\n\n### model (required)\n\nWhich model the agent should use.\n\n**Options:**\n- `inherit` - Use same model as parent (recommended)\n- `sonnet` - Claude Sonnet (balanced)\n- `opus` - Claude Opus (most capable, expensive)\n- `haiku` - Claude Haiku (fast, cheap)\n\n**Recommendation:** Use `inherit` unless agent needs specific model capabilities.\n\n### color (required)\n\nVisual identifier for agent in UI.\n\n**Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`\n\n**Guidelines:**\n- Choose distinct colors for different agents in same plugin\n- Use consistent colors for similar agent types\n- Blue/cyan: Analysis, review\n- Green: Success-oriented tasks\n- Yellow: Caution, validation\n- Red: Critical, security\n- Magenta: Creative, generation\n\n### tools (optional)\n\nRestrict agent to specific tools.\n\n**Format:** Array of tool names\n\n```yaml\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n```\n\n**Default:** If omitted, agent has access to all tools\n\n**Best practice:** Limit tools to minimum needed (principle of least privilege)\n\n**Common tool sets:**\n- Read-only analysis: `[\"Read\", \"Grep\", \"Glob\"]`\n- Code generation: `[\"Read\", \"Write\", \"Grep\"]`\n- Testing: `[\"Read\", \"Bash\", \"Grep\"]`\n- Full access: Omit field or use `[\"*\"]`\n\n## System Prompt Design\n\nThe markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.\n\n### Structure\n\n**Standard template:**\n```markdown\nYou are [role] specializing in [domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility]\n2. [Secondary responsibility]\n3. [Additional responsibilities...]\n\n**Analysis Process:**\n1. [Step one]\n2. [Step two]\n3. [Step three]\n[...]\n\n**Quality Standards:**\n- [Standard 1]\n- [Standard 2]\n\n**Output Format:**\nProvide results in this format:\n- [What to include]\n- [How to structure]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [How to handle]\n- [Edge case 2]: [How to handle]\n```\n\n### Best Practices\n\n✅ **DO:**\n- Write in second person (\"You are...\", \"You will...\")\n- Be specific about responsibilities\n- Provide step-by-step process\n- Define output format\n- Include quality standards\n- Address edge cases\n- Keep under 10,000 characters\n\n❌ **DON'T:**\n- Write in first person (\"I am...\", \"I will...\")\n- Be vague or generic\n- Omit process steps\n- Leave output format undefined\n- Skip quality guidance\n- Ignore error cases\n\n## Creating Agents\n\n### Method 1: AI-Assisted Generation\n\nUse this prompt pattern (extracted from Claude Code):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nRequirements:\n1. Extract core intent and responsibilities\n2. Design expert persona for the domain\n3. Create comprehensive system prompt with:\n - Clear behavioral boundaries\n - Specific methodologies\n - Edge case handling\n - Output format\n4. Create identifier (lowercase, hyphens, 3-50 chars)\n5. Write description with triggering conditions\n6. Include 2-3 blocks showing when to use\n\nReturn JSON with:\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are...\"\n}\n```\n\nThen convert to agent file format with frontmatter.\n\nSee `examples/agent-creation-prompt.md` for complete template.\n\n### Method 2: Manual Creation\n\n1. Choose agent identifier (3-50 chars, lowercase, hyphens)\n2. Write description with examples\n3. Select model (usually `inherit`)\n4. Choose color for visual identification\n5. Define tools (if restricting access)\n6. Write system prompt with structure above\n7. Save as `agents/agent-name.md`\n\n## Validation Rules\n\n### Identifier Validation\n\n```\n✅ Valid: code-reviewer, test-gen, api-analyzer-v2\n❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)\n```\n\n**Rules:**\n- 3-50 characters\n- Lowercase letters, numbers, hyphens only\n- Must start and end with alphanumeric\n- No underscores, spaces, or special characters\n\n### Description Validation\n\n**Length:** 10-5,000 characters\n**Must include:** Triggering conditions and examples\n**Best:** 200-1,000 characters with 2-4 examples\n\n### System Prompt Validation\n\n**Length:** 20-10,000 characters\n**Best:** 500-3,000 characters\n**Structure:** Clear responsibilities, process, output format\n\n## Agent Organization\n\n### Plugin Agents Directory\n\n```\nplugin-name/\n└── agents/\n ├── analyzer.md\n ├── reviewer.md\n └── generator.md\n```\n\nAll `.md` files in `agents/` are auto-discovered.\n\n### Namespacing\n\nAgents are namespaced automatically:\n- Single plugin: `agent-name`\n- With subdirectories: `plugin:subdir:agent-name`\n\n## Testing Agents\n\n### Test Triggering\n\nCreate test scenarios to verify agent triggers correctly:\n\n1. Write agent with specific triggering examples\n2. Use similar phrasing to examples in test\n3. Check Claude loads the agent\n4. Verify agent provides expected functionality\n\n### Test System Prompt\n\nEnsure system prompt is complete:\n\n1. Give agent typical task\n2. Check it follows process steps\n3. Verify output format is correct\n4. Test edge cases mentioned in prompt\n5. Confirm quality standards are met\n\n## Quick Reference\n\n### Minimal Agent\n\n```markdown\n---\nname: simple-agent\ndescription: Use this agent when... Examples: ...\nmodel: inherit\ncolor: blue\n---\n\nYou are an agent that [does X].\n\nProcess:\n1. [Step 1]\n2. [Step 2]\n\nOutput: [What to provide]\n```\n\n### Frontmatter Fields Summary\n\n| Field | Required | Format | Example |\n|-------|----------|--------|---------|\n| name | Yes | lowercase-hyphens | code-reviewer |\n| description | Yes | Text + examples | Use when... ... |\n| model | Yes | inherit/sonnet/opus/haiku | inherit |\n| color | Yes | Color name | blue |\n| tools | No | Array of tool names | [\"Read\", \"Grep\"] |\n\n### Best Practices\n\n**DO:**\n- ✅ Include 2-4 concrete examples in description\n- ✅ Write specific triggering conditions\n- ✅ Use `inherit` for model unless specific need\n- ✅ Choose appropriate tools (least privilege)\n- ✅ Write clear, structured system prompts\n- ✅ Test agent triggering thoroughly\n\n**DON'T:**\n- ❌ Use generic descriptions without examples\n- ❌ Omit triggering conditions\n- ❌ Give all agents same color\n- ❌ Grant unnecessary tool access\n- ❌ Write vague system prompts\n- ❌ Skip testing\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed guidance, consult:\n\n- **`references/system-prompt-design.md`** - Complete system prompt patterns\n- **`references/triggering-examples.md`** - Example formats and best practices\n- **`references/agent-creation-system-prompt.md`** - The exact prompt from Claude Code\n\n### Example Files\n\nWorking examples in `examples/`:\n\n- **`agent-creation-prompt.md`** - AI-assisted agent generation template\n- **`complete-agent-examples.md`** - Full agent examples for different use cases\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-agent.sh`** - Validate agent file structure\n- **`test-agent-trigger.sh`** - Test if agent triggers correctly\n\n## Implementation Workflow\n\nTo create an agent for a plugin:\n\n1. Define agent purpose and triggering conditions\n2. Choose creation method (AI-assisted or manual)\n3. Create `agents/agent-name.md` file\n4. Write frontmatter with all required fields\n5. Write system prompt following best practices\n6. Include 2-4 triggering examples in description\n7. Validate with `scripts/validate-agent.sh`\n8. Test triggering with real scenarios\n9. Document agent in plugin README\n\nFocus on clear triggering conditions and comprehensive system prompts for autonomous operation.\n","plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md":"# AI-Assisted Agent Generation Template\n\nUse this template to generate agents using Claude with the agent creation system prompt.\n\n## Usage Pattern\n\n### Step 1: Describe Your Agent Need\n\nThink about:\n- What task should the agent handle?\n- When should it be triggered?\n- Should it be proactive or reactive?\n- What are the key responsibilities?\n\n### Step 2: Use the Generation Prompt\n\nSend this to Claude (with the agent-creation-system-prompt loaded):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nReturn ONLY the JSON object, no other text.\n```\n\n**Replace [YOUR DESCRIPTION] with your agent requirements.**\n\n### Step 3: Claude Returns JSON\n\nClaude will return:\n\n```json\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are... **Your Core Responsibilities:**...\"\n}\n```\n\n### Step 4: Convert to Agent File\n\nCreate `agents/[identifier].md`:\n\n```markdown\n---\nname: [identifier from JSON]\ndescription: [whenToUse from JSON]\nmodel: inherit\ncolor: [choose: blue/cyan/green/yellow/magenta/red]\ntools: [\"Read\", \"Write\", \"Grep\"] # Optional: restrict tools\n---\n\n[systemPrompt from JSON]\n```\n\n## Example 1: Code Review Agent\n\n**Your request:**\n```\nI need an agent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be called after code is written and provide specific feedback.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"code-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\\n\\n\\nContext: User just implemented a new feature\\nuser: \\\"I've added the authentication feature\\\"\\nassistant: \\\"Great! Let me review the code quality.\\\"\\n\\nCode was written, trigger code-quality-reviewer agent for review.\\n\\nassistant: \\\"I'll use the code-quality-reviewer agent to analyze the changes.\\\"\\n\\n\\n\\nContext: User explicitly requests review\\nuser: \\\"Can you review my code for issues?\\\"\\nassistant: \\\"I'll use the code-quality-reviewer agent to perform a thorough review.\\\"\\n\\nExplicit review request triggers the agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer specializing in identifying issues in software implementations.\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues (readability, maintainability, performance)\\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\\n3. Check adherence to project best practices and coding standards\\n4. Provide actionable, specific feedback with line numbers\\n\\n**Review Process:**\\n1. Read the code changes using available tools\\n2. Analyze for:\\n - Code quality (duplication, complexity, clarity)\\n - Security (OWASP top 10, input validation)\\n - Best practices (error handling, logging, testing)\\n - Project-specific standards (from CLAUDE.md)\\n3. Identify issues with severity (critical/major/minor)\\n4. Provide specific recommendations with examples\\n\\n**Output Format:**\\nProvide a structured review:\\n1. Summary (2-3 sentences)\\n2. Critical Issues (must fix)\\n3. Major Issues (should fix)\\n4. Minor Issues (nice to fix)\\n5. Positive observations\\n6. Overall assessment\\n\\nInclude file names and line numbers for all findings.\"\n}\n```\n\n**You create:**\n\nFile: `agents/code-quality-reviewer.md`\n\n```markdown\n---\nname: code-quality-reviewer\ndescription: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode was written, trigger code-quality-reviewer agent for review.\n\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n - Code quality (duplication, complexity, clarity)\n - Security (OWASP top 10, input validation)\n - Best practices (error handling, logging, testing)\n - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings.\n```\n\n## Example 2: Test Generation Agent\n\n**Your request:**\n```\nCreate an agent that generates unit tests for code. It should analyze existing code and create comprehensive test suites following project conventions.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"test-generator\",\n \"whenToUse\": \"Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\\n\\n\\nContext: User wrote new functions without tests\\nuser: \\\"I've implemented the user authentication functions\\\"\\nassistant: \\\"Great! Let me generate tests for these functions.\\\"\\n\\nNew code without tests, proactively trigger test-generator.\\n\\nassistant: \\\"I'll use the test-generator agent to create comprehensive tests.\\\"\\n\",\n \"systemPrompt\": \"You are an expert test engineer specializing in creating comprehensive unit tests...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code to understand behavior\\n2. Generate test cases covering happy paths and edge cases\\n3. Follow project testing conventions\\n4. Ensure high code coverage\\n\\n**Test Generation Process:**\\n1. Read target code\\n2. Identify testable units (functions, classes, methods)\\n3. Design test cases (inputs, expected outputs, edge cases)\\n4. Generate tests following project patterns\\n5. Add assertions and error cases\\n\\n**Output Format:**\\nGenerate complete test files with:\\n- Test suite structure\\n- Setup/teardown if needed\\n- Descriptive test names\\n- Comprehensive assertions\"\n}\n```\n\n**You create:** `agents/test-generator.md` with the structure above.\n\n## Example 3: Documentation Agent\n\n**Your request:**\n```\nBuild an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs.\n```\n\n**Result:** Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation.\n\n## Tips for Effective Agent Generation\n\n### Be Specific in Your Request\n\n**Vague:**\n```\n\"I need an agent that helps with code\"\n```\n\n**Specific:**\n```\n\"I need an agent that reviews pull requests for type safety issues in TypeScript, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage\"\n```\n\n### Include Triggering Preferences\n\nTell Claude when the agent should activate:\n\n```\n\"Create an agent that generates tests. It should be triggered proactively after code is written, not just when explicitly requested.\"\n```\n\n### Mention Project Context\n\n```\n\"Create a code review agent. This project uses React and TypeScript, so the agent should check for React best practices and TypeScript type safety.\"\n```\n\n### Define Output Expectations\n\n```\n\"Create an agent that analyzes performance. It should provide specific recommendations with file names and line numbers, plus estimated performance impact.\"\n```\n\n## Validation After Generation\n\nAlways validate generated agents:\n\n```bash\n# Validate structure\n./scripts/validate-agent.sh agents/your-agent.md\n\n# Check triggering works\n# Test with scenarios from examples\n```\n\n## Iterating on Generated Agents\n\nIf generated agent needs improvement:\n\n1. Identify what's missing or wrong\n2. Manually edit the agent file\n3. Focus on:\n - Better examples in description\n - More specific system prompt\n - Clearer process steps\n - Better output format definition\n4. Re-validate\n5. Test again\n\n## Advantages of AI-Assisted Generation\n\n- **Comprehensive**: Claude includes edge cases and quality checks\n- **Consistent**: Follows proven patterns\n- **Fast**: Seconds vs manual writing\n- **Examples**: Auto-generates triggering examples\n- **Complete**: Provides full system prompt structure\n\n## When to Edit Manually\n\nEdit generated agents when:\n- Need very specific project patterns\n- Require custom tool combinations\n- Want unique persona or style\n- Integrating with existing agents\n- Need precise triggering conditions\n\nStart with generation, then refine manually for best results.\n","plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md":"# Complete Agent Examples\n\nFull, production-ready agent examples for common use cases. Use these as templates for your own agents.\n\n## Example 1: Code Review Agent\n\n**File:** `agents/code-reviewer.md`\n\n```markdown\n---\nname: code-reviewer\ndescription: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the payment processing feature\"\nassistant: \"Great! Let me review the implementation.\"\n\nCode written for payment processing (security-critical). Proactively trigger\ncode-reviewer agent to check for security issues and best practices.\n\nassistant: \"I'll use the code-reviewer agent to analyze the payment code.\"\n\n\n\nContext: User explicitly requests code review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a comprehensive review.\"\n\nExplicit code review request triggers the agent.\n\n\n\n\nContext: Before committing code\nuser: \"I'm ready to commit these changes\"\nassistant: \"Let me review them first.\"\n\nBefore commit, proactively review code quality.\n\nassistant: \"I'll use the code-reviewer agent to validate the changes.\"\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, complexity)\n2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.)\n3. Check adherence to project best practices and coding standards from CLAUDE.md\n4. Provide specific, actionable feedback with file and line number references\n5. Recognize and commend good practices\n\n**Code Review Process:**\n1. **Gather Context**: Use Glob to find recently modified files (git diff, git status)\n2. **Read Code**: Use Read tool to examine changed files\n3. **Analyze Quality**:\n - Check for code duplication (DRY principle)\n - Assess complexity and readability\n - Verify error handling\n - Check for proper logging\n4. **Security Analysis**:\n - Scan for injection vulnerabilities (SQL, command, XSS)\n - Check authentication and authorization\n - Verify input validation and sanitization\n - Look for hardcoded secrets or credentials\n5. **Best Practices**:\n - Follow project-specific standards from CLAUDE.md\n - Check naming conventions\n - Verify test coverage\n - Assess documentation\n6. **Categorize Issues**: Group by severity (critical/major/minor)\n7. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every issue includes file path and line number (e.g., `src/auth.ts:42`)\n- Issues categorized by severity with clear criteria\n- Recommendations are specific and actionable (not vague)\n- Include code examples in recommendations when helpful\n- Balance criticism with recognition of good practices\n\n**Output Format:**\n## Code Review Summary\n[2-3 sentence overview of changes and overall quality]\n\n## Critical Issues (Must Fix)\n- `src/file.ts:42` - [Issue description] - [Why critical] - [How to fix]\n\n## Major Issues (Should Fix)\n- `src/file.ts:15` - [Issue description] - [Impact] - [Recommendation]\n\n## Minor Issues (Consider Fixing)\n- `src/file.ts:88` - [Issue description] - [Suggestion]\n\n## Positive Observations\n- [Good practice 1]\n- [Good practice 2]\n\n## Overall Assessment\n[Final verdict and recommendations]\n\n**Edge Cases:**\n- No issues found: Provide positive validation, mention what was checked\n- Too many issues (>20): Group by type, prioritize top 10 critical/major\n- Unclear code intent: Note ambiguity and request clarification\n- Missing context (no CLAUDE.md): Apply general best practices\n- Large changeset: Focus on most impactful files first\n```\n\n## Example 2: Test Generator Agent\n\n**File:** `agents/test-generator.md`\n\n```markdown\n---\nname: test-generator\ndescription: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples:\n\n\nContext: User implemented functions without tests\nuser: \"I've added the data validation functions\"\nassistant: \"Let me generate tests for these.\"\n\nNew code without tests. Proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly requests tests\nuser: \"Generate unit tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: green\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n---\n\nYou are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.\n\n**Your Core Responsibilities:**\n1. Generate high-quality unit tests with excellent coverage\n2. Follow project testing conventions and patterns\n3. Include happy path, edge cases, and error scenarios\n4. Ensure tests are maintainable and clear\n\n**Test Generation Process:**\n1. **Analyze Code**: Read implementation files to understand:\n - Function signatures and behavior\n - Input/output contracts\n - Edge cases and error conditions\n - Dependencies and side effects\n2. **Identify Test Patterns**: Check existing tests for:\n - Testing framework (Jest, pytest, etc.)\n - File organization (test/ directory, *.test.ts, etc.)\n - Naming conventions\n - Setup/teardown patterns\n3. **Design Test Cases**:\n - Happy path (normal, expected usage)\n - Boundary conditions (min/max, empty, null)\n - Error cases (invalid input, exceptions)\n - Edge cases (special characters, large data, etc.)\n4. **Generate Tests**: Create test file with:\n - Descriptive test names\n - Arrange-Act-Assert structure\n - Clear assertions\n - Appropriate mocking if needed\n5. **Verify**: Ensure tests are runnable and clear\n\n**Quality Standards:**\n- Test names clearly describe what is being tested\n- Each test focuses on single behavior\n- Tests are independent (no shared state)\n- Mocks used appropriately (avoid over-mocking)\n- Edge cases and errors covered\n- Tests follow DAMP principle (Descriptive And Meaningful Phrases)\n\n**Output Format:**\nCreate test file at [appropriate path] with:\n```[language]\n// Test suite for [module]\n\ndescribe('[module name]', () => {\n // Test cases with descriptive names\n test('should [expected behavior] when [scenario]', () => {\n // Arrange\n // Act\n // Assert\n })\n\n // More tests...\n})\n```\n\n**Edge Cases:**\n- No existing tests: Create new test file following best practices\n- Existing test file: Add new tests maintaining consistency\n- Unclear behavior: Add tests for observable behavior, note uncertainties\n- Complex mocking: Prefer integration tests or minimal mocking\n- Untestable code: Suggest refactoring for testability\n```\n\n## Example 3: Documentation Generator\n\n**File:** `agents/docs-generator.md`\n\n```markdown\n---\nname: docs-generator\ndescription: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:\n\n\nContext: User implemented new public API\nuser: \"I've added the user management API endpoints\"\nassistant: \"Let me document these endpoints.\"\n\nNew public API needs documentation. Proactively trigger docs-generator.\n\nassistant: \"I'll use the docs-generator agent to create API documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Generate docs for this module\"\nassistant: \"I'll use the docs-generator agent to create comprehensive documentation.\"\n\nExplicit documentation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: cyan\ntools: [\"Read\", \"Write\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.\n\n**Your Core Responsibilities:**\n1. Generate accurate, clear documentation from code\n2. Follow project documentation standards\n3. Include examples and usage patterns\n4. Ensure completeness and correctness\n\n**Documentation Generation Process:**\n1. **Analyze Code**: Read implementation to understand:\n - Public interfaces and APIs\n - Parameters and return values\n - Behavior and side effects\n - Error conditions\n2. **Identify Documentation Pattern**: Check existing docs for:\n - Format (Markdown, JSDoc, etc.)\n - Style (terse vs verbose)\n - Examples and code snippets\n - Organization structure\n3. **Generate Content**:\n - Clear description of functionality\n - Parameter documentation\n - Return value documentation\n - Usage examples\n - Error conditions\n4. **Format**: Follow project conventions\n5. **Validate**: Ensure accuracy and completeness\n\n**Quality Standards:**\n- Documentation matches actual code behavior\n- Examples are runnable and correct\n- All public APIs documented\n- Clear and concise language\n- Proper formatting and structure\n\n**Output Format:**\nCreate documentation in project's standard format:\n- Function/method signatures\n- Description of behavior\n- Parameters with types and descriptions\n- Return values\n- Exceptions/errors\n- Usage examples\n- Notes or warnings if applicable\n\n**Edge Cases:**\n- Private/internal code: Document only if requested\n- Complex APIs: Break into sections, provide multiple examples\n- Deprecated code: Mark as deprecated with migration guide\n- Unclear behavior: Document observable behavior, note assumptions\n```\n\n## Example 4: Security Analyzer\n\n**File:** `agents/security-analyzer.md`\n\n```markdown\n---\nname: security-analyzer\ndescription: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples:\n\n\nContext: User implemented authentication logic\nuser: \"I've added JWT token validation\"\nassistant: \"Let me check the security.\"\n\nAuthentication code is security-critical. Proactively trigger security-analyzer.\n\nassistant: \"I'll use the security-analyzer agent to review for security vulnerabilities.\"\n\n\n\nContext: User requests security check\nuser: \"Check my code for security issues\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nExplicit security review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: red\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Identify security vulnerabilities (OWASP Top 10 and beyond)\n2. Analyze authentication and authorization logic\n3. Check input validation and sanitization\n4. Verify secure data handling and storage\n5. Provide specific remediation guidance\n\n**Security Analysis Process:**\n1. **Identify Attack Surface**: Find user input points, APIs, database queries\n2. **Check Common Vulnerabilities**:\n - Injection (SQL, command, XSS, etc.)\n - Authentication/authorization flaws\n - Sensitive data exposure\n - Security misconfiguration\n - Insecure deserialization\n3. **Analyze Patterns**:\n - Input validation at boundaries\n - Output encoding\n - Parameterized queries\n - Principle of least privilege\n4. **Assess Risk**: Categorize by severity and exploitability\n5. **Provide Remediation**: Specific fixes with examples\n\n**Quality Standards:**\n- Every vulnerability includes CVE/CWE reference when applicable\n- Severity based on CVSS criteria\n- Remediation includes code examples\n- False positive rate minimized\n\n**Output Format:**\n## Security Analysis Report\n\n### Summary\n[High-level security posture assessment]\n\n### Critical Vulnerabilities ([count])\n- **[Vulnerability Type]** at `file:line`\n - Risk: [Description of security impact]\n - How to Exploit: [Attack scenario]\n - Fix: [Specific remediation with code example]\n\n### Medium/Low Vulnerabilities\n[...]\n\n### Security Best Practices Recommendations\n[...]\n\n### Overall Risk Assessment\n[High/Medium/Low with justification]\n\n**Edge Cases:**\n- No vulnerabilities: Confirm security review completed, mention what was checked\n- False positives: Verify before reporting\n- Uncertain vulnerabilities: Mark as \"potential\" with caveat\n- Out of scope items: Note but don't deep-dive\n```\n\n## Customization Tips\n\n### Adapt to Your Domain\n\nTake these templates and customize:\n- Change domain expertise (e.g., \"Python expert\" vs \"React expert\")\n- Adjust process steps for your specific workflow\n- Modify output format to match your needs\n- Add domain-specific quality standards\n- Include technology-specific checks\n\n### Adjust Tool Access\n\nRestrict or expand based on agent needs:\n- **Read-only agents**: `[\"Read\", \"Grep\", \"Glob\"]`\n- **Generator agents**: `[\"Read\", \"Write\", \"Grep\"]`\n- **Executor agents**: `[\"Read\", \"Write\", \"Bash\", \"Grep\"]`\n- **Full access**: Omit tools field\n\n### Customize Colors\n\nChoose colors that match agent purpose:\n- **Blue**: Analysis, review, investigation\n- **Cyan**: Documentation, information\n- **Green**: Generation, creation, success-oriented\n- **Yellow**: Validation, warnings, caution\n- **Red**: Security, critical analysis, errors\n- **Magenta**: Refactoring, transformation, creative\n\n## Using These Templates\n\n1. Copy template that matches your use case\n2. Replace placeholders with your specifics\n3. Customize process steps for your domain\n4. Adjust examples to your triggering scenarios\n5. Validate with `scripts/validate-agent.sh`\n6. Test triggering with real scenarios\n7. Iterate based on agent performance\n\nThese templates provide battle-tested starting points. Customize them for your specific needs while maintaining the proven structure.\n","plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md":"# Agent Creation System Prompt\n\nThis is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.\n\n## The Prompt\n\n```\nYou are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.\n\n**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.\n\nWhen a user describes what they want an agent to do, you will:\n\n1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.\n\n2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.\n\n3. **Architect Comprehensive Instructions**: Develop a system prompt that:\n - Establishes clear behavioral boundaries and operational parameters\n - Provides specific methodologies and best practices for task execution\n - Anticipates edge cases and provides guidance for handling them\n - Incorporates any specific requirements or preferences mentioned by the user\n - Defines output format expectations when relevant\n - Aligns with project-specific coding standards and patterns from CLAUDE.md\n\n4. **Optimize for Performance**: Include:\n - Decision-making frameworks appropriate to the domain\n - Quality control mechanisms and self-verification steps\n - Efficient workflow patterns\n - Clear escalation or fallback strategies\n\n5. **Create Identifier**: Design a concise, descriptive identifier that:\n - Uses lowercase letters, numbers, and hyphens only\n - Is typically 2-4 words joined by hyphens\n - Clearly indicates the agent's primary function\n - Is memorable and easy to type\n - Avoids generic terms like \"helper\" or \"assistant\"\n\n6. **Example agent descriptions**:\n - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.\n - Examples should be of the form:\n \n Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.\n user: \"Please write a function that checks if a number is prime\"\n assistant: \"Here is the relevant function: \"\n \n \n Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.\n \n assistant: \"Now let me use the code-reviewer agent to review the code\"\n \n - If the user mentioned or implied that the agent should be used proactively, you should include examples of this.\n - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.\n\nYour output must be a valid JSON object with exactly these fields:\n{\n \"identifier\": \"A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')\",\n \"whenToUse\": \"A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.\",\n \"systemPrompt\": \"The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness\"\n}\n\nKey principles for your system prompts:\n- Be specific rather than generic - avoid vague instructions\n- Include concrete examples when they would clarify behavior\n- Balance comprehensiveness with clarity - every instruction should add value\n- Ensure the agent has enough context to handle variations of the core task\n- Make the agent proactive in seeking clarification when needed\n- Build in quality assurance and self-correction mechanisms\n\nRemember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.\n```\n\n## Usage Pattern\n\nUse this prompt to generate agent configurations:\n\n```markdown\n**User input:** \"I need an agent that reviews pull requests for code quality issues\"\n\n**You send to Claude with the system prompt above:**\nCreate an agent configuration based on this request: \"I need an agent that reviews pull requests for code quality issues\"\n\n**Claude returns JSON:**\n{\n \"identifier\": \"pr-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\\n\\n\\nContext: User has created a PR and wants quality review\\nuser: \\\"Can you review PR #123 for code quality?\\\"\\nassistant: \\\"I'll use the pr-quality-reviewer agent to analyze the PR.\\\"\\n\\nPR review request triggers the pr-quality-reviewer agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues\\n2. Check adherence to best practices\\n...\"\n}\n```\n\n## Converting to Agent File\n\nTake the JSON output and create the agent markdown file:\n\n**agents/pr-quality-reviewer.md:**\n```markdown\n---\nname: pr-quality-reviewer\ndescription: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n\nPR review request triggers the pr-quality-reviewer agent.\n\n\n\nmodel: inherit\ncolor: blue\n---\n\nYou are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n...\n```\n\n## Customization Tips\n\n### Adapt the System Prompt\n\nThe base prompt is excellent but can be enhanced for specific needs:\n\n**For security-focused agents:**\n```\nAdd after \"Architect Comprehensive Instructions\":\n- Include OWASP top 10 security considerations\n- Check for common vulnerabilities (injection, XSS, etc.)\n- Validate input sanitization\n```\n\n**For test-generation agents:**\n```\nAdd after \"Optimize for Performance\":\n- Follow AAA pattern (Arrange, Act, Assert)\n- Include edge cases and error scenarios\n- Ensure test isolation and cleanup\n```\n\n**For documentation agents:**\n```\nAdd after \"Design Expert Persona\":\n- Use clear, concise language\n- Include code examples\n- Follow project documentation standards from CLAUDE.md\n```\n\n## Best Practices from Internal Implementation\n\n### 1. Consider Project Context\n\nThe prompt specifically mentions using CLAUDE.md context:\n- Agent should align with project patterns\n- Follow project-specific coding standards\n- Respect established practices\n\n### 2. Proactive Agent Design\n\nInclude examples showing proactive usage:\n```\n\nContext: After writing code, agent should review proactively\nuser: \"Please write a function...\"\nassistant: \"[Writes function]\"\n\nCode written, now use review agent proactively.\n\nassistant: \"Now let me review this code with the code-reviewer agent\"\n\n```\n\n### 3. Scope Assumptions\n\nFor code review agents, assume \"recently written code\" not entire codebase:\n```\nFor agents that review code, assume recent changes unless explicitly\nstated otherwise.\n```\n\n### 4. Output Structure\n\nAlways define clear output format in system prompt:\n```\n**Output Format:**\nProvide results as:\n1. Summary (2-3 sentences)\n2. Detailed findings (bullet points)\n3. Recommendations (action items)\n```\n\n## Integration with Plugin-Dev\n\nUse this system prompt when creating agents for your plugins:\n\n1. Take user request for agent functionality\n2. Feed to Claude with this system prompt\n3. Get JSON output (identifier, whenToUse, systemPrompt)\n4. Convert to agent markdown file with frontmatter\n5. Validate with agent validation rules\n6. Test triggering conditions\n7. Add to plugin's `agents/` directory\n\nThis provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.\n","plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md":"# System Prompt Design Patterns\n\nComplete guide to writing effective agent system prompts that enable autonomous, high-quality operation.\n\n## Core Structure\n\nEvery agent system prompt should follow this proven structure:\n\n```markdown\nYou are [specific role] specializing in [specific domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility - the main task]\n2. [Secondary responsibility - supporting task]\n3. [Additional responsibilities as needed]\n\n**[Task Name] Process:**\n1. [First concrete step]\n2. [Second concrete step]\n3. [Continue with clear steps]\n[...]\n\n**Quality Standards:**\n- [Standard 1 with specifics]\n- [Standard 2 with specifics]\n- [Standard 3 with specifics]\n\n**Output Format:**\nProvide results structured as:\n- [Component 1]\n- [Component 2]\n- [Include specific formatting requirements]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [Specific handling approach]\n- [Edge case 2]: [Specific handling approach]\n```\n\n## Pattern 1: Analysis Agents\n\nFor agents that analyze code, PRs, or documentation:\n\n```markdown\nYou are an expert [domain] analyzer specializing in [specific analysis type].\n\n**Your Core Responsibilities:**\n1. Thoroughly analyze [what] for [specific issues]\n2. Identify [patterns/problems/opportunities]\n3. Provide actionable recommendations\n\n**Analysis Process:**\n1. **Gather Context**: Read [what] using available tools\n2. **Initial Scan**: Identify obvious [issues/patterns]\n3. **Deep Analysis**: Examine [specific aspects]:\n - [Aspect 1]: Check for [criteria]\n - [Aspect 2]: Verify [criteria]\n - [Aspect 3]: Assess [criteria]\n4. **Synthesize Findings**: Group related issues\n5. **Prioritize**: Rank by [severity/impact/urgency]\n6. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every finding includes file:line reference\n- Issues categorized by severity (critical/major/minor)\n- Recommendations are specific and actionable\n- Positive observations included for balance\n\n**Output Format:**\n## Summary\n[2-3 sentence overview]\n\n## Critical Issues\n- [file:line] - [Issue description] - [Recommendation]\n\n## Major Issues\n[...]\n\n## Minor Issues\n[...]\n\n## Recommendations\n[...]\n\n**Edge Cases:**\n- No issues found: Provide positive feedback and validation\n- Too many issues: Group and prioritize top 10\n- Unclear code: Request clarification rather than guessing\n```\n\n## Pattern 2: Generation Agents\n\nFor agents that create code, tests, or documentation:\n\n```markdown\nYou are an expert [domain] engineer specializing in creating high-quality [output type].\n\n**Your Core Responsibilities:**\n1. Generate [what] that meets [quality standards]\n2. Follow [specific conventions/patterns]\n3. Ensure [correctness/completeness/clarity]\n\n**Generation Process:**\n1. **Understand Requirements**: Analyze what needs to be created\n2. **Gather Context**: Read existing [code/docs/tests] for patterns\n3. **Design Structure**: Plan [architecture/organization/flow]\n4. **Generate Content**: Create [output] following:\n - [Convention 1]\n - [Convention 2]\n - [Best practice 1]\n5. **Validate**: Verify [correctness/completeness]\n6. **Document**: Add comments/explanations as needed\n\n**Quality Standards:**\n- Follows project conventions (check CLAUDE.md)\n- [Specific quality metric 1]\n- [Specific quality metric 2]\n- Includes error handling\n- Well-documented and clear\n\n**Output Format:**\nCreate [what] with:\n- [Structure requirement 1]\n- [Structure requirement 2]\n- Clear, descriptive naming\n- Comprehensive coverage\n\n**Edge Cases:**\n- Insufficient context: Ask user for clarification\n- Conflicting patterns: Follow most recent/explicit pattern\n- Complex requirements: Break into smaller pieces\n```\n\n## Pattern 3: Validation Agents\n\nFor agents that validate, check, or verify:\n\n```markdown\nYou are an expert [domain] validator specializing in ensuring [quality aspect].\n\n**Your Core Responsibilities:**\n1. Validate [what] against [criteria]\n2. Identify violations and issues\n3. Provide clear pass/fail determination\n\n**Validation Process:**\n1. **Load Criteria**: Understand validation requirements\n2. **Scan Target**: Read [what] needs validation\n3. **Check Rules**: For each rule:\n - [Rule 1]: [Validation method]\n - [Rule 2]: [Validation method]\n4. **Collect Violations**: Document each failure with details\n5. **Assess Severity**: Categorize issues\n6. **Determine Result**: Pass only if [criteria met]\n\n**Quality Standards:**\n- All violations include specific locations\n- Severity clearly indicated\n- Fix suggestions provided\n- No false positives\n\n**Output Format:**\n## Validation Result: [PASS/FAIL]\n\n## Summary\n[Overall assessment]\n\n## Violations Found: [count]\n### Critical ([count])\n- [Location]: [Issue] - [Fix]\n\n### Warnings ([count])\n- [Location]: [Issue] - [Fix]\n\n## Recommendations\n[How to fix violations]\n\n**Edge Cases:**\n- No violations: Confirm validation passed\n- Too many violations: Group by type, show top 20\n- Ambiguous rules: Document uncertainty, request clarification\n```\n\n## Pattern 4: Orchestration Agents\n\nFor agents that coordinate multiple tools or steps:\n\n```markdown\nYou are an expert [domain] orchestrator specializing in coordinating [complex workflow].\n\n**Your Core Responsibilities:**\n1. Coordinate [multi-step process]\n2. Manage [resources/tools/dependencies]\n3. Ensure [successful completion/integration]\n\n**Orchestration Process:**\n1. **Plan**: Understand full workflow and dependencies\n2. **Prepare**: Set up prerequisites\n3. **Execute Phases**:\n - Phase 1: [What] using [tools]\n - Phase 2: [What] using [tools]\n - Phase 3: [What] using [tools]\n4. **Monitor**: Track progress and handle failures\n5. **Verify**: Confirm successful completion\n6. **Report**: Provide comprehensive summary\n\n**Quality Standards:**\n- Each phase completes successfully\n- Errors handled gracefully\n- Progress reported to user\n- Final state verified\n\n**Output Format:**\n## Workflow Execution Report\n\n### Completed Phases\n- [Phase]: [Result]\n\n### Results\n- [Output 1]\n- [Output 2]\n\n### Next Steps\n[If applicable]\n\n**Edge Cases:**\n- Phase failure: Attempt retry, then report and stop\n- Missing dependencies: Request from user\n- Timeout: Report partial completion\n```\n\n## Writing Style Guidelines\n\n### Tone and Voice\n\n**Use second person (addressing the agent):**\n```\n✅ You are responsible for...\n✅ You will analyze...\n✅ Your process should...\n\n❌ The agent is responsible for...\n❌ This agent will analyze...\n❌ I will analyze...\n```\n\n### Clarity and Specificity\n\n**Be specific, not vague:**\n```\n✅ Check for SQL injection by examining all database queries for parameterization\n❌ Look for security issues\n\n✅ Provide file:line references for each finding\n❌ Show where issues are\n\n✅ Categorize as critical (security), major (bugs), or minor (style)\n❌ Rate the severity of issues\n```\n\n### Actionable Instructions\n\n**Give concrete steps:**\n```\n✅ Read the file using the Read tool, then search for patterns using Grep\n❌ Analyze the code\n\n✅ Generate test file at test/path/to/file.test.ts\n❌ Create tests\n```\n\n## Common Pitfalls\n\n### ❌ Vague Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Help the user with their code\n2. Provide assistance\n3. Be helpful\n```\n\n**Why bad:** Not specific enough to guide behavior.\n\n### ✅ Specific Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Analyze TypeScript code for type safety issues\n2. Identify missing type annotations and improper 'any' usage\n3. Recommend specific type improvements with examples\n```\n\n### ❌ Missing Process Steps\n\n```markdown\nAnalyze the code and provide feedback.\n```\n\n**Why bad:** Agent doesn't know HOW to analyze.\n\n### ✅ Clear Process\n\n```markdown\n**Analysis Process:**\n1. Read code files using Read tool\n2. Scan for type annotations on all functions\n3. Check for 'any' type usage\n4. Verify generic type parameters\n5. List findings with file:line references\n```\n\n### ❌ Undefined Output\n\n```markdown\nProvide a report.\n```\n\n**Why bad:** Agent doesn't know what format to use.\n\n### ✅ Defined Output Format\n\n```markdown\n**Output Format:**\n## Type Safety Report\n\n### Summary\n[Overview of findings]\n\n### Issues Found\n- `file.ts:42` - Missing return type on `processData`\n- `utils.ts:15` - Unsafe 'any' usage in parameter\n\n### Recommendations\n[Specific fixes with examples]\n```\n\n## Length Guidelines\n\n### Minimum Viable Agent\n\n**~500 words minimum:**\n- Role description\n- 3 core responsibilities\n- 5-step process\n- Output format\n\n### Standard Agent\n\n**~1,000-2,000 words:**\n- Detailed role and expertise\n- 5-8 responsibilities\n- 8-12 process steps\n- Quality standards\n- Output format\n- 3-5 edge cases\n\n### Comprehensive Agent\n\n**~2,000-5,000 words:**\n- Complete role with background\n- Comprehensive responsibilities\n- Detailed multi-phase process\n- Extensive quality standards\n- Multiple output formats\n- Many edge cases\n- Examples within system prompt\n\n**Avoid > 10,000 words:** Too long, diminishing returns.\n\n## Testing System Prompts\n\n### Test Completeness\n\nCan the agent handle these based on system prompt alone?\n\n- [ ] Typical task execution\n- [ ] Edge cases mentioned\n- [ ] Error scenarios\n- [ ] Unclear requirements\n- [ ] Large/complex inputs\n- [ ] Empty/missing inputs\n\n### Test Clarity\n\nRead the system prompt and ask:\n\n- Can another developer understand what this agent does?\n- Are process steps clear and actionable?\n- Is output format unambiguous?\n- Are quality standards measurable?\n\n### Iterate Based on Results\n\nAfter testing agent:\n1. Identify where it struggled\n2. Add missing guidance to system prompt\n3. Clarify ambiguous instructions\n4. Add process steps for edge cases\n5. Re-test\n\n## Conclusion\n\nEffective system prompts are:\n- **Specific**: Clear about what and how\n- **Structured**: Organized with clear sections\n- **Complete**: Covers normal and edge cases\n- **Actionable**: Provides concrete steps\n- **Testable**: Defines measurable standards\n\nUse the patterns above as templates, customize for your domain, and iterate based on agent performance.\n","plugins/plugin-dev/skills/agent-development/references/triggering-examples.md":"# Agent Triggering Examples: Best Practices\n\nComplete guide to writing effective `` blocks in agent descriptions for reliable triggering.\n\n## Example Block Format\n\nThe standard format for triggering examples:\n\n```markdown\n\nContext: [Describe the situation - what led to this interaction]\nuser: \"[Exact user message or request]\"\nassistant: \"[How Claude should respond before triggering]\"\n\n[Explanation of why this agent should be triggered in this scenario]\n\nassistant: \"[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']\"\n\n```\n\n## Anatomy of a Good Example\n\n### Context\n\n**Purpose:** Set the scene - what happened before the user's message\n\n**Good contexts:**\n```\nContext: User just implemented a new authentication feature\nContext: User has created a PR and wants it reviewed\nContext: User is debugging a test failure\nContext: After writing several functions without documentation\n```\n\n**Bad contexts:**\n```\nContext: User needs help (too vague)\nContext: Normal usage (not specific)\n```\n\n### User Message\n\n**Purpose:** Show the exact phrasing that should trigger the agent\n\n**Good user messages:**\n```\nuser: \"I've added the OAuth flow, can you check it?\"\nuser: \"Review PR #123\"\nuser: \"Why is this test failing?\"\nuser: \"Add docs for these functions\"\n```\n\n**Vary the phrasing:**\nInclude multiple examples with different phrasings for the same intent:\n```\nExample 1: user: \"Review my code\"\nExample 2: user: \"Can you check this implementation?\"\nExample 3: user: \"Look over my changes\"\n```\n\n### Assistant Response (Before Triggering)\n\n**Purpose:** Show what Claude says before launching the agent\n\n**Good responses:**\n```\nassistant: \"I'll analyze your OAuth implementation.\"\nassistant: \"Let me review that PR for you.\"\nassistant: \"I'll investigate the test failure.\"\n```\n\n**Proactive example:**\n```\nassistant: \"Great! Now let me review the code quality.\"\n\nCode was just written, proactively trigger review agent.\n\n```\n\n### Commentary\n\n**Purpose:** Explain the reasoning - WHY this agent should trigger\n\n**Good commentary:**\n```\n\nUser explicitly requested code review, trigger the code-reviewer agent.\n\n\n\nAfter code implementation, proactively use review agent to check quality.\n\n\n\nPR analysis request matches pr-analyzer agent's expertise.\n\n```\n\n**Include decision logic:**\n```\n\nUser wrote tests (Test tool used). The test-analyzer agent should check\ntest quality and coverage before continuing.\n\n```\n\n### Assistant Response (Triggering)\n\n**Purpose:** Show how Claude invokes the agent\n\n**Standard pattern:**\n```\nassistant: \"I'll use the [agent-name] agent to [what it will do].\"\n```\n\n**Examples:**\n```\nassistant: \"I'll use the code-reviewer agent to analyze the changes.\"\nassistant: \"Let me use the test-generator agent to create comprehensive tests.\"\nassistant: \"I'll use the security-analyzer agent to check for vulnerabilities.\"\n```\n\n## Example Types\n\n### Type 1: Explicit Request\n\nUser directly asks for what the agent does:\n\n```markdown\n\nContext: User explicitly requests security analysis\nuser: \"Check my code for security vulnerabilities\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nDirect security analysis request triggers the security-analyzer agent.\n\n\n```\n\n### Type 2: Proactive Triggering\n\nAgent triggers after relevant work without explicit request:\n\n```markdown\n\nContext: User just implemented database queries\nuser: \"I've added the user search functionality\"\nassistant: \"Great! Let me review it for security.\"\n\nDatabase code written. Proactively trigger security-analyzer to check\nfor SQL injection and other database security issues.\n\nassistant: \"I'll use the security-analyzer agent to check the database code.\"\n\n```\n\n### Type 3: Implicit Request\n\nUser implies need without stating it directly:\n\n```markdown\n\nContext: User mentions code is hard to understand\nuser: \"This code is confusing and hard to follow\"\nassistant: \"I can help improve the code clarity.\"\n\nUser indicates complexity issues. Trigger code-simplifier agent to refactor\nfor better readability.\n\nassistant: \"I'll use the code-simplifier agent to suggest improvements.\"\n\n```\n\n### Type 4: Tool Usage Pattern\n\nAgent triggers based on prior tool usage:\n\n```markdown\n\nContext: User made multiple edits to test files\nuser: \"I've updated all the tests\"\nassistant: \"Great! Let me verify test quality.\"\n\nMultiple Edit tools used on test files. Proactively trigger test-quality-analyzer\nto ensure tests follow best practices.\n\nassistant: \"I'll use the test-quality-analyzer agent to review the tests.\"\n\n```\n\n## Multiple Examples Strategy\n\n### Cover Different Phrasings\n\n```markdown\n\nuser: \"Review my code\"\n[...]\n\n\n\nuser: \"Can you check my implementation?\"\n[...]\n\n\n\nuser: \"Look over these changes\"\n[...]\n\n```\n\n### Cover Proactive and Reactive\n\n```markdown\n\nContext: User explicitly requests review\nuser: \"Review my code for issues\"\n[...]\n\n\n\nContext: After user writes code\nuser: \"I've implemented the feature\"\nassistant: \"Great! Now let me review it.\"\n\nCode written, proactively review.\n\n[...]\n\n```\n\n### Cover Edge Cases\n\n```markdown\n\nContext: Typical usage\nuser: \"Check my PR\"\n[...]\n\n\n\nContext: Large PR that needs thorough analysis\nuser: \"This is a big PR, can you do a deep review?\"\n[...]\n\nLarge PR mentioned, use thorough analysis mode.\n\n\n```\n\n## Common Mistakes\n\n### ❌ Missing Context\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent.\"\n\n```\n\n**Why bad:** No context about what led to this request.\n\n### ✅ With Context\n\n```markdown\n\nContext: User just finished implementing authentication\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to analyze the auth implementation.\"\n\nAuth code written, review for security and best practices.\n\n\n```\n\n### ❌ No Commentary\n\n```markdown\n\nContext: User requests review\nuser: \"Check my changes\"\nassistant: \"I'll use the reviewer agent.\"\n\n```\n\n**Why bad:** Doesn't explain WHY agent triggers.\n\n### ✅ With Commentary\n\n```markdown\n\nContext: User requests review after making changes\nuser: \"Check my changes\"\nassistant: \"I'll use the code-reviewer agent to analyze the modifications.\"\n\nCode review request triggers agent to check quality, security, and adherence to standards.\n\n\n```\n\n### ❌ Agent Responds Directly\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I found the following issues: [lists issues]\"\n\n```\n\n**Why bad:** Shows agent's output, not triggering.\n\n### ✅ Shows Triggering\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to perform the review.\"\n\nReview request triggers the agent.\n\n\n```\n\n## How Many Examples?\n\n### Minimum: 2 Examples\n\nCover at least:\n1. Explicit request\n2. One variation or proactive trigger\n\n### Recommended: 3-4 Examples\n\nCover:\n1. Explicit request (direct ask)\n2. Implicit request (user implies need)\n3. Proactive trigger (after relevant work)\n4. Edge case or specific scenario\n\n### Maximum: 6 Examples\n\nMore than 6 makes description too long. Focus on most important scenarios.\n\n## Template Library\n\n### Code Review Agent\n\n```markdown\n\nContext: User just implemented a new feature\nuser: \"I've added the user registration feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode written, proactively trigger code-reviewer agent.\n\nassistant: \"I'll use the code-reviewer agent to analyze the implementation.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my changes for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n```\n\n### Test Generation Agent\n\n```markdown\n\nContext: User implemented functions without tests\nuser: \"I've added the data processing functions\"\nassistant: \"Great! Let me generate tests for these.\"\n\nNew code without tests, proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly asks for tests\nuser: \"Generate tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n```\n\n### Documentation Agent\n\n```markdown\n\nContext: User added new API endpoints\nuser: \"I've implemented the REST API endpoints\"\nassistant: \"I'll document these endpoints.\"\n\nNew API code, proactively generate documentation.\n\nassistant: \"I'll use the api-docs-writer agent to create comprehensive documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Write docs for this API\"\nassistant: \"I'll use the api-docs-writer agent to generate clear documentation.\"\n\nDocumentation request triggers the agent.\n\n\n```\n\n### Validation Agent\n\n```markdown\n\nContext: User ready to commit changes\nuser: \"I'm ready to commit this code\"\nassistant: \"Let me validate it first.\"\n\nBefore commit, proactively validate with validation-agent.\n\nassistant: \"I'll use the code-validator agent to check for issues.\"\n\n\n\nContext: User asks for validation\nuser: \"Validate my implementation\"\nassistant: \"I'll use the code-validator agent to verify correctness.\"\n\nExplicit validation request triggers the agent.\n\n\n```\n\n## Debugging Triggering Issues\n\n### Agent Not Triggering\n\n**Check:**\n1. Examples include relevant keywords from user message\n2. Context matches actual usage scenarios\n3. Commentary explains triggering logic clearly\n4. Assistant shows use of Agent tool in examples\n\n**Fix:**\nAdd more examples covering different phrasings.\n\n### Agent Triggers Too Often\n\n**Check:**\n1. Examples are too broad or generic\n2. Triggering conditions overlap with other agents\n3. Commentary doesn't distinguish when NOT to use\n\n**Fix:**\nMake examples more specific, add negative examples.\n\n### Agent Triggers in Wrong Scenarios\n\n**Check:**\n1. Examples don't match actual intended use\n2. Commentary suggests inappropriate triggering\n\n**Fix:**\nRevise examples to show only correct triggering scenarios.\n\n## Best Practices Summary\n\n✅ **DO:**\n- Include 2-4 concrete, specific examples\n- Show both explicit and proactive triggering\n- Provide clear context for each example\n- Explain reasoning in commentary\n- Vary user message phrasing\n- Show Claude using Agent tool\n\n❌ **DON'T:**\n- Use generic, vague examples\n- Omit context or commentary\n- Show only one type of triggering\n- Skip the agent invocation step\n- Make examples too similar\n- Forget to explain why agent triggers\n\n## Conclusion\n\nWell-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.\n","plugins/plugin-dev/skills/command-development/README.md":"","plugins/plugin-dev/skills/command-development/SKILL.md":"---\nname: Command Development\ndescription: This skill should be used when the user asks to \"create a slash command\", \"add a command\", \"write a custom command\", \"define command arguments\", \"use command frontmatter\", \"organize commands\", \"create command with file references\", \"interactive command\", \"use AskUserQuestion in command\", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.\nversion: 0.2.0\n---\n\n# Command Development for Claude Code\n\n## Overview\n\nSlash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.\n\n**Key concepts:**\n- Markdown file format for commands\n- YAML frontmatter for configuration\n- Dynamic arguments and file references\n- Bash execution for context\n- Command organization and namespacing\n\n## Command Basics\n\n### What is a Slash Command?\n\nA slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:\n- **Reusability**: Define once, use repeatedly\n- **Consistency**: Standardize common workflows\n- **Sharing**: Distribute across team or projects\n- **Efficiency**: Quick access to complex prompts\n\n### Critical: Commands are Instructions FOR Claude\n\n**Commands are written for agent consumption, not human consumption.**\n\nWhen a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.\n\n**Correct approach (instructions for Claude):**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication issues\n\nProvide specific line numbers and severity ratings.\n```\n\n**Incorrect approach (messages to user):**\n```markdown\nThis command will review your code for security issues.\nYou'll receive a report with vulnerability details.\n```\n\nThe first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.\n\n### Command Locations\n\n**Project commands** (shared with team):\n- Location: `.claude/commands/`\n- Scope: Available in specific project\n- Label: Shown as \"(project)\" in `/help`\n- Use for: Team workflows, project-specific tasks\n\n**Personal commands** (available everywhere):\n- Location: `~/.claude/commands/`\n- Scope: Available in all projects\n- Label: Shown as \"(user)\" in `/help`\n- Use for: Personal workflows, cross-project utilities\n\n**Plugin commands** (bundled with plugins):\n- Location: `plugin-name/commands/`\n- Scope: Available when plugin installed\n- Label: Shown as \"(plugin-name)\" in `/help`\n- Use for: Plugin-specific functionality\n\n## File Format\n\n### Basic Structure\n\nCommands are Markdown files with `.md` extension:\n\n```\n.claude/commands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**Simple command:**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication bypass\n- Insecure data handling\n```\n\nNo frontmatter needed for basic commands.\n\n### With YAML Frontmatter\n\nAdd configuration using YAML frontmatter:\n\n```markdown\n---\ndescription: Review code for security issues\nallowed-tools: Read, Grep, Bash(git:*)\nmodel: sonnet\n---\n\nReview this code for security vulnerabilities...\n```\n\n## YAML Frontmatter Fields\n\n### description\n\n**Purpose:** Brief description shown in `/help`\n**Type:** String\n**Default:** First line of command prompt\n\n```yaml\n---\ndescription: Review pull request for code quality\n---\n```\n\n**Best practice:** Clear, actionable description (under 60 characters)\n\n### allowed-tools\n\n**Purpose:** Specify which tools command can use\n**Type:** String or Array\n**Default:** Inherits from conversation\n\n```yaml\n---\nallowed-tools: Read, Write, Edit, Bash(git:*)\n---\n```\n\n**Patterns:**\n- `Read, Write, Edit` - Specific tools\n- `Bash(git:*)` - Bash with git commands only\n- `*` - All tools (rarely needed)\n\n**Use when:** Command requires specific tool access\n\n### model\n\n**Purpose:** Specify model for command execution\n**Type:** String (sonnet, opus, haiku)\n**Default:** Inherits from conversation\n\n```yaml\n---\nmodel: haiku\n---\n```\n\n**Use cases:**\n- `haiku` - Fast, simple commands\n- `sonnet` - Standard workflows\n- `opus` - Complex analysis\n\n### argument-hint\n\n**Purpose:** Document expected arguments for autocomplete\n**Type:** String\n**Default:** None\n\n```yaml\n---\nargument-hint: [pr-number] [priority] [assignee]\n---\n```\n\n**Benefits:**\n- Helps users understand command arguments\n- Improves command discovery\n- Documents command interface\n\n### disable-model-invocation\n\n**Purpose:** Prevent SlashCommand tool from programmatically calling command\n**Type:** Boolean\n**Default:** false\n\n```yaml\n---\ndisable-model-invocation: true\n---\n```\n\n**Use when:** Command should only be manually invoked\n\n## Dynamic Arguments\n\n### Using $ARGUMENTS\n\nCapture all arguments as single string:\n\n```markdown\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$ARGUMENTS following our coding standards and best practices.\n```\n\n**Usage:**\n```\n> /fix-issue 123\n> /fix-issue 456\n```\n\n**Expands to:**\n```\nFix issue #123 following our coding standards...\nFix issue #456 following our coding standards...\n```\n\n### Using Positional Arguments\n\nCapture individual arguments with `$1`, `$2`, `$3`, etc.:\n\n```markdown\n---\ndescription: Review PR with priority and assignee\nargument-hint: [pr-number] [priority] [assignee]\n---\n\nReview pull request #$1 with priority level $2.\nAfter review, assign to $3 for follow-up.\n```\n\n**Usage:**\n```\n> /review-pr 123 high alice\n```\n\n**Expands to:**\n```\nReview pull request #123 with priority level high.\nAfter review, assign to alice for follow-up.\n```\n\n### Combining Arguments\n\nMix positional and remaining arguments:\n\n```markdown\nDeploy $1 to $2 environment with options: $3\n```\n\n**Usage:**\n```\n> /deploy api staging --force --skip-tests\n```\n\n**Expands to:**\n```\nDeploy api to staging environment with options: --force --skip-tests\n```\n\n## File References\n\n### Using @ Syntax\n\nInclude file contents in command:\n\n```markdown\n---\ndescription: Review specific file\nargument-hint: [file-path]\n---\n\nReview @$1 for:\n- Code quality\n- Best practices\n- Potential bugs\n```\n\n**Usage:**\n```\n> /review-file src/api/users.ts\n```\n\n**Effect:** Claude reads `src/api/users.ts` before processing command\n\n### Multiple File References\n\nReference multiple files:\n\n```markdown\nCompare @src/old-version.js with @src/new-version.js\n\nIdentify:\n- Breaking changes\n- New features\n- Bug fixes\n```\n\n### Static File References\n\nReference known files without arguments:\n\n```markdown\nReview @package.json and @tsconfig.json for consistency\n\nEnsure:\n- TypeScript version matches\n- Dependencies are aligned\n- Build configuration is correct\n```\n\n## Bash Execution in Commands\n\nCommands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.\n\n**When to use:**\n- Include dynamic context (git status, environment vars, etc.)\n- Gather project/repository state\n- Build context-aware workflows\n\n**Implementation details:**\nFor complete syntax, examples, and best practices, see `references/plugin-features-reference.md` section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues\n\n## Command Organization\n\n### Flat Structure\n\nSimple organization for small command sets:\n\n```\n.claude/commands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**Use when:** 5-15 commands, no clear categories\n\n### Namespaced Structure\n\nOrganize commands in subdirectories:\n\n```\n.claude/commands/\n├── ci/\n│ ├── build.md # /build (project:ci)\n│ ├── test.md # /test (project:ci)\n│ └── lint.md # /lint (project:ci)\n├── git/\n│ ├── commit.md # /commit (project:git)\n│ └── pr.md # /pr (project:git)\n└── docs/\n ├── generate.md # /generate (project:docs)\n └── publish.md # /publish (project:docs)\n```\n\n**Benefits:**\n- Logical grouping by category\n- Namespace shown in `/help`\n- Easier to find related commands\n\n**Use when:** 15+ commands, clear categories\n\n## Best Practices\n\n### Command Design\n\n1. **Single responsibility:** One command, one task\n2. **Clear descriptions:** Self-explanatory in `/help`\n3. **Explicit dependencies:** Use `allowed-tools` when needed\n4. **Document arguments:** Always provide `argument-hint`\n5. **Consistent naming:** Use verb-noun pattern (review-pr, fix-issue)\n\n### Argument Handling\n\n1. **Validate arguments:** Check for required arguments in prompt\n2. **Provide defaults:** Suggest defaults when arguments missing\n3. **Document format:** Explain expected argument format\n4. **Handle edge cases:** Consider missing or invalid arguments\n\n```markdown\n---\nargument-hint: [pr-number]\n---\n\n$IF($1,\n Review PR #$1,\n Please provide a PR number. Usage: /review-pr [number]\n)\n```\n\n### File References\n\n1. **Explicit paths:** Use clear file paths\n2. **Check existence:** Handle missing files gracefully\n3. **Relative paths:** Use project-relative paths\n4. **Glob support:** Consider using Glob tool for patterns\n\n### Bash Commands\n\n1. **Limit scope:** Use `Bash(git:*)` not `Bash(*)`\n2. **Safe commands:** Avoid destructive operations\n3. **Handle errors:** Consider command failures\n4. **Keep fast:** Long-running commands slow invocation\n\n### Documentation\n\n1. **Add comments:** Explain complex logic\n2. **Provide examples:** Show usage in comments\n3. **List requirements:** Document dependencies\n4. **Version commands:** Note breaking changes\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment] [version]\n---\n\n\n\nDeploy application to $1 environment using version $2...\n```\n\n## Common Patterns\n\n### Review Pattern\n\n```markdown\n---\ndescription: Review code changes\nallowed-tools: Read, Bash(git:*)\n---\n\nFiles changed: !`git diff --name-only`\n\nReview each file for:\n1. Code quality and style\n2. Potential bugs or issues\n3. Test coverage\n4. Documentation needs\n\nProvide specific feedback for each file.\n```\n\n### Testing Pattern\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*)\n---\n\nRun tests: !`npm test $1`\n\nAnalyze results and suggest fixes for failures.\n```\n\n### Documentation Pattern\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1 including:\n- Function/class descriptions\n- Parameter documentation\n- Return value descriptions\n- Usage examples\n- Edge cases and errors\n```\n\n### Workflow Pattern\n\n```markdown\n---\ndescription: Complete PR workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read\n---\n\nPR #$1 Workflow:\n\n1. Fetch PR: !`gh pr view $1`\n2. Review changes\n3. Run checks\n4. Approve or request changes\n```\n\n## Troubleshooting\n\n**Command not appearing:**\n- Check file is in correct directory\n- Verify `.md` extension present\n- Ensure valid Markdown format\n- Restart Claude Code\n\n**Arguments not working:**\n- Verify `$1`, `$2` syntax correct\n- Check `argument-hint` matches usage\n- Ensure no extra spaces\n\n**Bash execution failing:**\n- Check `allowed-tools` includes Bash\n- Verify command syntax in backticks\n- Test command in terminal first\n- Check for required permissions\n\n**File references not working:**\n- Verify `@` syntax correct\n- Check file path is valid\n- Ensure Read tool allowed\n- Use absolute or project-relative paths\n\n## Plugin-Specific Features\n\n### CLAUDE_PLUGIN_ROOT Variable\n\nPlugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path.\n\n**Purpose:**\n- Reference plugin files portably\n- Execute plugin scripts\n- Load plugin configuration\n- Access plugin templates\n\n**Basic usage:**\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*)\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\nReview results and report findings.\n```\n\n**Common patterns:**\n\n```markdown\n# Execute plugin script\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n\n# Load plugin configuration\n@${CLAUDE_PLUGIN_ROOT}/config/settings.json\n\n# Use plugin template\n@${CLAUDE_PLUGIN_ROOT}/templates/report.md\n\n# Access plugin resources\n@${CLAUDE_PLUGIN_ROOT}/docs/reference.md\n```\n\n**Why use it:**\n- Works across all installations\n- Portable between systems\n- No hardcoded paths needed\n- Essential for multi-file plugins\n\n### Plugin Command Organization\n\nPlugin commands discovered automatically from `commands/` directory:\n\n```\nplugin-name/\n├── commands/\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ ├── bar.md # /bar (plugin:plugin-name)\n│ └── utils/\n│ └── helper.md # /helper (plugin:plugin-name:utils)\n└── plugin.json\n```\n\n**Namespace benefits:**\n- Logical command grouping\n- Shown in `/help` output\n- Avoid name conflicts\n- Organize related commands\n\n**Naming conventions:**\n- Use descriptive action names\n- Avoid generic names (test, run)\n- Consider plugin-specific prefix\n- Use hyphens for multi-word names\n\n### Plugin Command Patterns\n\n**Configuration-based pattern:**\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nDeploy to $1 using configuration settings.\nMonitor deployment and report status.\n```\n\n**Template-based pattern:**\n\n```markdown\n---\ndescription: Generate docs from template\nargument-hint: [component]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md\n\nGenerate documentation for $1 following template structure.\n```\n\n**Multi-script pattern:**\n\n```markdown\n---\ndescription: Complete build workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\nPackage: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`\n\nReview outputs and report workflow status.\n```\n\n**See `references/plugin-features-reference.md` for detailed patterns.**\n\n## Integration with Plugin Components\n\nCommands can integrate with other plugin components for powerful workflows.\n\n### Agent Integration\n\nLaunch plugin agents for complex tasks:\n\n```markdown\n---\ndescription: Deep code review\nargument-hint: [file-path]\n---\n\nInitiate comprehensive review of @$1 using the code-reviewer agent.\n\nThe agent will analyze:\n- Code structure\n- Security issues\n- Performance\n- Best practices\n\nAgent uses plugin resources:\n- ${CLAUDE_PLUGIN_ROOT}/config/rules.json\n- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md\n```\n\n**Key points:**\n- Agent must exist in `plugin/agents/` directory\n- Claude uses Task tool to launch agent\n- Document agent capabilities\n- Reference plugin resources agent uses\n\n### Skill Integration\n\nLeverage plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: Document API with standards\nargument-hint: [api-file]\n---\n\nDocument API in @$1 following plugin standards.\n\nUse the api-docs-standards skill to ensure:\n- Complete endpoint documentation\n- Consistent formatting\n- Example quality\n- Error documentation\n\nGenerate production-ready API docs.\n```\n\n**Key points:**\n- Skill must exist in `plugin/skills/` directory\n- Mention skill name to trigger invocation\n- Document skill purpose\n- Explain what skill provides\n\n### Hook Coordination\n\nDesign commands that work with plugin hooks:\n- Commands can prepare state for hooks to process\n- Hooks execute automatically on tool events\n- Commands should document expected hook behavior\n- Guide Claude on interpreting hook output\n\nSee `references/plugin-features-reference.md` for examples of commands that coordinate with hooks\n\n### Multi-Component Workflows\n\nCombine agents, skills, and scripts:\n\n```markdown\n---\ndescription: Comprehensive review workflow\nargument-hint: [file]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget: @$1\n\nPhase 1 - Static Analysis:\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\nPhase 2 - Deep Review:\nLaunch code-reviewer agent for detailed analysis.\n\nPhase 3 - Standards Check:\nUse coding-standards skill for validation.\n\nPhase 4 - Report:\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review.md\n\nCompile findings into report following template.\n```\n\n**When to use:**\n- Complex multi-step workflows\n- Leverage multiple plugin capabilities\n- Require specialized analysis\n- Need structured outputs\n\n## Validation Patterns\n\nCommands should validate inputs and resources before processing.\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\nIf $1 is valid environment:\n Deploy to $1\nOtherwise:\n Explain valid environments: dev, staging, prod\n Show usage: /deploy [environment]\n```\n\n### File Existence Checks\n\n```markdown\n---\ndescription: Process configuration\nargument-hint: [config-file]\n---\n\nCheck file exists: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nIf file exists:\n Process configuration: @$1\nOtherwise:\n Explain where to place config file\n Show expected format\n Provide example configuration\n```\n\n### Plugin Resource Validation\n\n```markdown\n---\ndescription: Run plugin analyzer\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, run analysis.\nOtherwise, report missing components.\n```\n\n### Error Handling\n\n```markdown\n---\ndescription: Build with error handling\nallowed-tools: Bash(*)\n---\n\nExecute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo \"BUILD_FAILED\"`\n\nIf build succeeded:\n Report success and output location\nIf build failed:\n Analyze error output\n Suggest likely causes\n Provide troubleshooting steps\n```\n\n**Best practices:**\n- Validate early in command\n- Provide helpful error messages\n- Suggest corrective actions\n- Handle edge cases gracefully\n\n---\n\nFor detailed frontmatter field specifications, see `references/frontmatter-reference.md`.\nFor plugin-specific features and patterns, see `references/plugin-features-reference.md`.\nFor command pattern examples, see `examples/` directory.\n","plugins/plugin-dev/skills/command-development/examples/plugin-commands.md":"# Plugin Command Examples\n\nPractical examples of commands designed for Claude Code plugins, demonstrating plugin-specific patterns and features.\n\n## Table of Contents\n\n1. [Simple Plugin Command](#1-simple-plugin-command)\n2. [Script-Based Analysis](#2-script-based-analysis)\n3. [Template-Based Generation](#3-template-based-generation)\n4. [Multi-Script Workflow](#4-multi-script-workflow)\n5. [Configuration-Driven Deployment](#5-configuration-driven-deployment)\n6. [Agent Integration](#6-agent-integration)\n7. [Skill Integration](#7-skill-integration)\n8. [Multi-Component Workflow](#8-multi-component-workflow)\n9. [Validated Input Command](#9-validated-input-command)\n10. [Environment-Aware Command](#10-environment-aware-command)\n\n---\n\n## 1. Simple Plugin Command\n\n**Use case:** Basic command that uses plugin script\n\n**File:** `commands/analyze.md`\n\n```markdown\n---\ndescription: Analyze code quality using plugin tools\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nAnalyze @$1 using plugin's quality checker:\n\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/quality-check.js $1`\n\nReview the analysis output and provide:\n1. Summary of findings\n2. Priority issues to address\n3. Suggested improvements\n4. Code quality score interpretation\n```\n\n**Key features:**\n- Uses `${CLAUDE_PLUGIN_ROOT}` for portable path\n- Combines file reference with script execution\n- Simple single-purpose command\n\n---\n\n## 2. Script-Based Analysis\n\n**Use case:** Run comprehensive analysis using multiple plugin scripts\n\n**File:** `commands/full-audit.md`\n\n```markdown\n---\ndescription: Complete code audit using plugin suite\nargument-hint: [directory]\nallowed-tools: Bash(*)\nmodel: sonnet\n---\n\nRunning complete audit on $1:\n\n**Security scan:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh $1`\n\n**Performance analysis:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-analyze.sh $1`\n\n**Best practices check:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/best-practices.sh $1`\n\nAnalyze all results and create comprehensive report including:\n- Critical issues requiring immediate attention\n- Performance optimization opportunities\n- Security vulnerabilities and fixes\n- Overall health score and recommendations\n```\n\n**Key features:**\n- Multiple script executions\n- Organized output sections\n- Comprehensive workflow\n- Clear reporting structure\n\n---\n\n## 3. Template-Based Generation\n\n**Use case:** Generate documentation following plugin template\n\n**File:** `commands/gen-api-docs.md`\n\n```markdown\n---\ndescription: Generate API documentation from template\nargument-hint: [api-file]\n---\n\nTemplate structure: @${CLAUDE_PLUGIN_ROOT}/templates/api-documentation.md\n\nAPI implementation: @$1\n\nGenerate complete API documentation following the template format above.\n\nEnsure documentation includes:\n- Endpoint descriptions with HTTP methods\n- Request/response schemas\n- Authentication requirements\n- Error codes and handling\n- Usage examples with curl commands\n- Rate limiting information\n\nFormat output as markdown suitable for README or docs site.\n```\n\n**Key features:**\n- Uses plugin template\n- Combines template with source file\n- Standardized output format\n- Clear documentation structure\n\n---\n\n## 4. Multi-Script Workflow\n\n**Use case:** Orchestrate build, test, and deploy workflow\n\n**File:** `commands/release.md`\n\n```markdown\n---\ndescription: Execute complete release workflow\nargument-hint: [version]\nallowed-tools: Bash(*), Read\n---\n\nExecuting release workflow for version $1:\n\n**Step 1 - Pre-release validation:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-release-check.sh $1`\n\n**Step 2 - Build artifacts:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build-release.sh $1`\n\n**Step 3 - Run test suite:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh`\n\n**Step 4 - Package release:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh $1`\n\nReview all step outputs and report:\n1. Any failures or warnings\n2. Build artifacts location\n3. Test results summary\n4. Next steps for deployment\n5. Rollback plan if needed\n```\n\n**Key features:**\n- Multi-step workflow\n- Sequential script execution\n- Clear step numbering\n- Comprehensive reporting\n\n---\n\n## 5. Configuration-Driven Deployment\n\n**Use case:** Deploy using environment-specific plugin configuration\n\n**File:** `commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nDeployment configuration for $1: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nCurrent git state: !`git rev-parse --short HEAD`\n\nBuild info: !`cat package.json | grep -E '(name|version)'`\n\nExecute deployment to $1 environment using configuration above.\n\nDeployment checklist:\n1. Validate configuration settings\n2. Build application for $1\n3. Run pre-deployment tests\n4. Deploy to target environment\n5. Run smoke tests\n6. Verify deployment success\n7. Update deployment log\n\nReport deployment status and any issues encountered.\n```\n\n**Key features:**\n- Environment-specific configuration\n- Dynamic config file loading\n- Pre-deployment validation\n- Structured checklist\n\n---\n\n## 6. Agent Integration\n\n**Use case:** Command that launches plugin agent for complex task\n\n**File:** `commands/deep-review.md`\n\n```markdown\n---\ndescription: Deep code review using plugin agent\nargument-hint: [file-or-directory]\n---\n\nInitiate comprehensive code review of @$1 using the code-reviewer agent.\n\nThe agent will perform:\n1. **Static analysis** - Check for code smells and anti-patterns\n2. **Security audit** - Identify potential vulnerabilities\n3. **Performance review** - Find optimization opportunities\n4. **Best practices** - Ensure code follows standards\n5. **Documentation check** - Verify adequate documentation\n\nThe agent has access to:\n- Plugin's linting rules: ${CLAUDE_PLUGIN_ROOT}/config/lint-rules.json\n- Security checklist: ${CLAUDE_PLUGIN_ROOT}/checklists/security.md\n- Performance guidelines: ${CLAUDE_PLUGIN_ROOT}/docs/performance.md\n\nNote: This uses the Task tool to launch the plugin's code-reviewer agent for thorough analysis.\n```\n\n**Key features:**\n- Delegates to plugin agent\n- Documents agent capabilities\n- References plugin resources\n- Clear scope definition\n\n---\n\n## 7. Skill Integration\n\n**Use case:** Command that leverages plugin skill for specialized knowledge\n\n**File:** `commands/document-api.md`\n\n```markdown\n---\ndescription: Document API following plugin standards\nargument-hint: [api-file]\n---\n\nAPI source code: @$1\n\nGenerate API documentation following the plugin's API documentation standards.\n\nUse the api-documentation-standards skill to ensure:\n- **OpenAPI compliance** - Follow OpenAPI 3.0 specification\n- **Consistent formatting** - Use plugin's documentation style\n- **Complete coverage** - Document all endpoints and schemas\n- **Example quality** - Provide realistic usage examples\n- **Error documentation** - Cover all error scenarios\n\nThe skill provides:\n- Standard documentation templates\n- API documentation best practices\n- Common patterns for this codebase\n- Quality validation criteria\n\nGenerate production-ready API documentation.\n```\n\n**Key features:**\n- Invokes plugin skill by name\n- Documents skill purpose\n- Clear expectations\n- Leverages skill knowledge\n\n---\n\n## 8. Multi-Component Workflow\n\n**Use case:** Complex workflow using agents, skills, and scripts\n\n**File:** `commands/complete-review.md`\n\n```markdown\n---\ndescription: Comprehensive review using all plugin components\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget file: @$1\n\nExecute comprehensive review workflow:\n\n**Phase 1: Automated Analysis**\nRun plugin analyzer: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\n**Phase 2: Deep Review (Agent)**\nLaunch the code-quality-reviewer agent for detailed analysis.\nAgent will examine:\n- Code structure and organization\n- Error handling patterns\n- Testing coverage\n- Documentation quality\n\n**Phase 3: Standards Check (Skill)**\nUse the coding-standards skill to validate:\n- Naming conventions\n- Code formatting\n- Best practices adherence\n- Framework-specific patterns\n\n**Phase 4: Report Generation**\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nCompile all findings into comprehensive report following template.\n\n**Phase 5: Recommendations**\nGenerate prioritized action items:\n1. Critical issues (must fix)\n2. Important improvements (should fix)\n3. Nice-to-have enhancements (could fix)\n\nInclude specific file locations and suggested changes for each item.\n```\n\n**Key features:**\n- Multi-phase workflow\n- Combines scripts, agents, skills\n- Template-based reporting\n- Prioritized outputs\n\n---\n\n## 9. Validated Input Command\n\n**Use case:** Command with input validation and error handling\n\n**File:** `commands/build-env.md`\n\n```markdown\n---\ndescription: Build for specific environment with validation\nargument-hint: [environment]\nallowed-tools: Bash(*)\n---\n\nValidate environment argument: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" && echo \"VALID\" || echo \"INVALID\"`\n\nCheck build script exists: !`test -x ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh && echo \"EXISTS\" || echo \"MISSING\"`\n\nVerify configuration available: !`test -f ${CLAUDE_PLUGIN_ROOT}/config/$1.json && echo \"FOUND\" || echo \"NOT_FOUND\"`\n\nIf all validations pass:\n\n**Configuration:** @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\n**Execute build:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh $1 2>&1`\n\n**Validation results:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-build.sh $1 2>&1`\n\nReport build status and any issues.\n\nIf validations fail:\n- Explain which validation failed\n- Provide expected values/locations\n- Suggest corrective actions\n- Document troubleshooting steps\n```\n\n**Key features:**\n- Input validation\n- Resource existence checks\n- Error handling\n- Helpful error messages\n- Graceful failure handling\n\n---\n\n## 10. Environment-Aware Command\n\n**Use case:** Command that adapts behavior based on environment\n\n**File:** `commands/run-checks.md`\n\n```markdown\n---\ndescription: Run environment-appropriate checks\nargument-hint: [environment]\nallowed-tools: Bash(*), Read\n---\n\nEnvironment: $1\n\nLoad environment configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-checks.json\n\nDetermine check level: !`echo \"$1\" | grep -E \"^prod$\" && echo \"FULL\" || echo \"BASIC\"`\n\n**For production environment:**\n- Full test suite: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-full.sh`\n- Security scan: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh`\n- Performance audit: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-check.sh`\n- Compliance check: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/compliance.sh`\n\n**For non-production environments:**\n- Basic tests: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-basic.sh`\n- Quick lint: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh`\n\nAnalyze results based on environment requirements:\n\n**Production:** All checks must pass with zero critical issues\n**Staging:** No critical issues, warnings acceptable\n**Development:** Focus on blocking issues only\n\nReport status and recommend proceed/block decision.\n```\n\n**Key features:**\n- Environment-aware logic\n- Conditional execution\n- Different validation levels\n- Appropriate reporting per environment\n\n---\n\n## Common Patterns Summary\n\n### Pattern: Plugin Script Execution\n```markdown\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/script-name.js $1`\n```\nUse for: Running plugin-provided Node.js scripts\n\n### Pattern: Plugin Configuration Loading\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/config/config-name.json\n```\nUse for: Loading plugin configuration files\n\n### Pattern: Plugin Template Usage\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/templates/template-name.md\n```\nUse for: Using plugin templates for generation\n\n### Pattern: Agent Invocation\n```markdown\nLaunch the [agent-name] agent for [task description].\n```\nUse for: Delegating complex tasks to plugin agents\n\n### Pattern: Skill Reference\n```markdown\nUse the [skill-name] skill to ensure [requirements].\n```\nUse for: Leveraging plugin skills for specialized knowledge\n\n### Pattern: Input Validation\n```markdown\nValidate input: !`echo \"$1\" | grep -E \"^pattern$\" && echo \"OK\" || echo \"ERROR\"`\n```\nUse for: Validating command arguments\n\n### Pattern: Resource Validation\n```markdown\nCheck exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/path/file && echo \"YES\" || echo \"NO\"`\n```\nUse for: Verifying required plugin files exist\n\n---\n\n## Development Tips\n\n### Testing Plugin Commands\n\n1. **Test with plugin installed:**\n ```bash\n cd /path/to/plugin\n claude /command-name args\n ```\n\n2. **Verify ${CLAUDE_PLUGIN_ROOT} expansion:**\n ```bash\n # Add debug output to command\n !`echo \"Plugin root: ${CLAUDE_PLUGIN_ROOT}\"`\n ```\n\n3. **Test across different working directories:**\n ```bash\n cd /tmp && claude /command-name\n cd /other/project && claude /command-name\n ```\n\n4. **Validate resource availability:**\n ```bash\n # Check all plugin resources exist\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/scripts/`\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/config/`\n ```\n\n### Common Mistakes to Avoid\n\n1. **Using relative paths instead of ${CLAUDE_PLUGIN_ROOT}:**\n ```markdown\n # Wrong\n !`node ./scripts/analyze.js`\n\n # Correct\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n ```\n\n2. **Forgetting to allow required tools:**\n ```markdown\n # Missing allowed-tools\n !`bash script.sh` # Will fail without Bash permission\n\n # Correct\n ---\n allowed-tools: Bash(*)\n ---\n !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n ```\n\n3. **Not validating inputs:**\n ```markdown\n # Risky - no validation\n Deploy to $1 environment\n\n # Better - with validation\n Validate: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n Deploy to $1 environment (if valid)\n ```\n\n4. **Hardcoding plugin paths:**\n ```markdown\n # Wrong - breaks on different installations\n @/home/user/.claude/plugins/my-plugin/config.json\n\n # Correct - works everywhere\n @${CLAUDE_PLUGIN_ROOT}/config.json\n ```\n\n---\n\nFor detailed plugin-specific features, see `references/plugin-features-reference.md`.\nFor general command development, see main `SKILL.md`.\n","plugins/plugin-dev/skills/command-development/examples/simple-commands.md":"# Simple Command Examples\n\nBasic slash command patterns for common use cases.\n\n**Important:** All examples below are written as instructions FOR Claude (agent consumption), not messages TO users. Commands tell Claude what to do, not tell users what will happen.\n\n## Example 1: Code Review Command\n\n**File:** `.claude/commands/review.md`\n\n```markdown\n---\ndescription: Review code for quality and issues\nallowed-tools: Read, Bash(git:*)\n---\n\nReview the code in this repository for:\n\n1. **Code Quality:**\n - Readability and maintainability\n - Consistent style and formatting\n - Appropriate abstraction levels\n\n2. **Potential Issues:**\n - Logic errors or bugs\n - Edge cases not handled\n - Performance concerns\n\n3. **Best Practices:**\n - Design patterns used correctly\n - Error handling present\n - Documentation adequate\n\nProvide specific feedback with file and line references.\n```\n\n**Usage:**\n```\n> /review\n```\n\n---\n\n## Example 2: Security Review Command\n\n**File:** `.claude/commands/security-review.md`\n\n```markdown\n---\ndescription: Review code for security vulnerabilities\nallowed-tools: Read, Grep\nmodel: sonnet\n---\n\nPerform comprehensive security review checking for:\n\n**Common Vulnerabilities:**\n- SQL injection risks\n- Cross-site scripting (XSS)\n- Authentication/authorization issues\n- Insecure data handling\n- Hardcoded secrets or credentials\n\n**Security Best Practices:**\n- Input validation present\n- Output encoding correct\n- Secure defaults used\n- Error messages safe\n- Logging appropriate (no sensitive data)\n\nFor each issue found:\n- File and line number\n- Severity (Critical/High/Medium/Low)\n- Description of vulnerability\n- Recommended fix\n\nPrioritize issues by severity.\n```\n\n**Usage:**\n```\n> /security-review\n```\n\n---\n\n## Example 3: Test Command with File Argument\n\n**File:** `.claude/commands/test-file.md`\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*), Bash(jest:*)\n---\n\nRun tests for $1:\n\nTest execution: !`npm test $1`\n\nAnalyze results:\n- Tests passed/failed\n- Code coverage\n- Performance issues\n- Flaky tests\n\nIf failures found, suggest fixes based on error messages.\n```\n\n**Usage:**\n```\n> /test-file src/utils/helpers.test.ts\n```\n\n---\n\n## Example 4: Documentation Generator\n\n**File:** `.claude/commands/document.md`\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1\n\nInclude:\n\n**Overview:**\n- Purpose and responsibility\n- Main functionality\n- Dependencies\n\n**API Documentation:**\n- Function/method signatures\n- Parameter descriptions with types\n- Return values with types\n- Exceptions/errors thrown\n\n**Usage Examples:**\n- Basic usage\n- Common patterns\n- Edge cases\n\n**Implementation Notes:**\n- Algorithm complexity\n- Performance considerations\n- Known limitations\n\nFormat as Markdown suitable for project documentation.\n```\n\n**Usage:**\n```\n> /document src/api/users.ts\n```\n\n---\n\n## Example 5: Git Status Summary\n\n**File:** `.claude/commands/git-status.md`\n\n```markdown\n---\ndescription: Summarize Git repository status\nallowed-tools: Bash(git:*)\n---\n\nRepository Status Summary:\n\n**Current Branch:** !`git branch --show-current`\n\n**Status:** !`git status --short`\n\n**Recent Commits:** !`git log --oneline -5`\n\n**Remote Status:** !`git fetch && git status -sb`\n\nProvide:\n- Summary of changes\n- Suggested next actions\n- Any warnings or issues\n```\n\n**Usage:**\n```\n> /git-status\n```\n\n---\n\n## Example 6: Deployment Command\n\n**File:** `.claude/commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy to specified environment\nargument-hint: [environment] [version]\nallowed-tools: Bash(kubectl:*), Read\n---\n\nDeploy to $1 environment using version $2\n\n**Pre-deployment Checks:**\n1. Verify $1 configuration exists\n2. Check version $2 is valid\n3. Verify cluster accessibility: !`kubectl cluster-info`\n\n**Deployment Steps:**\n1. Update deployment manifest with version $2\n2. Apply configuration to $1\n3. Monitor rollout status\n4. Verify pod health\n5. Run smoke tests\n\n**Rollback Plan:**\nDocument current version for rollback if issues occur.\n\nProceed with deployment? (yes/no)\n```\n\n**Usage:**\n```\n> /deploy staging v1.2.3\n```\n\n---\n\n## Example 7: Comparison Command\n\n**File:** `.claude/commands/compare-files.md`\n\n```markdown\n---\ndescription: Compare two files\nargument-hint: [file1] [file2]\n---\n\nCompare @$1 with @$2\n\n**Analysis:**\n\n1. **Differences:**\n - Lines added\n - Lines removed\n - Lines modified\n\n2. **Functional Changes:**\n - Breaking changes\n - New features\n - Bug fixes\n - Refactoring\n\n3. **Impact:**\n - Affected components\n - Required updates elsewhere\n - Migration requirements\n\n4. **Recommendations:**\n - Code review focus areas\n - Testing requirements\n - Documentation updates needed\n\nPresent as structured comparison report.\n```\n\n**Usage:**\n```\n> /compare-files src/old-api.ts src/new-api.ts\n```\n\n---\n\n## Example 8: Quick Fix Command\n\n**File:** `.claude/commands/quick-fix.md`\n\n```markdown\n---\ndescription: Quick fix for common issues\nargument-hint: [issue-description]\nmodel: haiku\n---\n\nQuickly fix: $ARGUMENTS\n\n**Approach:**\n1. Identify the issue\n2. Find relevant code\n3. Propose fix\n4. Explain solution\n\nFocus on:\n- Simple, direct solution\n- Minimal changes\n- Following existing patterns\n- No breaking changes\n\nProvide code changes with file paths and line numbers.\n```\n\n**Usage:**\n```\n> /quick-fix button not responding to clicks\n> /quick-fix typo in error message\n```\n\n---\n\n## Example 9: Research Command\n\n**File:** `.claude/commands/research.md`\n\n```markdown\n---\ndescription: Research best practices for topic\nargument-hint: [topic]\nmodel: sonnet\n---\n\nResearch best practices for: $ARGUMENTS\n\n**Coverage:**\n\n1. **Current State:**\n - How we currently handle this\n - Existing implementations\n\n2. **Industry Standards:**\n - Common patterns\n - Recommended approaches\n - Tools and libraries\n\n3. **Comparison:**\n - Our approach vs standards\n - Gaps or improvements needed\n - Migration considerations\n\n4. **Recommendations:**\n - Concrete action items\n - Priority and effort estimates\n - Resources for implementation\n\nProvide actionable guidance based on research.\n```\n\n**Usage:**\n```\n> /research error handling in async operations\n> /research API authentication patterns\n```\n\n---\n\n## Example 10: Explain Code Command\n\n**File:** `.claude/commands/explain.md`\n\n```markdown\n---\ndescription: Explain how code works\nargument-hint: [file-or-function]\n---\n\nExplain @$1 in detail\n\n**Explanation Structure:**\n\n1. **Overview:**\n - What it does\n - Why it exists\n - How it fits in system\n\n2. **Step-by-Step:**\n - Line-by-line walkthrough\n - Key algorithms or logic\n - Important details\n\n3. **Inputs and Outputs:**\n - Parameters and types\n - Return values\n - Side effects\n\n4. **Edge Cases:**\n - Error handling\n - Special cases\n - Limitations\n\n5. **Usage Examples:**\n - How to call it\n - Common patterns\n - Integration points\n\nExplain at level appropriate for junior engineer.\n```\n\n**Usage:**\n```\n> /explain src/utils/cache.ts\n> /explain AuthService.login\n```\n\n---\n\n## Key Patterns\n\n### Pattern 1: Read-Only Analysis\n\n```markdown\n---\nallowed-tools: Read, Grep\n---\n\nAnalyze but don't modify...\n```\n\n**Use for:** Code review, documentation, analysis\n\n### Pattern 2: Git Operations\n\n```markdown\n---\nallowed-tools: Bash(git:*)\n---\n\n!`git status`\nAnalyze and suggest...\n```\n\n**Use for:** Repository status, commit analysis\n\n### Pattern 3: Single Argument\n\n```markdown\n---\nargument-hint: [target]\n---\n\nProcess $1...\n```\n\n**Use for:** File operations, targeted actions\n\n### Pattern 4: Multiple Arguments\n\n```markdown\n---\nargument-hint: [source] [target] [options]\n---\n\nProcess $1 to $2 with $3...\n```\n\n**Use for:** Workflows, deployments, comparisons\n\n### Pattern 5: Fast Execution\n\n```markdown\n---\nmodel: haiku\n---\n\nQuick simple task...\n```\n\n**Use for:** Simple, repetitive commands\n\n### Pattern 6: File Comparison\n\n```markdown\nCompare @$1 with @$2...\n```\n\n**Use for:** Diff analysis, migration planning\n\n### Pattern 7: Context Gathering\n\n```markdown\n---\nallowed-tools: Bash(git:*), Read\n---\n\nContext: !`git status`\nFiles: @file1 @file2\n\nAnalyze...\n```\n\n**Use for:** Informed decision making\n\n## Tips for Writing Simple Commands\n\n1. **Start basic:** Single responsibility, clear purpose\n2. **Add complexity gradually:** Start without frontmatter\n3. **Test incrementally:** Verify each feature works\n4. **Use descriptive names:** Command name should indicate purpose\n5. **Document arguments:** Always use argument-hint\n6. **Provide examples:** Show usage in comments\n7. **Handle errors:** Consider missing arguments or files\n","plugins/plugin-dev/skills/command-development/references/advanced-workflows.md":"# Advanced Workflow Patterns\n\nMulti-step command sequences and composition patterns for complex workflows.\n\n## Overview\n\nAdvanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks.\n\n## Multi-Step Command Patterns\n\n### Sequential Workflow Command\n\nCommands that guide users through multi-step processes:\n\n```markdown\n---\ndescription: Complete PR review workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read, Grep\n---\n\n# PR Review Workflow for #$1\n\n## Step 1: Fetch PR Details\n!`gh pr view $1 --json title,body,author,files`\n\n## Step 2: Review Files\nFiles changed: !`gh pr diff $1 --name-only`\n\nFor each file:\n- Check code quality\n- Verify tests exist\n- Review documentation\n\n## Step 3: Run Checks\nTest status: !`gh pr checks $1`\n\nVerify:\n- All tests passing\n- No merge conflicts\n- CI/CD successful\n\n## Step 4: Provide Feedback\n\nSummarize:\n- Issues found (critical/minor)\n- Suggestions for improvement\n- Approval recommendation\n\nWould you like to:\n1. Approve PR\n2. Request changes\n3. Leave comments only\n\nReply with your choice and I'll help complete the action.\n```\n\n**Key features:**\n- Numbered steps for clarity\n- Bash execution for context\n- Decision points for user input\n- Next action suggestions\n\n### State-Carrying Workflow\n\nCommands that maintain state between invocations:\n\n```markdown\n---\ndescription: Initialize deployment workflow\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment\n\nCreating deployment tracking file...\n\nCurrent branch: !`git branch --show-current`\nLatest commit: !`git log -1 --format=%H`\n\nDeployment state saved to `.claude/deployment-state.local.md`:\n\n\\`\\`\\`markdown\n---\ninitialized: true\nbranch: $(git branch --show-current)\ncommit: $(git log -1 --format=%H)\ntimestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)\nstatus: initialized\n---\n\n# Deployment Tracking\n\nBranch: $(git branch --show-current)\nStarted: $(date)\n\nNext steps:\n1. Run tests: /deploy-test\n2. Build: /deploy-build\n3. Deploy: /deploy-execute\n\\`\\`\\`\n\nState saved. Run `/deploy-test` to continue.\n```\n\n**Next command** (`/deploy-test`):\n```markdown\n---\ndescription: Run deployment tests\nallowed-tools: Read, Bash(npm:*)\n---\n\nReading deployment state from `.claude/deployment-state.local.md`...\n\nRunning tests: !`npm test`\n\nUpdating state to 'tested'...\n\nTests complete. Run `/deploy-build` to continue.\n```\n\n**Pattern benefits:**\n- Persistent state across commands\n- Clear workflow progression\n- Safety checkpoints\n- Resume capability\n\n### Conditional Workflow Branching\n\nCommands that adapt based on conditions:\n\n```markdown\n---\ndescription: Smart deployment workflow\nargument-hint: [environment]\nallowed-tools: Bash(git:*), Bash(npm:*), Read\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\nBranch: !`git branch --show-current`\nStatus: !`git status --short`\n\n**Checking conditions:**\n\n1. Branch status:\n - If main/master: Require approval\n - If feature branch: Warning about target\n - If hotfix: Fast-track process\n\n2. Tests:\n !`npm test`\n - If tests fail: STOP - fix tests first\n - If tests pass: Continue\n\n3. Environment:\n - If $1 = 'production': Extra validation\n - If $1 = 'staging': Standard process\n - If $1 = 'dev': Minimal checks\n\n**Workflow decision:**\nBased on above, proceeding with: [determined workflow]\n\n[Conditional steps based on environment and status]\n\nReady to deploy? (yes/no)\n```\n\n## Command Composition Patterns\n\n### Command Chaining\n\nCommands designed to work together:\n\n```markdown\n---\ndescription: Prepare for code review\n---\n\n# Prepare Code Review\n\nRunning preparation sequence:\n\n1. Format code: /format-code\n2. Run linter: /lint-code\n3. Run tests: /test-all\n4. Generate coverage: /coverage-report\n5. Create review summary: /review-summary\n\nThis is a meta-command. After completing each step above,\nI'll compile results and prepare comprehensive review materials.\n\nStarting sequence...\n```\n\n**Individual commands** are simple:\n- `/format-code` - Just formats\n- `/lint-code` - Just lints\n- `/test-all` - Just tests\n\n**Composition command** orchestrates them.\n\n### Pipeline Pattern\n\nCommands that process output from previous commands:\n\n```markdown\n---\ndescription: Analyze test failures\n---\n\n# Analyze Test Failures\n\n## Step 1: Get test results\n(Run /test-all first if not done)\n\nReading test output...\n\n## Step 2: Categorize failures\n- Flaky tests (random failures)\n- Consistent failures\n- New failures vs existing\n\n## Step 3: Prioritize\nRank by:\n- Impact (critical path vs edge case)\n- Frequency (always fails vs sometimes)\n- Effort (quick fix vs major work)\n\n## Step 4: Generate fix plan\nFor each failure:\n- Root cause hypothesis\n- Suggested fix approach\n- Estimated effort\n\nWould you like me to:\n1. Fix highest priority failure\n2. Generate detailed fix plans for all\n3. Create GitHub issues for each\n```\n\n### Parallel Execution Pattern\n\nCommands that coordinate multiple simultaneous operations:\n\n```markdown\n---\ndescription: Run comprehensive validation\nallowed-tools: Bash(*), Read\n---\n\n# Comprehensive Validation\n\nRunning validations in parallel...\n\nStarting:\n- Code quality checks\n- Security scanning\n- Dependency audit\n- Performance profiling\n\nThis will take 2-3 minutes. I'll monitor all processes\nand report when complete.\n\n[Poll each process and report progress]\n\nAll validations complete. Summary:\n- Quality: PASS (0 issues)\n- Security: WARN (2 minor issues)\n- Dependencies: PASS\n- Performance: PASS (baseline met)\n\nDetails:\n[Collated results from all checks]\n```\n\n## Workflow State Management\n\n### Using .local.md Files\n\nStore workflow state in plugin-specific files:\n\n```markdown\n.claude/plugin-name-workflow.local.md:\n\n---\nworkflow: deployment\nstage: testing\nstarted: 2025-01-15T10:30:00Z\nenvironment: staging\nbranch: feature/new-api\ncommit: abc123def\ntests_passed: false\nbuild_complete: false\n---\n\n# Deployment Workflow State\n\nCurrent stage: Testing\nStarted: 2025-01-15 10:30 UTC\n\nCompleted steps:\n- ✅ Validation\n- ✅ Branch check\n- ⏳ Testing (in progress)\n\nPending steps:\n- Build\n- Deploy\n- Smoke tests\n```\n\n**Reading state in commands:**\n\n```markdown\n---\ndescription: Continue deployment workflow\nallowed-tools: Read, Write\n---\n\nReading workflow state from .claude/plugin-name-workflow.local.md...\n\nCurrent stage: @.claude/plugin-name-workflow.local.md\n\n[Parse YAML frontmatter to determine next step]\n\nNext action based on state: [determined action]\n```\n\n### Workflow Recovery\n\nHandle interrupted workflows:\n\n```markdown\n---\ndescription: Resume deployment workflow\nallowed-tools: Read\n---\n\n# Resume Deployment\n\nChecking for interrupted workflow...\n\nState file: @.claude/plugin-name-workflow.local.md\n\n**Workflow found:**\n- Started: [timestamp]\n- Environment: [env]\n- Last completed: [step]\n\n**Recovery options:**\n1. Resume from last step\n2. Restart from beginning\n3. Abort and clean up\n\nWhich would you like? (1/2/3)\n```\n\n## Workflow Coordination Patterns\n\n### Cross-Command Communication\n\nCommands that signal each other:\n\n```markdown\n---\ndescription: Mark feature complete\nallowed-tools: Write\n---\n\n# Mark Feature Complete\n\nWriting completion marker...\n\nCreating: .claude/feature-complete.flag\n\nThis signals other commands that feature is ready for:\n- Integration testing (/integration-test will auto-detect)\n- Documentation generation (/docs-generate will include)\n- Release notes (/release-notes will add)\n\nFeature marked complete.\n```\n\n**Other commands check for flag:**\n\n```markdown\n---\ndescription: Generate release notes\nallowed-tools: Read, Bash(git:*)\n---\n\nChecking for completed features...\n\nif [ -f .claude/feature-complete.flag ]; then\n Feature ready for release notes\nfi\n\n[Include in release notes]\n```\n\n### Workflow Locking\n\nPrevent concurrent workflow execution:\n\n```markdown\n---\ndescription: Start deployment\nallowed-tools: Read, Write, Bash\n---\n\n# Start Deployment\n\nChecking for active deployments...\n\nif [ -f .claude/deployment.lock ]; then\n ERROR: Deployment already in progress\n Started: [timestamp from lock file]\n\n Cannot start concurrent deployment.\n Wait for completion or run /deployment-abort\n\n Exit.\nfi\n\nCreating deployment lock...\n\nDeployment started. Lock created.\n[Proceed with deployment]\n```\n\n**Lock cleanup:**\n\n```markdown\n---\ndescription: Complete deployment\nallowed-tools: Write, Bash\n---\n\nDeployment complete.\n\nRemoving deployment lock...\nrm .claude/deployment.lock\n\nReady for next deployment.\n```\n\n## Advanced Argument Handling\n\n### Optional Arguments with Defaults\n\n```markdown\n---\ndescription: Deploy with optional version\nargument-hint: [environment] [version]\n---\n\nEnvironment: ${1:-staging}\nVersion: ${2:-latest}\n\nDeploying ${2:-latest} to ${1:-staging}...\n\nNote: Using defaults for missing arguments:\n- Environment defaults to 'staging'\n- Version defaults to 'latest'\n```\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy to validated environment\nargument-hint: [environment]\n---\n\nEnvironment: $1\n\nValidating environment...\n\nvalid_envs=\"dev staging production\"\nif ! echo \"$valid_envs\" | grep -w \"$1\" > /dev/null; then\n ERROR: Invalid environment '$1'\n Valid options: dev, staging, production\n Exit.\nfi\n\nEnvironment validated. Proceeding...\n```\n\n### Argument Transformation\n\n```markdown\n---\ndescription: Deploy with shorthand\nargument-hint: [env-shorthand]\n---\n\nInput: $1\n\nExpanding shorthand:\n- d/dev → development\n- s/stg → staging\n- p/prod → production\n\ncase \"$1\" in\n d|dev) ENV=\"development\";;\n s|stg) ENV=\"staging\";;\n p|prod) ENV=\"production\";;\n *) ENV=\"$1\";;\nesac\n\nDeploying to: $ENV\n```\n\n## Error Handling in Workflows\n\n### Graceful Failure\n\n```markdown\n---\ndescription: Resilient deployment workflow\n---\n\n# Deployment Workflow\n\nRunning steps with error handling...\n\n## Step 1: Tests\n!`npm test`\n\nif [ $? -ne 0 ]; then\n ERROR: Tests failed\n\n Options:\n 1. Fix tests and retry\n 2. Skip tests (NOT recommended)\n 3. Abort deployment\n\n What would you like to do?\n\n [Wait for user input before continuing]\nfi\n\n## Step 2: Build\n[Continue only if Step 1 succeeded]\n```\n\n### Rollback on Failure\n\n```markdown\n---\ndescription: Deployment with rollback\n---\n\n# Deploy with Rollback\n\nSaving current state for rollback...\nPrevious version: !`current-version.sh`\n\nDeploying new version...\n\n!`deploy.sh`\n\nif [ $? -ne 0 ]; then\n DEPLOYMENT FAILED\n\n Initiating automatic rollback...\n !`rollback.sh`\n\n Rolled back to previous version.\n Check logs for failure details.\nfi\n\nDeployment complete.\n```\n\n### Checkpoint Recovery\n\n```markdown\n---\ndescription: Workflow with checkpoints\n---\n\n# Multi-Stage Deployment\n\n## Checkpoint 1: Validation\n!`validate.sh`\necho \"checkpoint:validation\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 2: Build\n!`build.sh`\necho \"checkpoint:build\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 3: Deploy\n!`deploy.sh`\necho \"checkpoint:deploy\" >> .claude/deployment-checkpoints.log\n\nIf any step fails, resume with:\n/deployment-resume [last-successful-checkpoint]\n```\n\n## Best Practices\n\n### Workflow Design\n\n1. **Clear progression**: Number steps, show current position\n2. **Explicit state**: Don't rely on implicit state\n3. **User control**: Provide decision points\n4. **Error recovery**: Handle failures gracefully\n5. **Progress indication**: Show what's done, what's pending\n\n### Command Composition\n\n1. **Single responsibility**: Each command does one thing well\n2. **Composable design**: Commands work together easily\n3. **Standard interfaces**: Consistent input/output formats\n4. **Loose coupling**: Commands don't depend on each other's internals\n\n### State Management\n\n1. **Persistent state**: Use .local.md files\n2. **Atomic updates**: Write complete state files atomically\n3. **State validation**: Check state file format/completeness\n4. **Cleanup**: Remove stale state files\n5. **Documentation**: Document state file formats\n\n### Error Handling\n\n1. **Fail fast**: Detect errors early\n2. **Clear messages**: Explain what went wrong\n3. **Recovery options**: Provide clear next steps\n4. **State preservation**: Keep state for recovery\n5. **Rollback capability**: Support undoing changes\n\n## Example: Complete Deployment Workflow\n\n### Initialize Command\n\n```markdown\n---\ndescription: Initialize deployment\nargument-hint: [environment]\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment to $1\n\nCreating workflow state...\n\n\\`\\`\\`yaml\n---\nworkflow: deployment\nenvironment: $1\nbranch: !`git branch --show-current`\ncommit: !`git rev-parse HEAD`\nstage: initialized\ntimestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`\n---\n\\`\\`\\`\n\nWritten to .claude/deployment-state.local.md\n\nNext: Run /deployment-validate\n```\n\n### Validation Command\n\n```markdown\n---\ndescription: Validate deployment\nallowed-tools: Read, Bash\n---\n\nReading state: @.claude/deployment-state.local.md\n\nRunning validation...\n- Branch check: PASS\n- Tests: PASS\n- Build: PASS\n\nUpdating state to 'validated'...\n\nNext: Run /deployment-execute\n```\n\n### Execution Command\n\n```markdown\n---\ndescription: Execute deployment\nallowed-tools: Read, Bash, Write\n---\n\nReading state: @.claude/deployment-state.local.md\n\nExecuting deployment to [environment]...\n\n!`deploy.sh [environment]`\n\nDeployment complete.\nUpdating state to 'completed'...\n\nCleanup: /deployment-cleanup\n```\n\n### Cleanup Command\n\n```markdown\n---\ndescription: Clean up deployment\nallowed-tools: Bash\n---\n\nRemoving deployment state...\nrm .claude/deployment-state.local.md\n\nDeployment workflow complete.\n```\n\nThis complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.\n","plugins/plugin-dev/skills/command-development/references/documentation-patterns.md":"# Command Documentation Patterns\n\nStrategies for creating self-documenting, maintainable commands with excellent user experience.\n\n## Overview\n\nWell-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.\n\n## Self-Documenting Command Structure\n\n### Complete Command Template\n\n```markdown\n---\ndescription: Clear, actionable description under 60 chars\nargument-hint: [arg1] [arg2] [optional-arg]\nallowed-tools: Read, Bash(git:*)\nmodel: sonnet\n---\n\n\n\n# Command Implementation\n\n[Command prompt content here...]\n\n[Explain what will happen...]\n\n[Guide user through steps...]\n\n[Provide clear output...]\n```\n\n### Documentation Comment Sections\n\n**PURPOSE**: Why the command exists\n- Problem it solves\n- Use cases\n- When to use vs when not to use\n\n**USAGE**: Basic syntax\n- Command invocation pattern\n- Required vs optional arguments\n- Default values\n\n**ARGUMENTS**: Detailed argument documentation\n- Each argument described\n- Type information\n- Valid values/ranges\n- Defaults\n\n**EXAMPLES**: Concrete usage examples\n- Common use cases\n- Edge cases\n- Expected outputs\n\n**REQUIREMENTS**: Prerequisites\n- Dependencies\n- Permissions\n- Environmental setup\n\n**RELATED COMMANDS**: Connections\n- Similar commands\n- Complementary commands\n- Alternative approaches\n\n**TROUBLESHOOTING**: Common issues\n- Known problems\n- Solutions\n- Workarounds\n\n**CHANGELOG**: Version history\n- What changed when\n- Breaking changes highlighted\n- Migration guidance\n\n## In-Line Documentation Patterns\n\n### Commented Sections\n\n```markdown\n---\ndescription: Complex multi-step command\n---\n\n\n\n\nChecking prerequisites...\n- Git repository: !`git rev-parse --git-dir 2>/dev/null`\n- Branch exists: [validation logic]\n\n\n\n\nAnalyzing differences between $1 and $2...\n[Analysis logic...]\n\n\n\n\nBased on analysis, recommend:\n[Recommendations...]\n\n\n```\n\n### Inline Explanations\n\n```markdown\n---\ndescription: Deployment command with inline docs\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\n\nCurrent branch: !`git branch --show-current`\n\n\nif [ \"$1\" = \"production\" ] && [ \"$(git branch --show-current)\" != \"main\" ]; then\n ⚠️ WARNING: Not on main branch for production deploy\n This is unusual. Confirm this is intentional.\nfi\n\n\nRunning tests: !`npm test`\n\n✓ All checks passed\n\n## Deployment\n\n\n\nDeploying to $1 environment...\n[Deployment steps...]\n\n\nVerifying deployment health...\n[Health checks...]\n\nDeployment complete!\n\n## Next Steps\n\n\n1. Monitor logs: /logs $1\n2. Run smoke tests: /smoke-test $1\n3. Notify team: /notify-deployment $1\n```\n\n### Decision Point Documentation\n\n```markdown\n---\ndescription: Interactive deployment command\n---\n\n# Interactive Deployment\n\n## Configuration Review\n\nTarget: $1\nCurrent version: !`cat version.txt`\nNew version: $2\n\n\n\n\n\nReview the above configuration.\n\n**Continue with deployment?**\n- Reply \"yes\" to proceed\n- Reply \"no\" to cancel\n- Reply \"edit\" to modify configuration\n\n[Await user input before continuing...]\n\n\n\n\nProceeding with deployment...\n```\n\n## Help Text Patterns\n\n### Built-in Help Command\n\nCreate a help subcommand for complex commands:\n\n```markdown\n---\ndescription: Main command with help\nargument-hint: [subcommand] [args]\n---\n\n# Command Processor\n\nif [ \"$1\" = \"help\" ] || [ \"$1\" = \"--help\" ] || [ \"$1\" = \"-h\" ]; then\n **Command Help**\n\n USAGE:\n /command [subcommand] [args]\n\n SUBCOMMANDS:\n init [name] Initialize new configuration\n deploy [env] Deploy to environment\n status Show current status\n rollback Rollback last deployment\n help Show this help\n\n EXAMPLES:\n /command init my-project\n /command deploy staging\n /command status\n /command rollback\n\n For detailed help on a subcommand:\n /command [subcommand] --help\n\n Exit.\nfi\n\n[Regular command processing...]\n```\n\n### Contextual Help\n\nProvide help based on context:\n\n```markdown\n---\ndescription: Context-aware command\nargument-hint: [operation] [target]\n---\n\n# Context-Aware Operation\n\nif [ -z \"$1\" ]; then\n **No operation specified**\n\n Available operations:\n - analyze: Analyze target for issues\n - fix: Apply automatic fixes\n - report: Generate detailed report\n\n Usage: /command [operation] [target]\n\n Examples:\n /command analyze src/\n /command fix src/app.js\n /command report\n\n Run /command help for more details.\n\n Exit.\nfi\n\n[Command continues if operation provided...]\n```\n\n## Error Message Documentation\n\n### Helpful Error Messages\n\n```markdown\n---\ndescription: Command with good error messages\n---\n\n# Validation Command\n\nif [ -z \"$1\" ]; then\n ❌ ERROR: Missing required argument\n\n The 'file-path' argument is required.\n\n USAGE:\n /validate [file-path]\n\n EXAMPLE:\n /validate src/app.js\n\n Try again with a file path.\n\n Exit.\nfi\n\nif [ ! -f \"$1\" ]; then\n ❌ ERROR: File not found: $1\n\n The specified file does not exist or is not accessible.\n\n COMMON CAUSES:\n 1. Typo in file path\n 2. File was deleted or moved\n 3. Insufficient permissions\n\n SUGGESTIONS:\n - Check spelling: $1\n - Verify file exists: ls -la $(dirname \"$1\")\n - Check permissions: ls -l \"$1\"\n\n Exit.\nfi\n\n[Command continues if validation passes...]\n```\n\n### Error Recovery Guidance\n\n```markdown\n---\ndescription: Command with recovery guidance\n---\n\n# Operation Command\n\nRunning operation...\n\n!`risky-operation.sh`\n\nif [ $? -ne 0 ]; then\n ❌ OPERATION FAILED\n\n The operation encountered an error and could not complete.\n\n WHAT HAPPENED:\n The risky-operation.sh script returned a non-zero exit code.\n\n WHAT THIS MEANS:\n - Changes may be partially applied\n - System may be in inconsistent state\n - Manual intervention may be needed\n\n RECOVERY STEPS:\n 1. Check operation logs: cat /tmp/operation.log\n 2. Verify system state: /check-state\n 3. If needed, rollback: /rollback-operation\n 4. Fix underlying issue\n 5. Retry operation: /retry-operation\n\n NEED HELP?\n - Check troubleshooting guide: /help troubleshooting\n - Contact support with error code: ERR_OP_FAILED_001\n\n Exit.\nfi\n```\n\n## Usage Example Documentation\n\n### Embedded Examples\n\n```markdown\n---\ndescription: Command with embedded examples\n---\n\n# Feature Command\n\nThis command performs feature analysis with multiple options.\n\n## Basic Usage\n\n\\`\\`\\`\n/feature analyze src/\n\\`\\`\\`\n\nAnalyzes all files in src/ directory for feature usage.\n\n## Advanced Usage\n\n\\`\\`\\`\n/feature analyze src/ --detailed\n\\`\\`\\`\n\nProvides detailed analysis including:\n- Feature breakdown by file\n- Usage patterns\n- Optimization suggestions\n\n## Use Cases\n\n**Use Case 1: Quick overview**\n\\`\\`\\`\n/feature analyze .\n\\`\\`\\`\nGet high-level feature summary of entire project.\n\n**Use Case 2: Specific directory**\n\\`\\`\\`\n/feature analyze src/components\n\\`\\`\\`\nFocus analysis on components directory only.\n\n**Use Case 3: Comparison**\n\\`\\`\\`\n/feature analyze src/ --compare baseline.json\n\\`\\`\\`\nCompare current features against baseline.\n\n---\n\nNow processing your request...\n\n[Command implementation...]\n```\n\n### Example-Driven Documentation\n\n```markdown\n---\ndescription: Example-heavy command\n---\n\n# Transformation Command\n\n## What This Does\n\nTransforms data from one format to another.\n\n## Examples First\n\n### Example 1: JSON to YAML\n**Input:** `data.json`\n\\`\\`\\`json\n{\"name\": \"test\", \"value\": 42}\n\\`\\`\\`\n\n**Command:** `/transform data.json yaml`\n\n**Output:** `data.yaml`\n\\`\\`\\`yaml\nname: test\nvalue: 42\n\\`\\`\\`\n\n### Example 2: CSV to JSON\n**Input:** `data.csv`\n\\`\\`\\`csv\nname,value\ntest,42\n\\`\\`\\`\n\n**Command:** `/transform data.csv json`\n\n**Output:** `data.json`\n\\`\\`\\`json\n[{\"name\": \"test\", \"value\": \"42\"}]\n\\`\\`\\`\n\n### Example 3: With Options\n**Command:** `/transform data.json yaml --pretty --sort-keys`\n\n**Result:** Formatted YAML with sorted keys\n\n---\n\n## Your Transformation\n\nFile: $1\nFormat: $2\n\n[Perform transformation...]\n```\n\n## Maintenance Documentation\n\n### Version and Changelog\n\n```markdown\n\n```\n\n### Maintenance Notes\n\n```markdown\n\n```\n\n## README Documentation\n\nCommands should have companion README files:\n\n```markdown\n# Command Name\n\nBrief description of what the command does.\n\n## Installation\n\nThis command is part of the [plugin-name] plugin.\n\nInstall with:\n\\`\\`\\`\n/plugin install plugin-name\n\\`\\`\\`\n\n## Usage\n\nBasic usage:\n\\`\\`\\`\n/command-name [arg1] [arg2]\n\\`\\`\\`\n\n## Arguments\n\n- `arg1`: Description (required)\n- `arg2`: Description (optional, defaults to X)\n\n## Examples\n\n### Example 1: Basic Usage\n\\`\\`\\`\n/command-name value1 value2\n\\`\\`\\`\n\nDescription of what happens.\n\n### Example 2: Advanced Usage\n\\`\\`\\`\n/command-name value1 --option\n\\`\\`\\`\n\nDescription of advanced feature.\n\n## Configuration\n\nOptional configuration file: `.claude/command-name.local.md`\n\n\\`\\`\\`markdown\n---\ndefault_arg: value\nenable_feature: true\n---\n\\`\\`\\`\n\n## Requirements\n\n- Git 2.x or later\n- jq (for JSON processing)\n- Node.js 14+ (optional, for advanced features)\n\n## Troubleshooting\n\n### Issue: Command not found\n\n**Solution:** Ensure plugin is installed and enabled.\n\n### Issue: Permission denied\n\n**Solution:** Check file permissions and allowed-tools setting.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT License - See [LICENSE](LICENSE).\n\n## Support\n\n- Issues: https://github.com/user/plugin/issues\n- Docs: https://docs.example.com\n- Email: support@example.com\n```\n\n## Best Practices\n\n### Documentation Principles\n\n1. **Write for your future self**: Assume you'll forget details\n2. **Examples before explanations**: Show, then tell\n3. **Progressive disclosure**: Basic info first, details available\n4. **Keep it current**: Update docs when code changes\n5. **Test your docs**: Verify examples actually work\n\n### Documentation Locations\n\n1. **In command file**: Core usage, examples, inline explanations\n2. **README**: Installation, configuration, troubleshooting\n3. **Separate docs**: Detailed guides, tutorials, API reference\n4. **Comments**: Implementation details for maintainers\n\n### Documentation Style\n\n1. **Clear and concise**: No unnecessary words\n2. **Active voice**: \"Run the command\" not \"The command can be run\"\n3. **Consistent terminology**: Use same terms throughout\n4. **Formatted well**: Use headings, lists, code blocks\n5. **Accessible**: Assume reader is beginner\n\n### Documentation Maintenance\n\n1. **Version everything**: Track what changed when\n2. **Deprecate gracefully**: Warn before removing features\n3. **Migration guides**: Help users upgrade\n4. **Archive old docs**: Keep old versions accessible\n5. **Review regularly**: Ensure docs match reality\n\n## Documentation Checklist\n\nBefore releasing a command:\n\n- [ ] Description in frontmatter is clear\n- [ ] argument-hint documents all arguments\n- [ ] Usage examples in comments\n- [ ] Common use cases shown\n- [ ] Error messages are helpful\n- [ ] Requirements documented\n- [ ] Related commands listed\n- [ ] Changelog maintained\n- [ ] Version number updated\n- [ ] README created/updated\n- [ ] Examples actually work\n- [ ] Troubleshooting section complete\n\nWith good documentation, commands become self-service, reducing support burden and improving user experience.\n","plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md":"# Command Frontmatter Reference\n\nComplete reference for YAML frontmatter fields in slash commands.\n\n## Frontmatter Overview\n\nYAML frontmatter is optional metadata at the start of command files:\n\n```markdown\n---\ndescription: Brief description\nallowed-tools: Read, Write\nmodel: sonnet\nargument-hint: [arg1] [arg2]\n---\n\nCommand prompt content here...\n```\n\nAll fields are optional. Commands work without any frontmatter.\n\n## Field Specifications\n\n### description\n\n**Type:** String\n**Required:** No\n**Default:** First line of command prompt\n**Max Length:** ~60 characters recommended for `/help` display\n\n**Purpose:** Describes what the command does, shown in `/help` output\n\n**Examples:**\n```yaml\ndescription: Review code for security issues\n```\n```yaml\ndescription: Deploy to staging environment\n```\n```yaml\ndescription: Generate API documentation\n```\n\n**Best practices:**\n- Keep under 60 characters for clean display\n- Start with verb (Review, Deploy, Generate)\n- Be specific about what command does\n- Avoid redundant \"command\" or \"slash command\"\n\n**Good:**\n- ✅ \"Review PR for code quality and security\"\n- ✅ \"Deploy application to specified environment\"\n- ✅ \"Generate comprehensive API documentation\"\n\n**Bad:**\n- ❌ \"This command reviews PRs\" (unnecessary \"This command\")\n- ❌ \"Review\" (too vague)\n- ❌ \"A command that reviews pull requests for code quality, security issues, and best practices\" (too long)\n\n### allowed-tools\n\n**Type:** String or Array of strings\n**Required:** No\n**Default:** Inherits from conversation permissions\n\n**Purpose:** Restrict or specify which tools command can use\n\n**Formats:**\n\n**Single tool:**\n```yaml\nallowed-tools: Read\n```\n\n**Multiple tools (comma-separated):**\n```yaml\nallowed-tools: Read, Write, Edit\n```\n\n**Multiple tools (array):**\n```yaml\nallowed-tools:\n - Read\n - Write\n - Bash(git:*)\n```\n\n**Tool Patterns:**\n\n**Specific tools:**\n```yaml\nallowed-tools: Read, Grep, Edit\n```\n\n**Bash with command filter:**\n```yaml\nallowed-tools: Bash(git:*) # Only git commands\nallowed-tools: Bash(npm:*) # Only npm commands\nallowed-tools: Bash(docker:*) # Only docker commands\n```\n\n**All tools (not recommended):**\n```yaml\nallowed-tools: \"*\"\n```\n\n**When to use:**\n\n1. **Security:** Restrict command to safe operations\n ```yaml\n allowed-tools: Read, Grep # Read-only command\n ```\n\n2. **Clarity:** Document required tools\n ```yaml\n allowed-tools: Bash(git:*), Read\n ```\n\n3. **Bash execution:** Enable bash command output\n ```yaml\n allowed-tools: Bash(git status:*), Bash(git diff:*)\n ```\n\n**Best practices:**\n- Be as restrictive as possible\n- Use command filters for Bash (e.g., `git:*` not `*`)\n- Only specify when different from conversation permissions\n- Document why specific tools are needed\n\n### model\n\n**Type:** String\n**Required:** No\n**Default:** Inherits from conversation\n**Values:** `sonnet`, `opus`, `haiku`\n\n**Purpose:** Specify which Claude model executes the command\n\n**Examples:**\n```yaml\nmodel: haiku # Fast, efficient for simple tasks\n```\n```yaml\nmodel: sonnet # Balanced performance (default)\n```\n```yaml\nmodel: opus # Maximum capability for complex tasks\n```\n\n**When to use:**\n\n**Use `haiku` for:**\n- Simple, formulaic commands\n- Fast execution needed\n- Low complexity tasks\n- Frequent invocations\n\n```yaml\n---\ndescription: Format code file\nmodel: haiku\n---\n```\n\n**Use `sonnet` for:**\n- Standard commands (default)\n- Balanced speed/quality\n- Most common use cases\n\n```yaml\n---\ndescription: Review code changes\nmodel: sonnet\n---\n```\n\n**Use `opus` for:**\n- Complex analysis\n- Architectural decisions\n- Deep code understanding\n- Critical tasks\n\n```yaml\n---\ndescription: Analyze system architecture\nmodel: opus\n---\n```\n\n**Best practices:**\n- Omit unless specific need\n- Use `haiku` for speed when possible\n- Reserve `opus` for genuinely complex tasks\n- Test with different models to find right balance\n\n### argument-hint\n\n**Type:** String\n**Required:** No\n**Default:** None\n\n**Purpose:** Document expected arguments for users and autocomplete\n\n**Format:**\n```yaml\nargument-hint: [arg1] [arg2] [optional-arg]\n```\n\n**Examples:**\n\n**Single argument:**\n```yaml\nargument-hint: [pr-number]\n```\n\n**Multiple required arguments:**\n```yaml\nargument-hint: [environment] [version]\n```\n\n**Optional arguments:**\n```yaml\nargument-hint: [file-path] [options]\n```\n\n**Descriptive names:**\n```yaml\nargument-hint: [source-branch] [target-branch] [commit-message]\n```\n\n**Best practices:**\n- Use square brackets `[]` for each argument\n- Use descriptive names (not `arg1`, `arg2`)\n- Indicate optional vs required in description\n- Match order to positional arguments in command\n- Keep concise but clear\n\n**Examples by pattern:**\n\n**Simple command:**\n```yaml\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$1...\n```\n\n**Multi-argument:**\n```yaml\n---\ndescription: Deploy to environment\nargument-hint: [app-name] [environment] [version]\n---\n\nDeploy $1 to $2 using version $3...\n```\n\n**With options:**\n```yaml\n---\ndescription: Run tests with options\nargument-hint: [test-pattern] [options]\n---\n\nRun tests matching $1 with options: $2\n```\n\n### disable-model-invocation\n\n**Type:** Boolean\n**Required:** No\n**Default:** false\n\n**Purpose:** Prevent SlashCommand tool from programmatically invoking command\n\n**Examples:**\n```yaml\ndisable-model-invocation: true\n```\n\n**When to use:**\n\n1. **Manual-only commands:** Commands requiring user judgment\n ```yaml\n ---\n description: Approve deployment to production\n disable-model-invocation: true\n ---\n ```\n\n2. **Destructive operations:** Commands with irreversible effects\n ```yaml\n ---\n description: Delete all test data\n disable-model-invocation: true\n ---\n ```\n\n3. **Interactive workflows:** Commands needing user input\n ```yaml\n ---\n description: Walk through setup wizard\n disable-model-invocation: true\n ---\n ```\n\n**Default behavior (false):**\n- Command available to SlashCommand tool\n- Claude can invoke programmatically\n- Still available for manual invocation\n\n**When true:**\n- Command only invokable by user typing `/command`\n- Not available to SlashCommand tool\n- Safer for sensitive operations\n\n**Best practices:**\n- Use sparingly (limits Claude's autonomy)\n- Document why in command comments\n- Consider if command should exist if always manual\n\n## Complete Examples\n\n### Minimal Command\n\nNo frontmatter needed:\n\n```markdown\nReview this code for common issues and suggest improvements.\n```\n\n### Simple Command\n\nJust description:\n\n```markdown\n---\ndescription: Review code for issues\n---\n\nReview this code for common issues and suggest improvements.\n```\n\n### Standard Command\n\nDescription and tools:\n\n```markdown\n---\ndescription: Review Git changes\nallowed-tools: Bash(git:*), Read\n---\n\nCurrent changes: !`git diff --name-only`\n\nReview each changed file for:\n- Code quality\n- Potential bugs\n- Best practices\n```\n\n### Complex Command\n\nAll common fields:\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [app-name] [environment] [version]\nallowed-tools: Bash(kubectl:*), Bash(helm:*), Read\nmodel: sonnet\n---\n\nDeploy $1 to $2 environment using version $3\n\nPre-deployment checks:\n- Verify $2 configuration\n- Check cluster status: !`kubectl cluster-info`\n- Validate version $3 exists\n\nProceed with deployment following deployment runbook.\n```\n\n### Manual-Only Command\n\nRestricted invocation:\n\n```markdown\n---\ndescription: Approve production deployment\nargument-hint: [deployment-id]\ndisable-model-invocation: true\nallowed-tools: Bash(gh:*)\n---\n\n\n\nReview deployment $1 for production approval:\n\nDeployment details: !`gh api /deployments/$1`\n\nVerify:\n- All tests passed\n- Security scan clean\n- Stakeholder approval\n- Rollback plan ready\n\nType \"APPROVED\" to confirm deployment.\n```\n\n## Validation\n\n### Common Errors\n\n**Invalid YAML syntax:**\n```yaml\n---\ndescription: Missing quote\nallowed-tools: Read, Write\nmodel: sonnet\n--- # ❌ Missing closing quote above\n```\n\n**Fix:** Validate YAML syntax\n\n**Incorrect tool specification:**\n```yaml\nallowed-tools: Bash # ❌ Missing command filter\n```\n\n**Fix:** Use `Bash(git:*)` format\n\n**Invalid model name:**\n```yaml\nmodel: gpt4 # ❌ Not a valid Claude model\n```\n\n**Fix:** Use `sonnet`, `opus`, or `haiku`\n\n### Validation Checklist\n\nBefore committing command:\n- [ ] YAML syntax valid (no errors)\n- [ ] Description under 60 characters\n- [ ] allowed-tools uses proper format\n- [ ] model is valid value if specified\n- [ ] argument-hint matches positional arguments\n- [ ] disable-model-invocation used appropriately\n\n## Best Practices Summary\n\n1. **Start minimal:** Add frontmatter only when needed\n2. **Document arguments:** Always use argument-hint with arguments\n3. **Restrict tools:** Use most restrictive allowed-tools that works\n4. **Choose right model:** Use haiku for speed, opus for complexity\n5. **Manual-only sparingly:** Only use disable-model-invocation when necessary\n6. **Clear descriptions:** Make commands discoverable in `/help`\n7. **Test thoroughly:** Verify frontmatter works as expected\n","plugins/plugin-dev/skills/command-development/references/interactive-commands.md":"# Interactive Command Patterns\n\nComprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.\n\n## Overview\n\nSome commands need user input that doesn't work well with simple arguments. For example:\n- Choosing between multiple complex options with trade-offs\n- Selecting multiple items from a list\n- Making decisions that require explanation\n- Gathering preferences or configuration interactively\n\nFor these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments.\n\n## When to Use AskUserQuestion\n\n### Use AskUserQuestion When:\n\n1. **Multiple choice decisions** with explanations needed\n2. **Complex options** that require context to choose\n3. **Multi-select scenarios** (choosing multiple items)\n4. **Preference gathering** for configuration\n5. **Interactive workflows** that adapt based on answers\n\n### Use Command Arguments When:\n\n1. **Simple values** (file paths, numbers, names)\n2. **Known inputs** user already has\n3. **Scriptable workflows** that should be automatable\n4. **Fast invocations** where prompting would slow down\n\n## AskUserQuestion Basics\n\n### Tool Parameters\n\n```typescript\n{\n questions: [\n {\n question: \"Which authentication method should we use?\",\n header: \"Auth method\", // Short label (max 12 chars)\n multiSelect: false, // true for multiple selection\n options: [\n {\n label: \"OAuth 2.0\",\n description: \"Industry standard, supports multiple providers\"\n },\n {\n label: \"JWT\",\n description: \"Stateless, good for APIs\"\n },\n {\n label: \"Session\",\n description: \"Traditional, server-side state\"\n }\n ]\n }\n ]\n}\n```\n\n**Key points:**\n- Users can always choose \"Other\" to provide custom input (automatic)\n- `multiSelect: true` allows selecting multiple options\n- Options should be 2-4 choices (not more)\n- Can ask 1-4 questions per tool call\n\n## Command Pattern for User Interaction\n\n### Basic Interactive Command\n\n```markdown\n---\ndescription: Interactive setup command\nallowed-tools: AskUserQuestion, Write\n---\n\n# Interactive Plugin Setup\n\nThis command will guide you through configuring the plugin with a series of questions.\n\n## Step 1: Gather Configuration\n\nUse the AskUserQuestion tool to ask:\n\n**Question 1 - Deployment target:**\n- header: \"Deploy to\"\n- question: \"Which deployment platform will you use?\"\n- options:\n - AWS (Amazon Web Services with ECS/EKS)\n - GCP (Google Cloud with GKE)\n - Azure (Microsoft Azure with AKS)\n - Local (Docker on local machine)\n\n**Question 2 - Environment strategy:**\n- header: \"Environments\"\n- question: \"How many environments do you need?\"\n- options:\n - Single (Just production)\n - Standard (Dev, Staging, Production)\n - Complete (Dev, QA, Staging, Production)\n\n**Question 3 - Features to enable:**\n- header: \"Features\"\n- question: \"Which features do you want to enable?\"\n- multiSelect: true\n- options:\n - Auto-scaling (Automatic resource scaling)\n - Monitoring (Health checks and metrics)\n - CI/CD (Automated deployment pipeline)\n - Backups (Automated database backups)\n\n## Step 2: Process Answers\n\nBased on the answers received from AskUserQuestion:\n\n1. Parse the deployment target choice\n2. Set up environment-specific configuration\n3. Enable selected features\n4. Generate configuration files\n\n## Step 3: Generate Configuration\n\nCreate `.claude/plugin-name.local.md` with:\n\n\\`\\`\\`yaml\n---\ndeployment_target: [answer from Q1]\nenvironments: [answer from Q2]\nfeatures:\n auto_scaling: [true if selected in Q3]\n monitoring: [true if selected in Q3]\n ci_cd: [true if selected in Q3]\n backups: [true if selected in Q3]\n---\n\n# Plugin Configuration\n\nGenerated: [timestamp]\nTarget: [deployment_target]\nEnvironments: [environments]\n\\`\\`\\`\n\n## Step 4: Confirm and Next Steps\n\nConfirm configuration created and guide user on next steps.\n```\n\n### Multi-Stage Interactive Workflow\n\n```markdown\n---\ndescription: Multi-stage interactive workflow\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Multi-Stage Deployment Setup\n\nThis command walks through deployment setup in stages, adapting based on your answers.\n\n## Stage 1: Basic Configuration\n\nUse AskUserQuestion to ask about deployment basics.\n\nBased on answers, determine which additional questions to ask.\n\n## Stage 2: Advanced Options (Conditional)\n\nIf user selected \"Advanced\" deployment in Stage 1:\n\nUse AskUserQuestion to ask about:\n- Load balancing strategy\n- Caching configuration\n- Security hardening options\n\nIf user selected \"Simple\" deployment:\n- Skip advanced questions\n- Use sensible defaults\n\n## Stage 3: Confirmation\n\nShow summary of all selections.\n\nUse AskUserQuestion for final confirmation:\n- header: \"Confirm\"\n- question: \"Does this configuration look correct?\"\n- options:\n - Yes (Proceed with setup)\n - No (Start over)\n - Modify (Let me adjust specific settings)\n\nIf \"Modify\", ask which specific setting to change.\n\n## Stage 4: Execute Setup\n\nBased on confirmed configuration, execute setup steps.\n```\n\n## Interactive Question Design\n\n### Question Structure\n\n**Good questions:**\n```markdown\nQuestion: \"Which database should we use for this project?\"\nHeader: \"Database\"\nOptions:\n - PostgreSQL (Relational, ACID compliant, best for complex queries)\n - MongoDB (Document store, flexible schema, best for rapid iteration)\n - Redis (In-memory, fast, best for caching and sessions)\n```\n\n**Poor questions:**\n```markdown\nQuestion: \"Database?\" // Too vague\nHeader: \"DB\" // Unclear abbreviation\nOptions:\n - Option 1 // Not descriptive\n - Option 2\n```\n\n### Option Design Best Practices\n\n**Clear labels:**\n- Use 1-5 words\n- Specific and descriptive\n- No jargon without context\n\n**Helpful descriptions:**\n- Explain what the option means\n- Mention key benefits or trade-offs\n- Help user make informed decision\n- Keep to 1-2 sentences\n\n**Appropriate number:**\n- 2-4 options per question\n- Don't overwhelm with too many choices\n- Group related options\n- \"Other\" automatically provided\n\n### Multi-Select Questions\n\n**When to use multiSelect:**\n\n```markdown\nUse AskUserQuestion for enabling features:\n\nQuestion: \"Which features do you want to enable?\"\nHeader: \"Features\"\nmultiSelect: true // Allow selecting multiple\nOptions:\n - Logging (Detailed operation logs)\n - Metrics (Performance monitoring)\n - Alerts (Error notifications)\n - Backups (Automatic backups)\n```\n\nUser can select any combination: none, some, or all.\n\n**When NOT to use multiSelect:**\n\n```markdown\nQuestion: \"Which authentication method?\"\nmultiSelect: false // Only one auth method makes sense\n```\n\nMutually exclusive choices should not use multiSelect.\n\n## Command Patterns with AskUserQuestion\n\n### Pattern 1: Simple Yes/No Decision\n\n```markdown\n---\ndescription: Command with confirmation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Destructive Operation\n\nThis operation will delete all cached data.\n\nUse AskUserQuestion to confirm:\n\nQuestion: \"This will delete all cached data. Are you sure?\"\nHeader: \"Confirm\"\nOptions:\n - Yes (Proceed with deletion)\n - No (Cancel operation)\n\nIf user selects \"Yes\":\n Execute deletion\n Report completion\n\nIf user selects \"No\":\n Cancel operation\n Exit without changes\n```\n\n### Pattern 2: Multiple Configuration Questions\n\n```markdown\n---\ndescription: Multi-question configuration\nallowed-tools: AskUserQuestion, Write\n---\n\n# Project Configuration Setup\n\nGather configuration through multiple questions.\n\nUse AskUserQuestion with multiple questions in one call:\n\n**Question 1:**\n- question: \"Which programming language?\"\n- header: \"Language\"\n- options: Python, TypeScript, Go, Rust\n\n**Question 2:**\n- question: \"Which test framework?\"\n- header: \"Testing\"\n- options: Jest, PyTest, Go Test, Cargo Test\n (Adapt based on language from Q1)\n\n**Question 3:**\n- question: \"Which CI/CD platform?\"\n- header: \"CI/CD\"\n- options: GitHub Actions, GitLab CI, CircleCI\n\n**Question 4:**\n- question: \"Which features do you need?\"\n- header: \"Features\"\n- multiSelect: true\n- options: Linting, Type checking, Code coverage, Security scanning\n\nProcess all answers together to generate cohesive configuration.\n```\n\n### Pattern 3: Conditional Question Flow\n\n```markdown\n---\ndescription: Conditional interactive workflow\nallowed-tools: AskUserQuestion, Read, Write\n---\n\n# Adaptive Configuration\n\n## Question 1: Deployment Complexity\n\nUse AskUserQuestion:\n\nQuestion: \"How complex is your deployment?\"\nHeader: \"Complexity\"\nOptions:\n - Simple (Single server, straightforward)\n - Standard (Multiple servers, load balancing)\n - Complex (Microservices, orchestration)\n\n## Conditional Questions Based on Answer\n\nIf answer is \"Simple\":\n - No additional questions\n - Use minimal configuration\n\nIf answer is \"Standard\":\n - Ask about load balancing strategy\n - Ask about scaling policy\n\nIf answer is \"Complex\":\n - Ask about orchestration platform (Kubernetes, Docker Swarm)\n - Ask about service mesh (Istio, Linkerd, None)\n - Ask about monitoring (Prometheus, Datadog, CloudWatch)\n - Ask about logging aggregation\n\n## Process Conditional Answers\n\nGenerate configuration appropriate for selected complexity level.\n```\n\n### Pattern 4: Iterative Collection\n\n```markdown\n---\ndescription: Collect multiple items iteratively\nallowed-tools: AskUserQuestion, Write\n---\n\n# Collect Team Members\n\nWe'll collect team member information for the project.\n\n## Question: How many team members?\n\nUse AskUserQuestion:\n\nQuestion: \"How many team members should we set up?\"\nHeader: \"Team size\"\nOptions:\n - 2 people\n - 3 people\n - 4 people\n - 6 people\n\n## Iterate Through Team Members\n\nFor each team member (1 to N based on answer):\n\nUse AskUserQuestion for member details:\n\nQuestion: \"What role for team member [number]?\"\nHeader: \"Role\"\nOptions:\n - Frontend Developer\n - Backend Developer\n - DevOps Engineer\n - QA Engineer\n - Designer\n\nStore each member's information.\n\n## Generate Team Configuration\n\nAfter collecting all N members, create team configuration file with all members and their roles.\n```\n\n### Pattern 5: Dependency Selection\n\n```markdown\n---\ndescription: Select dependencies with multi-select\nallowed-tools: AskUserQuestion\n---\n\n# Configure Project Dependencies\n\n## Question: Required Libraries\n\nUse AskUserQuestion with multiSelect:\n\nQuestion: \"Which libraries does your project need?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - React (UI framework)\n - Express (Web server)\n - TypeORM (Database ORM)\n - Jest (Testing framework)\n - Axios (HTTP client)\n\nUser can select any combination.\n\n## Process Selections\n\nFor each selected library:\n- Add to package.json dependencies\n- Generate sample configuration\n- Create usage examples\n- Update documentation\n```\n\n## Best Practices for Interactive Commands\n\n### Question Design\n\n1. **Clear and specific**: Question should be unambiguous\n2. **Concise header**: Max 12 characters for clean display\n3. **Helpful options**: Labels are clear, descriptions explain trade-offs\n4. **Appropriate count**: 2-4 options per question, 1-4 questions per call\n5. **Logical order**: Questions flow naturally\n\n### Error Handling\n\n```markdown\n# Handle AskUserQuestion Responses\n\nAfter calling AskUserQuestion, verify answers received:\n\nIf answers are empty or invalid:\n Something went wrong gathering responses.\n\n Please try again or provide configuration manually:\n [Show alternative approach]\n\n Exit.\n\nIf answers look correct:\n Process as expected\n```\n\n### Progressive Disclosure\n\n```markdown\n# Start Simple, Get Detailed as Needed\n\n## Question 1: Setup Type\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to set up?\"\nHeader: \"Setup type\"\nOptions:\n - Quick (Use recommended defaults)\n - Custom (Configure all options)\n - Guided (Step-by-step with explanations)\n\nIf \"Quick\":\n Apply defaults, minimal questions\n\nIf \"Custom\":\n Ask all available configuration questions\n\nIf \"Guided\":\n Ask questions with extra explanation\n Provide recommendations along the way\n```\n\n### Multi-Select Guidelines\n\n**Good multi-select use:**\n```markdown\nQuestion: \"Which features do you want to enable?\"\nmultiSelect: true\nOptions:\n - Logging\n - Metrics\n - Alerts\n - Backups\n\nReason: User might want any combination\n```\n\n**Bad multi-select use:**\n```markdown\nQuestion: \"Which database engine?\"\nmultiSelect: true // ❌ Should be single-select\n\nReason: Can only use one database engine\n```\n\n## Advanced Patterns\n\n### Validation Loop\n\n```markdown\n---\ndescription: Interactive with validation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Setup with Validation\n\n## Gather Configuration\n\nUse AskUserQuestion to collect settings.\n\n## Validate Configuration\n\nCheck if configuration is valid:\n- Required dependencies available?\n- Settings compatible with each other?\n- No conflicts detected?\n\nIf validation fails:\n Show validation errors\n\n Use AskUserQuestion to ask:\n\n Question: \"Configuration has issues. What would you like to do?\"\n Header: \"Next step\"\n Options:\n - Fix (Adjust settings to resolve issues)\n - Override (Proceed despite warnings)\n - Cancel (Abort setup)\n\n Based on answer, retry or proceed or exit.\n```\n\n### Build Configuration Incrementally\n\n```markdown\n---\ndescription: Incremental configuration builder\nallowed-tools: AskUserQuestion, Write, Read\n---\n\n# Incremental Setup\n\n## Phase 1: Core Settings\n\nUse AskUserQuestion for core settings.\n\nSave to `.claude/config-partial.yml`\n\n## Phase 2: Review Core Settings\n\nShow user the core settings:\n\nBased on these core settings, you need to configure:\n- [Setting A] (because you chose [X])\n- [Setting B] (because you chose [Y])\n\nReady to continue?\n\n## Phase 3: Detailed Settings\n\nUse AskUserQuestion for settings based on Phase 1 answers.\n\nMerge with core settings.\n\n## Phase 4: Final Review\n\nPresent complete configuration.\n\nUse AskUserQuestion for confirmation:\n\nQuestion: \"Is this configuration correct?\"\nOptions:\n - Yes (Save and apply)\n - No (Start over)\n - Modify (Edit specific settings)\n```\n\n### Dynamic Options Based on Context\n\n```markdown\n---\ndescription: Context-aware questions\nallowed-tools: AskUserQuestion, Bash, Read\n---\n\n# Context-Aware Setup\n\n## Detect Current State\n\nCheck existing configuration:\n- Current language: !`detect-language.sh`\n- Existing frameworks: !`detect-frameworks.sh`\n- Available tools: !`check-tools.sh`\n\n## Ask Context-Appropriate Questions\n\nBased on detected language, ask relevant questions.\n\nIf language is TypeScript:\n\n Use AskUserQuestion:\n\n Question: \"Which TypeScript features should we enable?\"\n Options:\n - Strict Mode (Maximum type safety)\n - Decorators (Experimental decorator support)\n - Path Mapping (Module path aliases)\n\nIf language is Python:\n\n Use AskUserQuestion:\n\n Question: \"Which Python tools should we configure?\"\n Options:\n - Type Hints (mypy for type checking)\n - Black (Code formatting)\n - Pylint (Linting and style)\n\nQuestions adapt to project context.\n```\n\n## Real-World Example: Multi-Agent Swarm Launch\n\n**From multi-agent-swarm plugin:**\n\n```markdown\n---\ndescription: Launch multi-agent swarm\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Launch Multi-Agent Swarm\n\n## Interactive Mode (No Task List Provided)\n\nIf user didn't provide task list file, help create one interactively.\n\n### Question 1: Agent Count\n\nUse AskUserQuestion:\n\nQuestion: \"How many agents should we launch?\"\nHeader: \"Agent count\"\nOptions:\n - 2 agents (Best for simple projects)\n - 3 agents (Good for medium projects)\n - 4 agents (Standard team size)\n - 6 agents (Large projects)\n - 8 agents (Complex multi-component projects)\n\n### Question 2: Task Definition Approach\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to define tasks?\"\nHeader: \"Task setup\"\nOptions:\n - File (I have a task list file ready)\n - Guided (Help me create tasks interactively)\n - Custom (Other approach)\n\nIf \"File\":\n Ask for file path\n Validate file exists and has correct format\n\nIf \"Guided\":\n Enter iterative task creation mode (see below)\n\n### Question 3: Coordination Mode\n\nUse AskUserQuestion:\n\nQuestion: \"How should agents coordinate?\"\nHeader: \"Coordination\"\nOptions:\n - Team Leader (One agent coordinates others)\n - Collaborative (Agents coordinate as peers)\n - Autonomous (Independent work, minimal coordination)\n\n### Iterative Task Creation (If \"Guided\" Selected)\n\nFor each agent (1 to N from Question 1):\n\n**Question A: Agent Name**\nQuestion: \"What should we call agent [number]?\"\nHeader: \"Agent name\"\nOptions:\n - auth-agent\n - api-agent\n - ui-agent\n - db-agent\n (Provide relevant suggestions based on common patterns)\n\n**Question B: Task Type**\nQuestion: \"What task for [agent-name]?\"\nHeader: \"Task type\"\nOptions:\n - Authentication (User auth, JWT, OAuth)\n - API Endpoints (REST/GraphQL APIs)\n - UI Components (Frontend components)\n - Database (Schema, migrations, queries)\n - Testing (Test suites and coverage)\n - Documentation (Docs, README, guides)\n\n**Question C: Dependencies**\nQuestion: \"What does [agent-name] depend on?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - [List of previously defined agents]\n - No dependencies\n\n**Question D: Base Branch**\nQuestion: \"Which base branch for PR?\"\nHeader: \"PR base\"\nOptions:\n - main\n - staging\n - develop\n\nStore all task information for each agent.\n\n### Generate Task List File\n\nAfter collecting all agent task details:\n\n1. Ask for project name\n2. Generate task list in proper format\n3. Save to `.daisy/swarm/tasks.md`\n4. Show user the file path\n5. Proceed with launch using generated task list\n```\n\n## Best Practices\n\n### Question Writing\n\n1. **Be specific**: \"Which database?\" not \"Choose option?\"\n2. **Explain trade-offs**: Describe pros/cons in option descriptions\n3. **Provide context**: Question text should stand alone\n4. **Guide decisions**: Help user make informed choice\n5. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences\n\n### Option Design\n\n1. **Meaningful labels**: Specific, clear names\n2. **Informative descriptions**: Explain what each option does\n3. **Show trade-offs**: Help user understand implications\n4. **Consistent detail**: All options equally explained\n5. **2-4 options**: Not too few, not too many\n\n### Flow Design\n\n1. **Logical order**: Questions flow naturally\n2. **Build on previous**: Later questions use earlier answers\n3. **Minimize questions**: Ask only what's needed\n4. **Group related**: Ask related questions together\n5. **Show progress**: Indicate where in flow\n\n### User Experience\n\n1. **Set expectations**: Tell user what to expect\n2. **Explain why**: Help user understand purpose\n3. **Provide defaults**: Suggest recommended options\n4. **Allow escape**: Let user cancel or restart\n5. **Confirm actions**: Summarize before executing\n\n## Common Patterns\n\n### Pattern: Feature Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which features do you need?\"\nHeader: \"Features\"\nmultiSelect: true\nOptions:\n - Authentication\n - Authorization\n - Rate Limiting\n - Caching\n```\n\n### Pattern: Environment Configuration\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which environment is this?\"\nHeader: \"Environment\"\nOptions:\n - Development (Local development)\n - Staging (Pre-production testing)\n - Production (Live environment)\n```\n\n### Pattern: Priority Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What's the priority for this task?\"\nHeader: \"Priority\"\nOptions:\n - Critical (Must be done immediately)\n - High (Important, do soon)\n - Medium (Standard priority)\n - Low (Nice to have)\n```\n\n### Pattern: Scope Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What scope should we analyze?\"\nHeader: \"Scope\"\nOptions:\n - Current file (Just this file)\n - Current directory (All files in directory)\n - Entire project (Full codebase scan)\n```\n\n## Combining Arguments and Questions\n\n### Use Both Appropriately\n\n**Arguments for known values:**\n```markdown\n---\nargument-hint: [project-name]\nallowed-tools: AskUserQuestion, Write\n---\n\nSetup for project: $1\n\nNow gather additional configuration...\n\nUse AskUserQuestion for options that require explanation.\n```\n\n**Questions for complex choices:**\n```markdown\nProject name from argument: $1\n\nNow use AskUserQuestion to choose:\n- Architecture pattern\n- Technology stack\n- Deployment strategy\n\nThese require explanation, so questions work better than arguments.\n```\n\n## Troubleshooting\n\n**Questions not appearing:**\n- Verify AskUserQuestion in allowed-tools\n- Check question format is correct\n- Ensure options array has 2-4 items\n\n**User can't make selection:**\n- Check option labels are clear\n- Verify descriptions are helpful\n- Consider if too many options\n- Ensure multiSelect setting is correct\n\n**Flow feels confusing:**\n- Reduce number of questions\n- Group related questions\n- Add explanation between stages\n- Show progress through workflow\n\nWith AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.\n","plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md":"# Marketplace Considerations for Commands\n\nGuidelines for creating commands designed for distribution and marketplace success.\n\n## Overview\n\nCommands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.\n\n## Design for Distribution\n\n### Universal Compatibility\n\n**Cross-platform considerations:**\n\n```markdown\n---\ndescription: Cross-platform command\nallowed-tools: Bash(*)\n---\n\n# Platform-Aware Command\n\nDetecting platform...\n\ncase \"$(uname)\" in\n Darwin*) PLATFORM=\"macOS\" ;;\n Linux*) PLATFORM=\"Linux\" ;;\n MINGW*|MSYS*|CYGWIN*) PLATFORM=\"Windows\" ;;\n *) PLATFORM=\"Unknown\" ;;\nesac\n\nPlatform: $PLATFORM\n\n\nif [ \"$PLATFORM\" = \"Windows\" ]; then\n # Windows-specific handling\n PATH_SEP=\"\\\\\"\n NULL_DEVICE=\"NUL\"\nelse\n # Unix-like handling\n PATH_SEP=\"/\"\n NULL_DEVICE=\"/dev/null\"\nfi\n\n[Platform-appropriate implementation...]\n```\n\n**Avoid platform-specific commands:**\n\n```markdown\n\n!`pbcopy < file.txt`\n\n\nif command -v pbcopy > /dev/null; then\n pbcopy < file.txt\nelif command -v xclip > /dev/null; then\n xclip -selection clipboard < file.txt\nelif command -v clip.exe > /dev/null; then\n cat file.txt | clip.exe\nelse\n echo \"Clipboard not available on this platform\"\nfi\n```\n\n### Minimal Dependencies\n\n**Check for required tools:**\n\n```markdown\n---\ndescription: Dependency-aware command\nallowed-tools: Bash(*)\n---\n\n# Check Dependencies\n\nRequired tools:\n- git\n- jq\n- node\n\nChecking availability...\n\nMISSING_DEPS=\"\"\n\nfor tool in git jq node; do\n if ! command -v $tool > /dev/null; then\n MISSING_DEPS=\"$MISSING_DEPS $tool\"\n fi\ndone\n\nif [ -n \"$MISSING_DEPS\" ]; then\n ❌ ERROR: Missing required dependencies:$MISSING_DEPS\n\n INSTALLATION:\n - git: https://git-scm.com/downloads\n - jq: https://stedolan.github.io/jq/download/\n - node: https://nodejs.org/\n\n Install missing tools and try again.\n\n Exit.\nfi\n\n✓ All dependencies available\n\n[Continue with command...]\n```\n\n**Document optional dependencies:**\n\n```markdown\n\n```\n\n### Graceful Degradation\n\n**Handle missing features:**\n\n```markdown\n---\ndescription: Feature-aware command\n---\n\n# Feature Detection\n\nDetecting available features...\n\nFEATURES=\"\"\n\nif command -v gh > /dev/null; then\n FEATURES=\"$FEATURES github\"\nfi\n\nif command -v docker > /dev/null; then\n FEATURES=\"$FEATURES docker\"\nfi\n\nAvailable features: $FEATURES\n\nif echo \"$FEATURES\" | grep -q \"github\"; then\n # Full functionality with GitHub integration\n echo \"✓ GitHub integration available\"\nelse\n # Reduced functionality without GitHub\n echo \"⚠ Limited functionality: GitHub CLI not installed\"\n echo \" Install 'gh' for full features\"\nfi\n\n[Adapt behavior based on available features...]\n```\n\n## User Experience for Unknown Users\n\n### Clear Onboarding\n\n**First-run experience:**\n\n```markdown\n---\ndescription: Command with onboarding\nallowed-tools: Read, Write\n---\n\n# First Run Check\n\nif [ ! -f \".claude/command-initialized\" ]; then\n **Welcome to Command Name!**\n\n This appears to be your first time using this command.\n\n WHAT THIS COMMAND DOES:\n [Brief explanation of purpose and benefits]\n\n QUICK START:\n 1. Basic usage: /command [arg]\n 2. For help: /command help\n 3. Examples: /command examples\n\n SETUP:\n No additional setup required. You're ready to go!\n\n ✓ Initialization complete\n\n [Create initialization marker]\n\n Ready to proceed with your request...\nfi\n\n[Normal command execution...]\n```\n\n**Progressive feature discovery:**\n\n```markdown\n---\ndescription: Command with tips\n---\n\n# Command Execution\n\n[Main functionality...]\n\n---\n\n💡 TIP: Did you know?\n\nYou can speed up this command with the --fast flag:\n /command --fast [args]\n\nFor more tips: /command tips\n```\n\n### Comprehensive Error Handling\n\n**Anticipate user mistakes:**\n\n```markdown\n---\ndescription: Forgiving command\n---\n\n# User Input Handling\n\nArgument: \"$1\"\n\n\nif [ \"$1\" = \"hlep\" ] || [ \"$1\" = \"hepl\" ]; then\n Did you mean: help?\n\n Showing help instead...\n [Display help]\n\n Exit.\nfi\n\n\nif [ \"$1\" != \"valid-option1\" ] && [ \"$1\" != \"valid-option2\" ]; then\n ❌ Unknown option: $1\n\n Did you mean:\n - valid-option1 (most similar)\n - valid-option2\n\n For all options: /command help\n\n Exit.\nfi\n\n[Command continues...]\n```\n\n**Helpful diagnostics:**\n\n```markdown\n---\ndescription: Diagnostic command\n---\n\n# Operation Failed\n\nThe operation could not complete.\n\n**Diagnostic Information:**\n\nEnvironment:\n- Platform: $(uname)\n- Shell: $SHELL\n- Working directory: $(pwd)\n- Command: /command $@\n\nChecking common issues:\n- Git repository: $(git rev-parse --git-dir 2>&1)\n- Write permissions: $(test -w . && echo \"OK\" || echo \"DENIED\")\n- Required files: $(test -f config.yml && echo \"Found\" || echo \"Missing\")\n\nThis information helps debug the issue.\n\nFor support, include the above diagnostics.\n```\n\n## Distribution Best Practices\n\n### Namespace Awareness\n\n**Avoid name collisions:**\n\n```markdown\n---\ndescription: Namespaced command\n---\n\n\n\n# Plugin Name Command\n\n[Implementation...]\n```\n\n**Document naming rationale:**\n\n```markdown\n\n```\n\n### Configurability\n\n**User preferences:**\n\n```markdown\n---\ndescription: Configurable command\nallowed-tools: Read\n---\n\n# Load User Configuration\n\nDefault configuration:\n- verbose: false\n- color: true\n- max_results: 10\n\nChecking for user config: .claude/plugin-name.local.md\n\nif [ -f \".claude/plugin-name.local.md\" ]; then\n # Parse YAML frontmatter for settings\n VERBOSE=$(grep \"^verbose:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n COLOR=$(grep \"^color:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n MAX_RESULTS=$(grep \"^max_results:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n\n echo \"✓ Using user configuration\"\nelse\n echo \"Using default configuration\"\n echo \"Create .claude/plugin-name.local.md to customize\"\nfi\n\n[Use configuration in command...]\n```\n\n**Sensible defaults:**\n\n```markdown\n---\ndescription: Command with smart defaults\n---\n\n# Smart Defaults\n\nConfiguration:\n- Format: ${FORMAT:-json} # Defaults to json\n- Output: ${OUTPUT:-stdout} # Defaults to stdout\n- Verbose: ${VERBOSE:-false} # Defaults to false\n\nThese defaults work for 80% of use cases.\n\nOverride with arguments:\n /command --format yaml --output file.txt --verbose\n\nOr set in .claude/plugin-name.local.md:\n\\`\\`\\`yaml\n---\nformat: yaml\noutput: custom.txt\nverbose: true\n---\n\\`\\`\\`\n```\n\n### Version Compatibility\n\n**Version checking:**\n\n```markdown\n---\ndescription: Version-aware command\n---\n\n\n\n# Version Check\n\nCommand version: 2.1.0\nPlugin version: [detect from plugin.json]\n\nif [ \"$PLUGIN_VERSION\" < \"2.0.0\" ]; then\n ❌ ERROR: Incompatible plugin version\n\n This command requires plugin version >= 2.0.0\n Current version: $PLUGIN_VERSION\n\n Update plugin:\n /plugin update plugin-name\n\n Exit.\nfi\n\n✓ Version compatible\n\n[Command continues...]\n```\n\n**Deprecation warnings:**\n\n```markdown\n---\ndescription: Command with deprecation warnings\n---\n\n# Deprecation Check\n\nif [ \"$1\" = \"--old-flag\" ]; then\n ⚠️ DEPRECATION WARNING\n\n The --old-flag option is deprecated as of v2.0.0\n It will be removed in v3.0.0 (est. June 2025)\n\n Use instead: --new-flag\n\n Example:\n Old: /command --old-flag value\n New: /command --new-flag value\n\n See migration guide: /command migrate\n\n Continuing with deprecated behavior for now...\nfi\n\n[Handle both old and new flags during deprecation period...]\n```\n\n## Marketplace Presentation\n\n### Command Discovery\n\n**Descriptive naming:**\n\n```markdown\n---\ndescription: Review pull request with security and quality checks\n---\n\n\n```\n\n```markdown\n---\ndescription: Do the thing\n---\n\n\n```\n\n**Searchable keywords:**\n\n```markdown\n\n```\n\n### Showcase Examples\n\n**Compelling demonstrations:**\n\n```markdown\n---\ndescription: Advanced code analysis command\n---\n\n# Code Analysis Command\n\nThis command performs deep code analysis with actionable insights.\n\n## Demo: Quick Security Audit\n\nTry it now:\n\\`\\`\\`\n/analyze-code src/ --security\n\\`\\`\\`\n\n**What you'll get:**\n- Security vulnerability detection\n- Code quality metrics\n- Performance bottleneck identification\n- Actionable recommendations\n\n**Sample output:**\n\\`\\`\\`\nSecurity Analysis Results\n=========================\n\n🔴 Critical (2):\n - SQL injection risk in users.js:45\n - XSS vulnerability in display.js:23\n\n🟡 Warnings (5):\n - Unvalidated input in api.js:67\n ...\n\nRecommendations:\n1. Fix critical issues immediately\n2. Review warnings before next release\n3. Run /analyze-code --fix for auto-fixes\n\\`\\`\\`\n\n---\n\nReady to analyze your code...\n\n[Command implementation...]\n```\n\n### User Reviews and Feedback\n\n**Feedback mechanism:**\n\n```markdown\n---\ndescription: Command with feedback\n---\n\n# Command Complete\n\n[Command results...]\n\n---\n\n**How was your experience?**\n\nThis helps improve the command for everyone.\n\nRate this command:\n- 👍 Helpful\n- 👎 Not helpful\n- 🐛 Found a bug\n- 💡 Have a suggestion\n\nReply with an emoji or:\n- /command feedback\n\nYour feedback matters!\n```\n\n**Usage analytics preparation:**\n\n```markdown\n\n```\n\n## Quality Standards\n\n### Professional Polish\n\n**Consistent branding:**\n\n```markdown\n---\ndescription: Branded command\n---\n\n# ✨ Command Name\n\nPart of the [Plugin Name] suite\n\n[Command functionality...]\n\n---\n\n**Need Help?**\n- Documentation: https://docs.example.com\n- Support: support@example.com\n- Community: https://community.example.com\n\nPowered by Plugin Name v2.1.0\n```\n\n**Attention to detail:**\n\n```markdown\n\n\n✓ Use proper emoji/symbols consistently\n✓ Align output columns neatly\n✓ Format numbers with thousands separators\n✓ Use color/formatting appropriately\n✓ Provide progress indicators\n✓ Show estimated time remaining\n✓ Confirm successful operations\n```\n\n### Reliability\n\n**Idempotency:**\n\n```markdown\n---\ndescription: Idempotent command\n---\n\n# Safe Repeated Execution\n\nChecking if operation already completed...\n\nif [ -f \".claude/operation-completed.flag\" ]; then\n ℹ️ Operation already completed\n\n Completed at: $(cat .claude/operation-completed.flag)\n\n To re-run:\n 1. Remove flag: rm .claude/operation-completed.flag\n 2. Run command again\n\n Otherwise, no action needed.\n\n Exit.\nfi\n\nPerforming operation...\n\n[Safe, repeatable operation...]\n\nMarking complete...\necho \"$(date)\" > .claude/operation-completed.flag\n```\n\n**Atomic operations:**\n\n```markdown\n---\ndescription: Atomic command\n---\n\n# Atomic Operation\n\nThis operation is atomic - either fully succeeds or fully fails.\n\nCreating temporary workspace...\nTEMP_DIR=$(mktemp -d)\n\nPerforming changes in isolated environment...\n[Make changes in $TEMP_DIR]\n\nif [ $? -eq 0 ]; then\n ✓ Changes validated\n\n Applying changes atomically...\n mv $TEMP_DIR/* ./target/\n\n ✓ Operation complete\nelse\n ❌ Changes failed validation\n\n Rolling back...\n rm -rf $TEMP_DIR\n\n No changes applied. Safe to retry.\nfi\n```\n\n## Testing for Distribution\n\n### Pre-Release Checklist\n\n```markdown\n\n```\n\n### Beta Testing\n\n**Beta release approach:**\n\n```markdown\n---\ndescription: Beta command (v0.9.0)\n---\n\n# 🧪 Beta Command\n\n**This is a beta release**\n\nFeatures may change based on feedback.\n\nBETA STATUS:\n- Version: 0.9.0\n- Stability: Experimental\n- Support: Limited\n- Feedback: Encouraged\n\nKnown limitations:\n- Performance not optimized\n- Some edge cases not handled\n- Documentation incomplete\n\nHelp improve this command:\n- Report issues: /command report-issue\n- Suggest features: /command suggest\n- Join beta testers: /command join-beta\n\n---\n\n[Command implementation...]\n\n---\n\n**Thank you for beta testing!**\n\nYour feedback helps make this command better.\n```\n\n## Maintenance and Updates\n\n### Update Strategy\n\n**Versioned commands:**\n\n```markdown\n\n```\n\n**Update notifications:**\n\n```markdown\n---\ndescription: Update-aware command\n---\n\n# Check for Updates\n\nCurrent version: 2.1.0\nLatest version: [check if available]\n\nif [ \"$CURRENT_VERSION\" != \"$LATEST_VERSION\" ]; then\n 📢 UPDATE AVAILABLE\n\n New version: $LATEST_VERSION\n Current: $CURRENT_VERSION\n\n What's new:\n - Feature improvements\n - Bug fixes\n - Performance enhancements\n\n Update with:\n /plugin update plugin-name\n\n Release notes: https://releases.example.com/v$LATEST_VERSION\nfi\n\n[Command continues...]\n```\n\n## Best Practices Summary\n\n### Distribution Design\n\n1. **Universal**: Works across platforms and environments\n2. **Self-contained**: Minimal dependencies, clear requirements\n3. **Graceful**: Degrades gracefully when features unavailable\n4. **Forgiving**: Anticipates and handles user mistakes\n5. **Helpful**: Clear errors, good defaults, excellent docs\n\n### Marketplace Success\n\n1. **Discoverable**: Clear name, good description, searchable keywords\n2. **Professional**: Polished presentation, consistent branding\n3. **Reliable**: Tested thoroughly, handles edge cases\n4. **Maintainable**: Versioned, updated regularly, supported\n5. **User-focused**: Great UX, responsive to feedback\n\n### Quality Standards\n\n1. **Complete**: Fully documented, all features working\n2. **Tested**: Works in real environments, edge cases handled\n3. **Secure**: No vulnerabilities, safe operations\n4. **Performant**: Reasonable speed, resource-efficient\n5. **Ethical**: Privacy-respecting, user consent\n\nWith these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.\n","plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md":"# Plugin-Specific Command Features Reference\n\nThis reference covers features and patterns specific to commands bundled in Claude Code plugins.\n\n## Table of Contents\n\n- [Plugin Command Discovery](#plugin-command-discovery)\n- [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable)\n- [Plugin Command Patterns](#plugin-command-patterns)\n- [Integration with Plugin Components](#integration-with-plugin-components)\n- [Validation Patterns](#validation-patterns)\n\n## Plugin Command Discovery\n\n### Auto-Discovery\n\nClaude Code automatically discovers commands in plugins using the following locations:\n\n```\nplugin-name/\n├── commands/ # Auto-discovered commands\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ └── bar.md # /bar (plugin:plugin-name)\n└── plugin.json # Plugin manifest\n```\n\n**Key points:**\n- Commands are discovered at plugin load time\n- No manual registration required\n- Commands appear in `/help` with \"(plugin:plugin-name)\" label\n- Subdirectories create namespaces\n\n### Namespaced Plugin Commands\n\nOrganize commands in subdirectories for logical grouping:\n\n```\nplugin-name/\n└── commands/\n ├── review/\n │ ├── security.md # /security (plugin:plugin-name:review)\n │ └── style.md # /style (plugin:plugin-name:review)\n └── deploy/\n ├── staging.md # /staging (plugin:plugin-name:deploy)\n └── prod.md # /prod (plugin:plugin-name:deploy)\n```\n\n**Namespace behavior:**\n- Subdirectory name becomes namespace\n- Shown as \"(plugin:plugin-name:namespace)\" in `/help`\n- Helps organize related commands\n- Use when plugin has 5+ commands\n\n### Command Naming Conventions\n\n**Plugin command names should:**\n1. Be descriptive and action-oriented\n2. Avoid conflicts with common command names\n3. Use hyphens for multi-word names\n4. Consider prefixing with plugin name for uniqueness\n\n**Examples:**\n```\nGood:\n- /mylyn-sync (plugin-specific prefix)\n- /analyze-performance (descriptive action)\n- /docker-compose-up (clear purpose)\n\nAvoid:\n- /test (conflicts with common name)\n- /run (too generic)\n- /do-stuff (not descriptive)\n```\n\n## CLAUDE_PLUGIN_ROOT Environment Variable\n\n### Purpose\n\n`${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory.\n\n**Why it matters:**\n- Enables portable paths within plugin\n- Allows referencing plugin files and scripts\n- Works across different installations\n- Essential for multi-file plugin operations\n\n### Basic Usage\n\nReference files within your plugin:\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*), Read\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n\nRead template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md\n```\n\n**Expands to:**\n```\nRun analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js`\n\nRead template: @/path/to/plugins/plugin-name/templates/report.md\n```\n\n### Common Patterns\n\n#### 1. Executing Plugin Scripts\n\n```markdown\n---\ndescription: Run custom linter from plugin\nallowed-tools: Bash(node:*)\n---\n\nLint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`\n\nReview the linting output and suggest fixes.\n```\n\n#### 2. Loading Configuration Files\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nallowed-tools: Read, Bash(*)\n---\n\nConfiguration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json\n\nDeploy application using the configuration above for $1 environment.\n```\n\n#### 3. Accessing Plugin Resources\n\n```markdown\n---\ndescription: Generate report from template\n---\n\nUse this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md\n\nGenerate a report for @$1 following the template format.\n```\n\n#### 4. Multi-Step Plugin Workflows\n\n```markdown\n---\ndescription: Complete plugin workflow\nallowed-tools: Bash(*), Read\n---\n\nStep 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`\nStep 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\nStep 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`\n\nReview results and report status.\n```\n\n### Best Practices\n\n1. **Always use for plugin-internal paths:**\n ```markdown\n # Good\n @${CLAUDE_PLUGIN_ROOT}/templates/foo.md\n\n # Bad\n @./templates/foo.md # Relative to current directory, not plugin\n ```\n\n2. **Validate file existence:**\n ```markdown\n ---\n description: Use plugin config if exists\n allowed-tools: Bash(test:*), Read\n ---\n\n !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"exists\" || echo \"missing\"`\n\n If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json\n Otherwise, use defaults...\n ```\n\n3. **Document plugin file structure:**\n ```markdown\n \n ```\n\n4. **Combine with arguments:**\n ```markdown\n Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2`\n ```\n\n### Troubleshooting\n\n**Variable not expanding:**\n- Ensure command is loaded from plugin\n- Check bash execution is allowed\n- Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}`\n\n**File not found errors:**\n- Verify file exists in plugin directory\n- Check file path is correct relative to plugin root\n- Ensure file permissions allow reading/execution\n\n**Path with spaces:**\n- Bash commands automatically handle spaces\n- File references work with spaces in paths\n- No special quoting needed\n\n## Plugin Command Patterns\n\n### Pattern 1: Configuration-Based Commands\n\nCommands that load plugin-specific configuration:\n\n```markdown\n---\ndescription: Deploy using plugin settings\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json\n\nDeploy to $1 environment using:\n1. Configuration settings above\n2. Current git branch: !`git branch --show-current`\n3. Application version: !`cat package.json | grep version`\n\nExecute deployment and monitor progress.\n```\n\n**When to use:** Commands that need consistent settings across invocations\n\n### Pattern 2: Template-Based Generation\n\nCommands that use plugin templates:\n\n```markdown\n---\ndescription: Generate documentation from template\nargument-hint: [component-name]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md\n\nGenerate documentation for $1 component following the template structure.\nInclude:\n- Component purpose and usage\n- API reference\n- Examples\n- Testing guidelines\n```\n\n**When to use:** Standardized output generation\n\n### Pattern 3: Multi-Script Workflow\n\nCommands that orchestrate multiple plugin scripts:\n\n```markdown\n---\ndescription: Complete build and test workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nValidate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\n\nReview all outputs and report:\n1. Build status\n2. Validation results\n3. Test results\n4. Recommended next steps\n```\n\n**When to use:** Complex plugin workflows with multiple steps\n\n### Pattern 4: Environment-Aware Commands\n\nCommands that adapt to environment:\n\n```markdown\n---\ndescription: Deploy based on environment\nargument-hint: [dev|staging|prod]\n---\n\nEnvironment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\nEnvironment check: !`echo \"Deploying to: $1\"`\n\nDeploy application using $1 environment configuration.\nVerify deployment and run smoke tests.\n```\n\n**When to use:** Commands that behave differently per environment\n\n### Pattern 5: Plugin Data Management\n\nCommands that manage plugin-specific data:\n\n```markdown\n---\ndescription: Save analysis results to plugin cache\nallowed-tools: Bash(*), Read, Write\n---\n\nCache directory: ${CLAUDE_PLUGIN_ROOT}/cache/\n\nAnalyze @$1 and save results to cache:\n!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`\n\nStore analysis for future reference and comparison.\n```\n\n**When to use:** Commands that need persistent data storage\n\n## Integration with Plugin Components\n\n### Invoking Plugin Agents\n\nCommands can trigger plugin agents using the Task tool:\n\n```markdown\n---\ndescription: Deep analysis using plugin agent\nargument-hint: [file-path]\n---\n\nInitiate deep code analysis of @$1 using the code-analyzer agent.\n\nThe agent will:\n1. Analyze code structure\n2. Identify patterns\n3. Suggest improvements\n4. Generate detailed report\n\nNote: This uses the Task tool to launch the plugin's code-analyzer agent.\n```\n\n**Key points:**\n- Agent must be defined in plugin's `agents/` directory\n- Claude will automatically use Task tool to launch agent\n- Agent has access to same plugin resources\n\n### Invoking Plugin Skills\n\nCommands can reference plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: API documentation with best practices\nargument-hint: [api-file]\n---\n\nDocument the API in @$1 following our API documentation standards.\n\nUse the api-docs-standards skill to ensure documentation includes:\n- Endpoint descriptions\n- Parameter specifications\n- Response formats\n- Error codes\n- Usage examples\n\nNote: This leverages the plugin's api-docs-standards skill for consistency.\n```\n\n**Key points:**\n- Skill must be defined in plugin's `skills/` directory\n- Mention skill by name to hint Claude should invoke it\n- Skills provide specialized domain knowledge\n\n### Coordinating with Plugin Hooks\n\nCommands can be designed to work with plugin hooks:\n\n```markdown\n---\ndescription: Commit with pre-commit validation\nallowed-tools: Bash(git:*)\n---\n\nStage changes: !\\`git add $1\\`\n\nCommit changes: !\\`git commit -m \"$2\"\\`\n\nNote: This commit will trigger the plugin's pre-commit hook for validation.\nReview hook output for any issues.\n```\n\n**Key points:**\n- Hooks execute automatically on events\n- Commands can prepare state for hooks\n- Document hook interaction in command\n\n### Multi-Component Plugin Commands\n\nCommands that coordinate multiple plugin components:\n\n```markdown\n---\ndescription: Comprehensive code review workflow\nargument-hint: [file-path]\n---\n\nFile to review: @$1\n\nExecute comprehensive review:\n\n1. **Static Analysis** (via plugin scripts)\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\n2. **Deep Review** (via plugin agent)\n Launch the code-reviewer agent for detailed analysis.\n\n3. **Best Practices** (via plugin skill)\n Use the code-standards skill to ensure compliance.\n\n4. **Documentation** (via plugin template)\n Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nGenerate final report combining all outputs.\n```\n\n**When to use:** Complex workflows leveraging multiple plugin capabilities\n\n## Validation Patterns\n\n### Input Validation\n\nCommands should validate inputs before processing:\n\n```markdown\n---\ndescription: Deploy to environment with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\n$IF($1 in [dev, staging, prod],\n Deploy to $1 environment using validated configuration,\n ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod\n)\n```\n\n**Validation approaches:**\n1. Bash validation using grep/test\n2. Inline validation in prompt\n3. Script-based validation\n\n### File Existence Checks\n\nVerify required files exist:\n\n```markdown\n---\ndescription: Process configuration file\nargument-hint: [config-file]\n---\n\nCheck file: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nProcess configuration if file exists: @$1\n\nIf file doesn't exist, explain:\n- Expected location\n- Required format\n- How to create it\n```\n\n### Required Arguments\n\nValidate required arguments provided:\n\n```markdown\n---\ndescription: Create deployment with version\nargument-hint: [environment] [version]\n---\n\nValidate inputs: !`test -n \"$1\" -a -n \"$2\" && echo \"OK\" || echo \"MISSING\"`\n\n$IF($1 AND $2,\n Deploy version $2 to $1 environment,\n ERROR: Both environment and version required. Usage: /deploy [env] [version]\n)\n```\n\n### Plugin Resource Validation\n\nVerify plugin resources available:\n\n```markdown\n---\ndescription: Run analysis with plugin tools\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n- Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo \"✓\" || echo \"✗\"`\n- Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, proceed with analysis.\nOtherwise, report missing components and installation steps.\n```\n\n### Output Validation\n\nValidate command execution results:\n\n```markdown\n---\ndescription: Build and validate output\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\n\nValidate output:\n- Exit code: !`echo $?`\n- Output exists: !`test -d dist && echo \"✓\" || echo \"✗\"`\n- File count: !`find dist -type f | wc -l`\n\nReport build status and any validation failures.\n```\n\n### Graceful Error Handling\n\nHandle errors gracefully with helpful messages:\n\n```markdown\n---\ndescription: Process file with error handling\nargument-hint: [file-path]\n---\n\nTry processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo \"ERROR: $?\"`\n\nIf processing succeeded:\n- Report results\n- Suggest next steps\n\nIf processing failed:\n- Explain likely causes\n- Provide troubleshooting steps\n- Suggest alternative approaches\n```\n\n## Best Practices Summary\n\n### Plugin Commands Should:\n\n1. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths**\n - Scripts, templates, configuration, resources\n\n2. **Validate inputs early**\n - Check required arguments\n - Verify file existence\n - Validate argument formats\n\n3. **Document plugin structure**\n - Explain required files\n - Document script purposes\n - Clarify dependencies\n\n4. **Integrate with plugin components**\n - Reference agents for complex tasks\n - Use skills for specialized knowledge\n - Coordinate with hooks when relevant\n\n5. **Provide helpful error messages**\n - Explain what went wrong\n - Suggest how to fix\n - Offer alternatives\n\n6. **Handle edge cases**\n - Missing files\n - Invalid arguments\n - Failed script execution\n - Missing dependencies\n\n7. **Keep commands focused**\n - One clear purpose per command\n - Delegate complex logic to scripts\n - Use agents for multi-step workflows\n\n8. **Test across installations**\n - Verify paths work everywhere\n - Test with different arguments\n - Validate error cases\n\n---\n\nFor general command development, see main SKILL.md.\nFor command examples, see examples/ directory.\n","plugins/plugin-dev/skills/command-development/references/testing-strategies.md":"# Command Testing Strategies\n\nComprehensive strategies for testing slash commands before deployment and distribution.\n\n## Overview\n\nTesting commands ensures they work correctly, handle edge cases, and provide good user experience. A systematic testing approach catches issues early and builds confidence in command reliability.\n\n## Testing Levels\n\n### Level 1: Syntax and Structure Validation\n\n**What to test:**\n- YAML frontmatter syntax\n- Markdown format\n- File location and naming\n\n**How to test:**\n\n```bash\n# Validate YAML frontmatter\nhead -n 20 .claude/commands/my-command.md | grep -A 10 \"^---\"\n\n# Check for closing frontmatter marker\nhead -n 20 .claude/commands/my-command.md | grep -c \"^---\" # Should be 2\n\n# Verify file has .md extension\nls .claude/commands/*.md\n\n# Check file is in correct location\ntest -f .claude/commands/my-command.md && echo \"Found\" || echo \"Missing\"\n```\n\n**Automated validation script:**\n\n```bash\n#!/bin/bash\n# validate-command.sh\n\nCOMMAND_FILE=\"$1\"\n\nif [ ! -f \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File not found: $COMMAND_FILE\"\n exit 1\nfi\n\n# Check .md extension\nif [[ ! \"$COMMAND_FILE\" =~ \\.md$ ]]; then\n echo \"ERROR: File must have .md extension\"\n exit 1\nfi\n\n# Validate YAML frontmatter if present\nif head -n 1 \"$COMMAND_FILE\" | grep -q \"^---\"; then\n # Count frontmatter markers\n MARKERS=$(head -n 50 \"$COMMAND_FILE\" | grep -c \"^---\")\n if [ \"$MARKERS\" -ne 2 ]; then\n echo \"ERROR: Invalid YAML frontmatter (need exactly 2 '---' markers)\"\n exit 1\n fi\n echo \"✓ YAML frontmatter syntax valid\"\nfi\n\n# Check for empty file\nif [ ! -s \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File is empty\"\n exit 1\nfi\n\necho \"✓ Command file structure valid\"\n```\n\n### Level 2: Frontmatter Field Validation\n\n**What to test:**\n- Field types correct\n- Values in valid ranges\n- Required fields present (if any)\n\n**Validation script:**\n\n```bash\n#!/bin/bash\n# validate-frontmatter.sh\n\nCOMMAND_FILE=\"$1\"\n\n# Extract YAML frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/p' \"$COMMAND_FILE\" | sed '1d;$d')\n\nif [ -z \"$FRONTMATTER\" ]; then\n echo \"No frontmatter to validate\"\n exit 0\nfi\n\n# Check 'model' field if present\nif echo \"$FRONTMATTER\" | grep -q \"^model:\"; then\n MODEL=$(echo \"$FRONTMATTER\" | grep \"^model:\" | cut -d: -f2 | tr -d ' ')\n if ! echo \"sonnet opus haiku\" | grep -qw \"$MODEL\"; then\n echo \"ERROR: Invalid model '$MODEL' (must be sonnet, opus, or haiku)\"\n exit 1\n fi\n echo \"✓ Model field valid: $MODEL\"\nfi\n\n# Check 'allowed-tools' field format\nif echo \"$FRONTMATTER\" | grep -q \"^allowed-tools:\"; then\n echo \"✓ allowed-tools field present\"\n # Could add more sophisticated validation here\nfi\n\n# Check 'description' length\nif echo \"$FRONTMATTER\" | grep -q \"^description:\"; then\n DESC=$(echo \"$FRONTMATTER\" | grep \"^description:\" | cut -d: -f2-)\n LENGTH=${#DESC}\n if [ \"$LENGTH\" -gt 80 ]; then\n echo \"WARNING: Description length $LENGTH (recommend < 60 chars)\"\n else\n echo \"✓ Description length acceptable: $LENGTH chars\"\n fi\nfi\n\necho \"✓ Frontmatter fields valid\"\n```\n\n### Level 3: Manual Command Invocation\n\n**What to test:**\n- Command appears in `/help`\n- Command executes without errors\n- Output is as expected\n\n**Test procedure:**\n\n```bash\n# 1. Start Claude Code\nclaude --debug\n\n# 2. Check command appears in help\n> /help\n# Look for your command in the list\n\n# 3. Invoke command without arguments\n> /my-command\n# Check for reasonable error or behavior\n\n# 4. Invoke with valid arguments\n> /my-command arg1 arg2\n# Verify expected behavior\n\n# 5. Check debug logs\ntail -f ~/.claude/debug-logs/latest\n# Look for errors or warnings\n```\n\n### Level 4: Argument Testing\n\n**What to test:**\n- Positional arguments work ($1, $2, etc.)\n- $ARGUMENTS captures all arguments\n- Missing arguments handled gracefully\n- Invalid arguments detected\n\n**Test matrix:**\n\n| Test Case | Command | Expected Result |\n|-----------|---------|-----------------|\n| No args | `/cmd` | Graceful handling or useful message |\n| One arg | `/cmd arg1` | $1 substituted correctly |\n| Two args | `/cmd arg1 arg2` | $1 and $2 substituted |\n| Extra args | `/cmd a b c d` | All captured or extras ignored appropriately |\n| Special chars | `/cmd \"arg with spaces\"` | Quotes handled correctly |\n| Empty arg | `/cmd \"\"` | Empty string handled |\n\n**Test script:**\n\n```bash\n#!/bin/bash\n# test-command-arguments.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing argument handling for /$COMMAND\"\necho\n\necho \"Test 1: No arguments\"\necho \" Command: /$COMMAND\"\necho \" Expected: [describe expected behavior]\"\necho \" Manual test required\"\necho\n\necho \"Test 2: Single argument\"\necho \" Command: /$COMMAND test-value\"\necho \" Expected: 'test-value' appears in output\"\necho \" Manual test required\"\necho\n\necho \"Test 3: Multiple arguments\"\necho \" Command: /$COMMAND arg1 arg2 arg3\"\necho \" Expected: All arguments used appropriately\"\necho \" Manual test required\"\necho\n\necho \"Test 4: Special characters\"\necho \" Command: /$COMMAND \\\"value with spaces\\\"\"\necho \" Expected: Entire phrase captured\"\necho \" Manual test required\"\n```\n\n### Level 5: File Reference Testing\n\n**What to test:**\n- @ syntax loads file contents\n- Non-existent files handled\n- Large files handled appropriately\n- Multiple file references work\n\n**Test procedure:**\n\n```bash\n# Create test files\necho \"Test content\" > /tmp/test-file.txt\necho \"Second file\" > /tmp/test-file-2.txt\n\n# Test single file reference\n> /my-command /tmp/test-file.txt\n# Verify file content is read\n\n# Test non-existent file\n> /my-command /tmp/nonexistent.txt\n# Verify graceful error handling\n\n# Test multiple files\n> /my-command /tmp/test-file.txt /tmp/test-file-2.txt\n# Verify both files processed\n\n# Test large file\ndd if=/dev/zero of=/tmp/large-file.bin bs=1M count=100\n> /my-command /tmp/large-file.bin\n# Verify reasonable behavior (may truncate or warn)\n\n# Cleanup\nrm /tmp/test-file*.txt /tmp/large-file.bin\n```\n\n### Level 6: Bash Execution Testing\n\n**What to test:**\n- !` commands execute correctly\n- Command output included in prompt\n- Command failures handled\n- Security: only allowed commands run\n\n**Test procedure:**\n\n```bash\n# Create test command with bash execution\ncat > .claude/commands/test-bash.md << 'EOF'\n---\ndescription: Test bash execution\nallowed-tools: Bash(echo:*), Bash(date:*)\n---\n\nCurrent date: !`date`\nTest output: !`echo \"Hello from bash\"`\n\nAnalysis of output above...\nEOF\n\n# Test in Claude Code\n> /test-bash\n# Verify:\n# 1. Date appears correctly\n# 2. Echo output appears\n# 3. No errors in debug logs\n\n# Test with disallowed command (should fail or be blocked)\ncat > .claude/commands/test-forbidden.md << 'EOF'\n---\ndescription: Test forbidden command\nallowed-tools: Bash(echo:*)\n---\n\nTrying forbidden: !`ls -la /`\nEOF\n\n> /test-forbidden\n# Verify: Permission denied or appropriate error\n```\n\n### Level 7: Integration Testing\n\n**What to test:**\n- Commands work with other plugin components\n- Commands interact correctly with each other\n- State management works across invocations\n- Workflow commands execute in sequence\n\n**Test scenarios:**\n\n**Scenario 1: Command + Hook Integration**\n\n```bash\n# Setup: Command that triggers a hook\n# Test: Invoke command, verify hook executes\n\n# Command: .claude/commands/risky-operation.md\n# Hook: PreToolUse that validates the operation\n\n> /risky-operation\n# Verify: Hook executes and validates before command completes\n```\n\n**Scenario 2: Command Sequence**\n\n```bash\n# Setup: Multi-command workflow\n> /workflow-init\n# Verify: State file created\n\n> /workflow-step2\n# Verify: State file read, step 2 executes\n\n> /workflow-complete\n# Verify: State file cleaned up\n```\n\n**Scenario 3: Command + MCP Integration**\n\n```bash\n# Setup: Command uses MCP tools\n# Test: Verify MCP server accessible\n\n> /mcp-command\n# Verify:\n# 1. MCP server starts (if stdio)\n# 2. Tool calls succeed\n# 3. Results included in output\n```\n\n## Automated Testing Approaches\n\n### Command Test Suite\n\nCreate a test suite script:\n\n```bash\n#!/bin/bash\n# test-commands.sh - Command test suite\n\nTEST_DIR=\".claude/commands\"\nFAILED_TESTS=0\n\necho \"Command Test Suite\"\necho \"==================\"\necho\n\nfor cmd_file in \"$TEST_DIR\"/*.md; do\n cmd_name=$(basename \"$cmd_file\" .md)\n echo \"Testing: $cmd_name\"\n\n # Validate structure\n if ./validate-command.sh \"$cmd_file\"; then\n echo \" ✓ Structure valid\"\n else\n echo \" ✗ Structure invalid\"\n ((FAILED_TESTS++))\n fi\n\n # Validate frontmatter\n if ./validate-frontmatter.sh \"$cmd_file\"; then\n echo \" ✓ Frontmatter valid\"\n else\n echo \" ✗ Frontmatter invalid\"\n ((FAILED_TESTS++))\n fi\n\n echo\ndone\n\necho \"==================\"\necho \"Tests complete\"\necho \"Failed: $FAILED_TESTS\"\n\nexit $FAILED_TESTS\n```\n\n### Pre-Commit Hook\n\nValidate commands before committing:\n\n```bash\n#!/bin/bash\n# .git/hooks/pre-commit\n\necho \"Validating commands...\"\n\nCOMMANDS_CHANGED=$(git diff --cached --name-only | grep \"\\.claude/commands/.*\\.md\")\n\nif [ -z \"$COMMANDS_CHANGED\" ]; then\n echo \"No commands changed\"\n exit 0\nfi\n\nfor cmd in $COMMANDS_CHANGED; do\n echo \"Checking: $cmd\"\n\n if ! ./scripts/validate-command.sh \"$cmd\"; then\n echo \"ERROR: Command validation failed: $cmd\"\n exit 1\n fi\ndone\n\necho \"✓ All commands valid\"\n```\n\n### Continuous Testing\n\nTest commands in CI/CD:\n\n```yaml\n# .github/workflows/test-commands.yml\nname: Test Commands\n\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n\n - name: Validate command structure\n run: |\n for cmd in .claude/commands/*.md; do\n echo \"Testing: $cmd\"\n ./scripts/validate-command.sh \"$cmd\"\n done\n\n - name: Validate frontmatter\n run: |\n for cmd in .claude/commands/*.md; do\n ./scripts/validate-frontmatter.sh \"$cmd\"\n done\n\n - name: Check for TODOs\n run: |\n if grep -r \"TODO\" .claude/commands/; then\n echo \"ERROR: TODOs found in commands\"\n exit 1\n fi\n```\n\n## Edge Case Testing\n\n### Test Edge Cases\n\n**Empty arguments:**\n```bash\n> /cmd \"\"\n> /cmd '' ''\n```\n\n**Special characters:**\n```bash\n> /cmd \"arg with spaces\"\n> /cmd arg-with-dashes\n> /cmd arg_with_underscores\n> /cmd arg/with/slashes\n> /cmd 'arg with \"quotes\"'\n```\n\n**Long arguments:**\n```bash\n> /cmd $(python -c \"print('a' * 10000)\")\n```\n\n**Unusual file paths:**\n```bash\n> /cmd ./file\n> /cmd ../file\n> /cmd ~/file\n> /cmd \"/path with spaces/file\"\n```\n\n**Bash command edge cases:**\n```markdown\n# Commands that might fail\n!`exit 1`\n!`false`\n!`command-that-does-not-exist`\n\n# Commands with special output\n!`echo \"\"`\n!`cat /dev/null`\n!`yes | head -n 1000000`\n```\n\n## Performance Testing\n\n### Response Time Testing\n\n```bash\n#!/bin/bash\n# test-command-performance.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing performance of /$COMMAND\"\necho\n\nfor i in {1..5}; do\n echo \"Run $i:\"\n START=$(date +%s%N)\n\n # Invoke command (manual step - record time)\n echo \" Invoke: /$COMMAND\"\n echo \" Start time: $START\"\n echo \" (Record end time manually)\"\n echo\ndone\n\necho \"Analyze results:\"\necho \" - Average response time\"\necho \" - Variance\"\necho \" - Acceptable threshold: < 3 seconds for fast commands\"\n```\n\n### Resource Usage Testing\n\n```bash\n# Monitor Claude Code during command execution\n# In terminal 1:\nclaude --debug\n\n# In terminal 2:\nwatch -n 1 'ps aux | grep claude'\n\n# Execute command and observe:\n# - Memory usage\n# - CPU usage\n# - Process count\n```\n\n## User Experience Testing\n\n### Usability Checklist\n\n- [ ] Command name is intuitive\n- [ ] Description is clear in `/help`\n- [ ] Arguments are well-documented\n- [ ] Error messages are helpful\n- [ ] Output is formatted readably\n- [ ] Long-running commands show progress\n- [ ] Results are actionable\n- [ ] Edge cases have good UX\n\n### User Acceptance Testing\n\nRecruit testers:\n\n```markdown\n# Testing Guide for Beta Testers\n\n## Command: /my-new-command\n\n### Test Scenarios\n\n1. **Basic usage:**\n - Run: `/my-new-command`\n - Expected: [describe]\n - Rate clarity: 1-5\n\n2. **With arguments:**\n - Run: `/my-new-command arg1 arg2`\n - Expected: [describe]\n - Rate usefulness: 1-5\n\n3. **Error case:**\n - Run: `/my-new-command invalid-input`\n - Expected: Helpful error message\n - Rate error message: 1-5\n\n### Feedback Questions\n\n1. Was the command easy to understand?\n2. Did the output meet your expectations?\n3. What would you change?\n4. Would you use this command regularly?\n```\n\n## Testing Checklist\n\nBefore releasing a command:\n\n### Structure\n- [ ] File in correct location\n- [ ] Correct .md extension\n- [ ] Valid YAML frontmatter (if present)\n- [ ] Markdown syntax correct\n\n### Functionality\n- [ ] Command appears in `/help`\n- [ ] Description is clear\n- [ ] Command executes without errors\n- [ ] Arguments work as expected\n- [ ] File references work\n- [ ] Bash execution works (if used)\n\n### Edge Cases\n- [ ] Missing arguments handled\n- [ ] Invalid arguments detected\n- [ ] Non-existent files handled\n- [ ] Special characters work\n- [ ] Long inputs handled\n\n### Integration\n- [ ] Works with other commands\n- [ ] Works with hooks (if applicable)\n- [ ] Works with MCP (if applicable)\n- [ ] State management works\n\n### Quality\n- [ ] Performance acceptable\n- [ ] No security issues\n- [ ] Error messages helpful\n- [ ] Output formatted well\n- [ ] Documentation complete\n\n### Distribution\n- [ ] Tested by others\n- [ ] Feedback incorporated\n- [ ] README updated\n- [ ] Examples provided\n\n## Debugging Failed Tests\n\n### Common Issues and Solutions\n\n**Issue: Command not appearing in /help**\n\n```bash\n# Check file location\nls -la .claude/commands/my-command.md\n\n# Check permissions\nchmod 644 .claude/commands/my-command.md\n\n# Check syntax\nhead -n 20 .claude/commands/my-command.md\n\n# Restart Claude Code\nclaude --debug\n```\n\n**Issue: Arguments not substituting**\n\n```bash\n# Verify syntax\ngrep '\\$1' .claude/commands/my-command.md\ngrep '\\$ARGUMENTS' .claude/commands/my-command.md\n\n# Test with simple command first\necho \"Test: \\$1 and \\$2\" > .claude/commands/test-args.md\n```\n\n**Issue: Bash commands not executing**\n\n```bash\n# Check allowed-tools\ngrep \"allowed-tools\" .claude/commands/my-command.md\n\n# Verify command syntax\ngrep '!\\`' .claude/commands/my-command.md\n\n# Test command manually\ndate\necho \"test\"\n```\n\n**Issue: File references not working**\n\n```bash\n# Check @ syntax\ngrep '@' .claude/commands/my-command.md\n\n# Verify file exists\nls -la /path/to/referenced/file\n\n# Check permissions\nchmod 644 /path/to/referenced/file\n```\n\n## Best Practices\n\n1. **Test early, test often**: Validate as you develop\n2. **Automate validation**: Use scripts for repeatable checks\n3. **Test edge cases**: Don't just test the happy path\n4. **Get feedback**: Have others test before wide release\n5. **Document tests**: Keep test scenarios for regression testing\n6. **Monitor in production**: Watch for issues after release\n7. **Iterate**: Improve based on real usage data\n","plugins/plugin-dev/skills/hook-development/SKILL.md":"---\nname: Hook Development\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse/PostToolUse/Stop hook\", \"validate tool use\", \"implement prompt-based hooks\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"set up event-driven automation\", \"block dangerous commands\", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.\nversion: 0.1.0\n---\n\n# Hook Development for Claude Code Plugins\n\n## Overview\n\nHooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.\n\n**Key capabilities:**\n- Validate tool calls before execution (PreToolUse)\n- React to tool results (PostToolUse)\n- Enforce completion standards (Stop, SubagentStop)\n- Load project context (SessionStart)\n- Automate workflows across the development lifecycle\n\n## Hook Types\n\n### Prompt-Based Hooks (Recommended)\n\nUse LLM-driven decision making for context-aware validation:\n\n```json\n{\n \"type\": \"prompt\",\n \"prompt\": \"Evaluate if this tool use is appropriate: $TOOL_INPUT\",\n \"timeout\": 30\n}\n```\n\n**Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse\n\n**Benefits:**\n- Context-aware decisions based on natural language reasoning\n- Flexible evaluation logic without bash scripting\n- Better edge case handling\n- Easier to maintain and extend\n\n### Command Hooks\n\nExecute bash commands for deterministic checks:\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 60\n}\n```\n\n**Use for:**\n- Fast deterministic validations\n- File system operations\n- External tool integrations\n- Performance-critical checks\n\n## Hook Configuration Formats\n\n### Plugin hooks.json Format\n\n**For plugin hooks** in `hooks/hooks.json`, use wrapper format:\n\n```json\n{\n \"description\": \"Brief explanation of hooks (optional)\",\n \"hooks\": {\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n }\n}\n```\n\n**Key points:**\n- `description` field is optional\n- `hooks` field is required wrapper containing actual hook events\n- This is the **plugin-specific format**\n\n**Example:**\n```json\n{\n \"description\": \"Validation hooks for code quality\",\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh\"\n }\n ]\n }\n ]\n }\n}\n```\n\n### Settings Format (Direct)\n\n**For user settings** in `.claude/settings.json`, use direct format:\n\n```json\n{\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**Key points:**\n- No wrapper - events directly at top level\n- No description field\n- This is the **settings format**\n\n**Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{\"hooks\": {...}}`.\n\n## Hook Events\n\n### PreToolUse\n\nExecute before any tool runs. Use to approve, deny, or modify tool calls.\n\n**Example (prompt-based):**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output for PreToolUse:**\n```json\n{\n \"hookSpecificOutput\": {\n \"permissionDecision\": \"allow|deny|ask\",\n \"updatedInput\": {\"field\": \"modified_value\"}\n },\n \"systemMessage\": \"Explanation for Claude\"\n}\n```\n\n### PostToolUse\n\nExecute after tool completes. Use to react to results, provide feedback, or log.\n\n**Example:**\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output behavior:**\n- Exit 0: stdout shown in transcript\n- Exit 2: stderr fed back to Claude\n- systemMessage included in context\n\n### Stop\n\nExecute when main agent considers stopping. Use to validate completeness.\n\n**Example:**\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue.\"\n }\n ]\n }\n ]\n}\n```\n\n**Decision output:**\n```json\n{\n \"decision\": \"approve|block\",\n \"reason\": \"Explanation\",\n \"systemMessage\": \"Additional context\"\n}\n```\n\n### SubagentStop\n\nExecute when subagent considers stopping. Use to ensure subagent completed its task.\n\nSimilar to Stop hook, but for subagents.\n\n### UserPromptSubmit\n\nExecute when user submits a prompt. Use to add context, validate, or block prompts.\n\n**Example:**\n```json\n{\n \"UserPromptSubmit\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings.\"\n }\n ]\n }\n ]\n}\n```\n\n### SessionStart\n\nExecute when Claude Code session begins. Use to load context and set environment.\n\n**Example:**\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`:\n```bash\necho \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\n```\n\nSee `examples/load-context.sh` for complete example.\n\n### SessionEnd\n\nExecute when session ends. Use for cleanup, logging, and state preservation.\n\n### PreCompact\n\nExecute before context compaction. Use to add critical information to preserve.\n\n### Notification\n\nExecute when Claude sends notifications. Use to react to user notifications.\n\n## Hook Output Format\n\n### Standard Output (All Hooks)\n\n```json\n{\n \"continue\": true,\n \"suppressOutput\": false,\n \"systemMessage\": \"Message for Claude\"\n}\n```\n\n- `continue`: If false, halt processing (default true)\n- `suppressOutput`: Hide output from transcript (default false)\n- `systemMessage`: Message shown to Claude\n\n### Exit Codes\n\n- `0` - Success (stdout shown in transcript)\n- `2` - Blocking error (stderr fed back to Claude)\n- Other - Non-blocking error\n\n## Hook Input Format\n\nAll hooks receive JSON via stdin with common fields:\n\n```json\n{\n \"session_id\": \"abc123\",\n \"transcript_path\": \"/path/to/transcript.txt\",\n \"cwd\": \"/current/working/dir\",\n \"permission_mode\": \"ask|allow\",\n \"hook_event_name\": \"PreToolUse\"\n}\n```\n\n**Event-specific fields:**\n\n- **PreToolUse/PostToolUse:** `tool_name`, `tool_input`, `tool_result`\n- **UserPromptSubmit:** `user_prompt`\n- **Stop/SubagentStop:** `reason`\n\nAccess fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc.\n\n## Environment Variables\n\nAvailable in all command hooks:\n\n- `$CLAUDE_PROJECT_DIR` - Project root path\n- `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths)\n- `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here\n- `$CLAUDE_CODE_REMOTE` - Set if running in remote context\n\n**Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:**\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\"\n}\n```\n\n## Plugin Hook Configuration\n\nIn plugins, define hooks in `hooks/hooks.json`:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\",\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nPlugin hooks merge with user's hooks and run in parallel.\n\n## Matchers\n\n### Tool Name Matching\n\n**Exact match:**\n```json\n\"matcher\": \"Write\"\n```\n\n**Multiple tools:**\n```json\n\"matcher\": \"Read|Write|Edit\"\n```\n\n**Wildcard (all tools):**\n```json\n\"matcher\": \"*\"\n```\n\n**Regex patterns:**\n```json\n\"matcher\": \"mcp__.*__delete.*\" // All MCP delete tools\n```\n\n**Note:** Matchers are case-sensitive.\n\n### Common Patterns\n\n```json\n// All MCP tools\n\"matcher\": \"mcp__.*\"\n\n// Specific plugin's MCP tools\n\"matcher\": \"mcp__plugin_asana_.*\"\n\n// All file operations\n\"matcher\": \"Read|Write|Edit\"\n\n// Bash commands only\n\"matcher\": \"Bash\"\n```\n\n## Security Best Practices\n\n### Input Validation\n\nAlways validate inputs in command hooks:\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Validate tool name format\nif [[ ! \"$tool_name\" =~ ^[a-zA-Z0-9_]+$ ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Invalid tool name\"}' >&2\n exit 2\nfi\n```\n\n### Path Safety\n\nCheck for path traversal and sensitive files:\n\n```bash\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Deny path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Deny sensitive files\nif [[ \"$file_path\" == *\".env\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Sensitive file\"}' >&2\n exit 2\nfi\n```\n\nSee `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples.\n\n### Quote All Variables\n\n```bash\n# GOOD: Quoted\necho \"$file_path\"\ncd \"$CLAUDE_PROJECT_DIR\"\n\n# BAD: Unquoted (injection risk)\necho $file_path\ncd $CLAUDE_PROJECT_DIR\n```\n\n### Set Appropriate Timeouts\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash script.sh\",\n \"timeout\": 10\n}\n```\n\n**Defaults:** Command hooks (60s), Prompt hooks (30s)\n\n## Performance Considerations\n\n### Parallel Execution\n\nAll matching hooks run **in parallel**:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\"type\": \"command\", \"command\": \"check1.sh\"}, // Parallel\n {\"type\": \"command\", \"command\": \"check2.sh\"}, // Parallel\n {\"type\": \"prompt\", \"prompt\": \"Validate...\"} // Parallel\n ]\n }\n ]\n}\n```\n\n**Design implications:**\n- Hooks don't see each other's output\n- Non-deterministic ordering\n- Design for independence\n\n### Optimization\n\n1. Use command hooks for quick deterministic checks\n2. Use prompt hooks for complex reasoning\n3. Cache validation results in temp files\n4. Minimize I/O in hot paths\n\n## Temporarily Active Hooks\n\nCreate hooks that activate conditionally by checking for a flag file or configuration:\n\n**Pattern: Flag file activation**\n```bash\n#!/bin/bash\n# Only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-strict-validation\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Flag not present, skip validation\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\n# ... validation logic ...\n```\n\n**Pattern: Configuration-based activation**\n```bash\n#!/bin/bash\n# Check configuration for activation\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/plugin-config.json\"\n\nif [ -f \"$CONFIG_FILE\" ]; then\n enabled=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n if [ \"$enabled\" != \"true\" ]; then\n exit 0 # Not enabled, skip\n fi\nfi\n\n# Enabled, run hook logic\ninput=$(cat)\n# ... hook logic ...\n```\n\n**Use cases:**\n- Enable strict validation only when needed\n- Temporary debugging hooks\n- Project-specific hook behavior\n- Feature flags for hooks\n\n**Best practice:** Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.\n\n## Hook Lifecycle and Limitations\n\n### Hooks Load at Session Start\n\n**Important:** Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.\n\n**Cannot hot-swap hooks:**\n- Editing `hooks/hooks.json` won't affect current session\n- Adding new hook scripts won't be recognized\n- Changing hook commands/prompts won't update\n- Must restart Claude Code: exit and run `claude` again\n\n**To test hook changes:**\n1. Edit hook configuration or scripts\n2. Exit Claude Code session\n3. Restart: `claude` or `cc`\n4. New hook configuration loads\n5. Test hooks with `claude --debug`\n\n### Hook Validation at Startup\n\nHooks are validated when Claude Code starts:\n- Invalid JSON in hooks.json causes loading failure\n- Missing scripts cause warnings\n- Syntax errors reported in debug mode\n\nUse `/hooks` command to review loaded hooks in current session.\n\n## Debugging Hooks\n\n### Enable Debug Mode\n\n```bash\nclaude --debug\n```\n\nLook for hook registration, execution logs, input/output JSON, and timing information.\n\n### Test Hook Scripts\n\nTest command hooks directly:\n\n```bash\necho '{\"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"/test\"}}' | \\\n bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\n\necho \"Exit code: $?\"\n```\n\n### Validate JSON Output\n\nEnsure hooks output valid JSON:\n\n```bash\noutput=$(./your-hook.sh < test-input.json)\necho \"$output\" | jq .\n```\n\n## Quick Reference\n\n### Hook Events Summary\n\n| Event | When | Use For |\n|-------|------|---------|\n| PreToolUse | Before tool | Validation, modification |\n| PostToolUse | After tool | Feedback, logging |\n| UserPromptSubmit | User input | Context, validation |\n| Stop | Agent stopping | Completeness check |\n| SubagentStop | Subagent done | Task validation |\n| SessionStart | Session begins | Context loading |\n| SessionEnd | Session ends | Cleanup, logging |\n| PreCompact | Before compact | Preserve context |\n| Notification | User notified | Logging, reactions |\n\n### Best Practices\n\n**DO:**\n- ✅ Use prompt-based hooks for complex logic\n- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability\n- ✅ Validate all inputs in command hooks\n- ✅ Quote all bash variables\n- ✅ Set appropriate timeouts\n- ✅ Return structured JSON output\n- ✅ Test hooks thoroughly\n\n**DON'T:**\n- ❌ Use hardcoded paths\n- ❌ Trust user input without validation\n- ❌ Create long-running hooks\n- ❌ Rely on hook execution order\n- ❌ Modify global state unpredictably\n- ❌ Log sensitive information\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed patterns and advanced techniques, consult:\n\n- **`references/patterns.md`** - Common hook patterns (8+ proven patterns)\n- **`references/migration.md`** - Migrating from basic to advanced hooks\n- **`references/advanced.md`** - Advanced use cases and techniques\n\n### Example Hook Scripts\n\nWorking examples in `examples/`:\n\n- **`validate-write.sh`** - File write validation example\n- **`validate-bash.sh`** - Bash command validation example\n- **`load-context.sh`** - SessionStart context loading example\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-hook-schema.sh`** - Validate hooks.json structure and syntax\n- **`test-hook.sh`** - Test hooks with sample input before deployment\n- **`hook-linter.sh`** - Check hook scripts for common issues and best practices\n\n### External Resources\n\n- **Official Docs**: https://docs.claude.com/en/docs/claude-code/hooks\n- **Examples**: See security-guidance plugin in marketplace\n- **Testing**: Use `claude --debug` for detailed logs\n- **Validation**: Use `jq` to validate hook JSON output\n\n## Implementation Workflow\n\nTo implement hooks in a plugin:\n\n1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.)\n2. Decide between prompt-based (flexible) or command (deterministic) hooks\n3. Write hook configuration in `hooks/hooks.json`\n4. For command hooks, create hook scripts\n5. Use ${CLAUDE_PLUGIN_ROOT} for all file references\n6. Validate configuration with `scripts/validate-hook-schema.sh hooks/hooks.json`\n7. Test hooks with `scripts/test-hook.sh` before deployment\n8. Test in Claude Code with `claude --debug`\n9. Document hooks in plugin README\n\nFocus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.\n","plugins/plugin-dev/skills/hook-development/references/advanced.md":"# Advanced Hook Use Cases\n\nThis reference covers advanced hook patterns and techniques for sophisticated automation workflows.\n\n## Multi-Stage Validation\n\nCombine command and prompt hooks for layered validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Use case:** Fast deterministic checks followed by intelligent analysis\n\n**Example quick-check.sh:**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Immediate approval for safe commands\nif [[ \"$command\" =~ ^(ls|pwd|echo|date|whoami)$ ]]; then\n exit 0\nfi\n\n# Let prompt hook handle complex cases\nexit 0\n```\n\nThe command hook quickly approves obviously safe commands, while the prompt hook analyzes everything else.\n\n## Conditional Hook Execution\n\nExecute hooks based on environment or context:\n\n```bash\n#!/bin/bash\n# Only run in CI environment\nif [ -z \"$CI\" ]; then\n echo '{\"continue\": true}' # Skip in non-CI\n exit 0\nfi\n\n# Run validation logic in CI\ninput=$(cat)\n# ... validation code ...\n```\n\n**Use cases:**\n- Different behavior in CI vs local development\n- Project-specific validation\n- User-specific rules\n\n**Example: Skip certain checks for trusted users:**\n```bash\n#!/bin/bash\n# Skip detailed checks for admin users\nif [ \"$USER\" = \"admin\" ]; then\n exit 0\nfi\n\n# Full validation for other users\ninput=$(cat)\n# ... validation code ...\n```\n\n## Hook Chaining via State\n\nShare state between hooks using temporary files:\n\n```bash\n# Hook 1: Analyze and save state\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Analyze command\nrisk_level=$(calculate_risk \"$command\")\necho \"$risk_level\" > /tmp/hook-state-$$\n\nexit 0\n```\n\n```bash\n# Hook 2: Use saved state\n#!/bin/bash\nrisk_level=$(cat /tmp/hook-state-$$ 2>/dev/null || echo \"unknown\")\n\nif [ \"$risk_level\" = \"high\" ]; then\n echo \"High risk operation detected\" >&2\n exit 2\nfi\n```\n\n**Important:** This only works for sequential hook events (e.g., PreToolUse then PostToolUse), not parallel hooks.\n\n## Dynamic Hook Configuration\n\nModify hook behavior based on project configuration:\n\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Read project-specific config\nif [ -f \".claude-hooks-config.json\" ]; then\n strict_mode=$(jq -r '.strict_mode' .claude-hooks-config.json)\n\n if [ \"$strict_mode\" = \"true\" ]; then\n # Apply strict validation\n # ...\n else\n # Apply lenient validation\n # ...\n fi\nfi\n```\n\n**Example .claude-hooks-config.json:**\n```json\n{\n \"strict_mode\": true,\n \"allowed_commands\": [\"ls\", \"pwd\", \"grep\"],\n \"forbidden_paths\": [\"/etc\", \"/sys\"]\n}\n```\n\n## Context-Aware Prompt Hooks\n\nUse transcript and session context for intelligent decisions:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review the full transcript at $TRANSCRIPT_PATH. Check: 1) Were tests run after code changes? 2) Did the build succeed? 3) Were all user questions answered? 4) Is there any unfinished work? Return 'approve' only if everything is complete.\"\n }\n ]\n }\n ]\n}\n```\n\nThe LLM can read the transcript file and make context-aware decisions.\n\n## Performance Optimization\n\n### Caching Validation Results\n\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncache_key=$(echo -n \"$file_path\" | md5sum | cut -d' ' -f1)\ncache_file=\"/tmp/hook-cache-$cache_key\"\n\n# Check cache\nif [ -f \"$cache_file\" ]; then\n cache_age=$(($(date +%s) - $(stat -f%m \"$cache_file\" 2>/dev/null || stat -c%Y \"$cache_file\")))\n if [ \"$cache_age\" -lt 300 ]; then # 5 minute cache\n cat \"$cache_file\"\n exit 0\n fi\nfi\n\n# Perform validation\nresult='{\"decision\": \"approve\"}'\n\n# Cache result\necho \"$result\" > \"$cache_file\"\necho \"$result\"\n```\n\n### Parallel Execution Optimization\n\nSince hooks run in parallel, design them to be independent:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash check-size.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"command\",\n \"command\": \"bash check-path.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check content safety\", // Independent\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nAll three hooks run simultaneously, reducing total latency.\n\n## Cross-Event Workflows\n\nCoordinate hooks across different events:\n\n**SessionStart - Set up tracking:**\n```bash\n#!/bin/bash\n# Initialize session tracking\necho \"0\" > /tmp/test-count-$$\necho \"0\" > /tmp/build-count-$$\n```\n\n**PostToolUse - Track events:**\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\nif [ \"$tool_name\" = \"Bash\" ]; then\n command=$(echo \"$input\" | jq -r '.tool_result')\n if [[ \"$command\" == *\"test\"* ]]; then\n count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n echo $((count + 1)) > /tmp/test-count-$$\n fi\nfi\n```\n\n**Stop - Verify based on tracking:**\n```bash\n#!/bin/bash\ntest_count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n\nif [ \"$test_count\" -eq 0 ]; then\n echo '{\"decision\": \"block\", \"reason\": \"No tests were run\"}' >&2\n exit 2\nfi\n```\n\n## Integration with External Systems\n\n### Slack Notifications\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ndecision=\"blocked\"\n\n# Send notification to Slack\ncurl -X POST \"$SLACK_WEBHOOK\" \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"text\\\": \\\"Hook ${decision} ${tool_name} operation\\\"}\" \\\n 2>/dev/null\n\necho '{\"decision\": \"deny\"}' >&2\nexit 2\n```\n\n### Database Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\n\n# Log to database\npsql \"$DATABASE_URL\" -c \"INSERT INTO hook_logs (event, data) VALUES ('PreToolUse', '$input')\" \\\n 2>/dev/null\n\nexit 0\n```\n\n### Metrics Collection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Send metrics to monitoring system\necho \"hook.pretooluse.${tool_name}:1|c\" | nc -u -w1 statsd.local 8125\n\nexit 0\n```\n\n## Security Patterns\n\n### Rate Limiting\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Track command frequency\nrate_file=\"/tmp/hook-rate-$$\"\ncurrent_minute=$(date +%Y%m%d%H%M)\n\nif [ -f \"$rate_file\" ]; then\n last_minute=$(head -1 \"$rate_file\")\n count=$(tail -1 \"$rate_file\")\n\n if [ \"$current_minute\" = \"$last_minute\" ]; then\n if [ \"$count\" -gt 10 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Rate limit exceeded\"}' >&2\n exit 2\n fi\n count=$((count + 1))\n else\n count=1\n fi\nelse\n count=1\nfi\n\necho \"$current_minute\" > \"$rate_file\"\necho \"$count\" >> \"$rate_file\"\n\nexit 0\n```\n\n### Audit Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ntimestamp=$(date -Iseconds)\n\n# Append to audit log\necho \"$timestamp | $USER | $tool_name | $input\" >> ~/.claude/audit.log\n\nexit 0\n```\n\n### Secret Detection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncontent=$(echo \"$input\" | jq -r '.tool_input.content')\n\n# Check for common secret patterns\nif echo \"$content\" | grep -qE \"(api[_-]?key|password|secret|token).{0,20}['\\\"]?[A-Za-z0-9]{20,}\"; then\n echo '{\"decision\": \"deny\", \"reason\": \"Potential secret detected in content\"}' >&2\n exit 2\nfi\n\nexit 0\n```\n\n## Testing Advanced Hooks\n\n### Unit Testing Hook Scripts\n\n```bash\n# test-hook.sh\n#!/bin/bash\n\n# Test 1: Approve safe command\nresult=$(echo '{\"tool_input\": {\"command\": \"ls\"}}' | bash validate-bash.sh)\nif [ $? -eq 0 ]; then\n echo \"✓ Test 1 passed\"\nelse\n echo \"✗ Test 1 failed\"\nfi\n\n# Test 2: Block dangerous command\nresult=$(echo '{\"tool_input\": {\"command\": \"rm -rf /\"}}' | bash validate-bash.sh)\nif [ $? -eq 2 ]; then\n echo \"✓ Test 2 passed\"\nelse\n echo \"✗ Test 2 failed\"\nfi\n```\n\n### Integration Testing\n\nCreate test scenarios that exercise the full hook workflow:\n\n```bash\n# integration-test.sh\n#!/bin/bash\n\n# Set up test environment\nexport CLAUDE_PROJECT_DIR=\"/tmp/test-project\"\nexport CLAUDE_PLUGIN_ROOT=\"$(pwd)\"\nmkdir -p \"$CLAUDE_PROJECT_DIR\"\n\n# Test SessionStart hook\necho '{}' | bash hooks/session-start.sh\nif [ -f \"/tmp/session-initialized\" ]; then\n echo \"✓ SessionStart hook works\"\nelse\n echo \"✗ SessionStart hook failed\"\nfi\n\n# Clean up\nrm -rf \"$CLAUDE_PROJECT_DIR\"\n```\n\n## Best Practices for Advanced Hooks\n\n1. **Keep hooks independent**: Don't rely on execution order\n2. **Use timeouts**: Set appropriate limits for each hook type\n3. **Handle errors gracefully**: Provide clear error messages\n4. **Document complexity**: Explain advanced patterns in README\n5. **Test thoroughly**: Cover edge cases and failure modes\n6. **Monitor performance**: Track hook execution time\n7. **Version configuration**: Use version control for hook configs\n8. **Provide escape hatches**: Allow users to bypass hooks when needed\n\n## Common Pitfalls\n\n### ❌ Assuming Hook Order\n\n```bash\n# BAD: Assumes hooks run in specific order\n# Hook 1 saves state, Hook 2 reads it\n# This can fail because hooks run in parallel!\n```\n\n### ❌ Long-Running Hooks\n\n```bash\n# BAD: Hook takes 2 minutes to run\nsleep 120\n# This will timeout and block the workflow\n```\n\n### ❌ Uncaught Exceptions\n\n```bash\n# BAD: Script crashes on unexpected input\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncat \"$file_path\" # Fails if file doesn't exist\n```\n\n### ✅ Proper Error Handling\n\n```bash\n# GOOD: Handles errors gracefully\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nif [ ! -f \"$file_path\" ]; then\n echo '{\"continue\": true, \"systemMessage\": \"File not found, skipping check\"}' >&2\n exit 0\nfi\n```\n\n## Conclusion\n\nAdvanced hook patterns enable sophisticated automation while maintaining reliability and performance. Use these techniques when basic hooks are insufficient, but always prioritize simplicity and maintainability.\n","plugins/plugin-dev/skills/hook-development/references/migration.md":"# Migrating from Basic to Advanced Hooks\n\nThis guide shows how to migrate from basic command hooks to advanced prompt-based hooks for better maintainability and flexibility.\n\n## Why Migrate?\n\nPrompt-based hooks offer several advantages:\n\n- **Natural language reasoning**: LLM understands context and intent\n- **Better edge case handling**: Adapts to unexpected scenarios\n- **No bash scripting required**: Simpler to write and maintain\n- **More flexible validation**: Can handle complex logic without coding\n\n## Migration Example: Bash Command Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-bash.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-bash.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Hard-coded validation logic\nif [[ \"$command\" == *\"rm -rf\"* ]]; then\n echo \"Dangerous command detected\" >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Only checks for exact \"rm -rf\" pattern\n- Doesn't catch variations like `rm -fr` or `rm -r -f`\n- Misses other dangerous commands (`dd`, `mkfs`, etc.)\n- No context awareness\n- Requires bash scripting knowledge\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. Analyze for: 1) Destructive operations (rm -rf, dd, mkfs, etc) 2) Privilege escalation (sudo) 3) Network operations without user consent. Return 'approve' or 'deny' with explanation.\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Catches all variations and patterns\n- Understands intent, not just literal strings\n- No script file needed\n- Easy to extend with new criteria\n- Context-aware decisions\n- Natural language explanation in denial\n\n## Migration Example: File Write Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-write.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-write.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Check for path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Check for system paths\nif [[ \"$file_path\" == \"/etc/\"* ]] || [[ \"$file_path\" == \"/sys/\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"System file\"}' >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Hard-coded path patterns\n- Doesn't understand symlinks\n- Missing edge cases (e.g., `/etc` vs `/etc/`)\n- No consideration of file content\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Content preview: $TOOL_INPUT.content (first 200 chars). Verify: 1) Not system directories (/etc, /sys, /usr) 2) Not credentials (.env, tokens, secrets) 3) No path traversal 4) Content doesn't expose secrets. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Context-aware (considers content too)\n- Handles symlinks and edge cases\n- Natural understanding of \"system directories\"\n- Can detect secrets in content\n- Easy to extend criteria\n\n## When to Keep Command Hooks\n\nCommand hooks still have their place:\n\n### 1. Deterministic Performance Checks\n\n```bash\n#!/bin/bash\n# Check file size quickly\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nsize=$(stat -f%z \"$file_path\" 2>/dev/null || stat -c%s \"$file_path\" 2>/dev/null)\n\nif [ \"$size\" -gt 10000000 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File too large\"}' >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Validation is purely mathematical or deterministic.\n\n### 2. External Tool Integration\n\n```bash\n#!/bin/bash\n# Run security scanner\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nscan_result=$(security-scanner \"$file_path\")\n\nif [ \"$?\" -ne 0 ]; then\n echo \"Security scan failed: $scan_result\" >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Integrating with external tools that provide yes/no answers.\n\n### 3. Very Fast Checks (< 50ms)\n\n```bash\n#!/bin/bash\n# Quick regex check\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\nif [[ \"$command\" =~ ^(ls|pwd|echo)$ ]]; then\n exit 0 # Safe commands\nfi\n```\n\n**Use command hooks when:** Performance is critical and logic is simple.\n\n## Hybrid Approach\n\nCombine both for multi-stage validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\nThe command hook does fast deterministic checks, while the prompt hook handles complex reasoning.\n\n## Migration Checklist\n\nWhen migrating hooks:\n\n- [ ] Identify the validation logic in the command hook\n- [ ] Convert hard-coded patterns to natural language criteria\n- [ ] Test with edge cases the old hook missed\n- [ ] Verify LLM understands the intent\n- [ ] Set appropriate timeout (usually 15-30s for prompt hooks)\n- [ ] Document the new hook in README\n- [ ] Remove or archive old script files\n\n## Migration Tips\n\n1. **Start with one hook**: Don't migrate everything at once\n2. **Test thoroughly**: Verify prompt hook catches what command hook caught\n3. **Look for improvements**: Use migration as opportunity to enhance validation\n4. **Keep scripts for reference**: Archive old scripts in case you need to reference the logic\n5. **Document reasoning**: Explain why prompt hook is better in README\n\n## Complete Migration Example\n\n### Original Plugin Structure\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json\n└── scripts/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### After Migration\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json # Now uses prompt hooks\n└── scripts/ # Archive or delete\n └── archive/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### Updated hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety: destructive ops, privilege escalation, network access\"\n }\n ]\n },\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety: system paths, credentials, path traversal, content secrets\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests were run if code was modified\"\n }\n ]\n }\n ]\n}\n```\n\n**Result:** Simpler, more maintainable, more powerful.\n\n## Common Migration Patterns\n\n### Pattern: String Contains → Natural Language\n\n**Before:**\n```bash\nif [[ \"$command\" == *\"sudo\"* ]]; then\n echo \"Privilege escalation\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check for privilege escalation (sudo, su, etc)\"\n```\n\n### Pattern: Regex → Intent\n\n**Before:**\n```bash\nif [[ \"$file\" =~ \\.(env|secret|key|token)$ ]]; then\n echo \"Credential file\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Verify not writing to credential files (.env, secrets, keys, tokens)\"\n```\n\n### Pattern: Multiple Conditions → Criteria List\n\n**Before:**\n```bash\nif [ condition1 ] || [ condition2 ] || [ condition3 ]; then\n echo \"Invalid\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check: 1) condition1 2) condition2 3) condition3. Deny if any fail.\"\n```\n\n## Conclusion\n\nMigrating to prompt-based hooks makes plugins more maintainable, flexible, and powerful. Reserve command hooks for deterministic checks and external tool integration.\n","plugins/plugin-dev/skills/hook-development/references/patterns.md":"# Common Hook Patterns\n\nThis reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases.\n\n## Pattern 1: Security Validation\n\nBlock dangerous file writes using prompt-based hooks:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Preventing writes to sensitive files or system directories.\n\n## Pattern 2: Test Enforcement\n\nEnsure tests run before stopping:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Enforcing quality standards and preventing incomplete work.\n\n## Pattern 3: Context Loading\n\nLoad project-specific context at session start:\n\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (load-context.sh):**\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Detect project type\nif [ -f \"package.json\" ]; then\n echo \"📦 Node.js project detected\"\n echo \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\nelif [ -f \"Cargo.toml\" ]; then\n echo \"🦀 Rust project detected\"\n echo \"export PROJECT_TYPE=rust\" >> \"$CLAUDE_ENV_FILE\"\nfi\n```\n\n**Use for:** Automatically detecting and configuring project-specific settings.\n\n## Pattern 4: Notification Logging\n\nLog all notifications for audit or analysis:\n\n```json\n{\n \"Notification\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Tracking user notifications or integration with external logging systems.\n\n## Pattern 5: MCP Tool Monitoring\n\nMonitor and validate MCP tool usage:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"mcp__.*__delete.*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Protecting against destructive MCP operations.\n\n## Pattern 6: Build Verification\n\nEnsure project builds after code changes:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Catching build errors before committing or stopping work.\n\n## Pattern 7: Permission Confirmation\n\nAsk user before dangerous operations:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** User confirmation on potentially destructive commands.\n\n## Pattern 8: Code Quality Checks\n\nRun linters or formatters on file edits:\n\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (check-quality.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run linter if applicable\nif [[ \"$file_path\" == *.js ]] || [[ \"$file_path\" == *.ts ]]; then\n npx eslint \"$file_path\" 2>&1 || true\nfi\n```\n\n**Use for:** Automatic code quality enforcement.\n\n## Pattern Combinations\n\nCombine multiple patterns for comprehensive protection:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n },\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests run and build succeeded\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\nThis provides multi-layered protection and automation.\n\n## Pattern 9: Temporarily Active Hooks\n\nCreate hooks that only run when explicitly enabled via flag files:\n\n```bash\n#!/bin/bash\n# Hook only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-security-scan\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Quick exit when disabled\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run security scan\nsecurity-scanner \"$file_path\"\n```\n\n**Activation:**\n```bash\n# Enable the hook\ntouch .enable-security-scan\n\n# Disable the hook\nrm .enable-security-scan\n```\n\n**Use for:**\n- Temporary debugging hooks\n- Feature flags for development\n- Project-specific validation that's opt-in\n- Performance-intensive checks only when needed\n\n**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes.\n\n## Pattern 10: Configuration-Driven Hooks\n\nUse JSON configuration to control hook behavior:\n\n```bash\n#!/bin/bash\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json\"\n\n# Read configuration\nif [ -f \"$CONFIG_FILE\" ]; then\n strict_mode=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n max_file_size=$(jq -r '.maxFileSize // 1000000' \"$CONFIG_FILE\")\nelse\n # Defaults\n strict_mode=false\n max_file_size=1000000\nfi\n\n# Skip if not in strict mode\nif [ \"$strict_mode\" != \"true\" ]; then\n exit 0\nfi\n\n# Apply configured limits\ninput=$(cat)\nfile_size=$(echo \"$input\" | jq -r '.tool_input.content | length')\n\nif [ \"$file_size\" -gt \"$max_file_size\" ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File exceeds configured size limit\"}' >&2\n exit 2\nfi\n```\n\n**Configuration file (.claude/my-plugin.local.json):**\n```json\n{\n \"strictMode\": true,\n \"maxFileSize\": 500000,\n \"allowedPaths\": [\"/tmp\", \"/home/user/projects\"]\n}\n```\n\n**Use for:**\n- User-configurable hook behavior\n- Per-project settings\n- Team-specific rules\n- Dynamic validation criteria\n","plugins/plugin-dev/skills/hook-development/scripts/README.md":"","plugins/plugin-dev/skills/mcp-integration/SKILL.md":"---\nname: MCP Integration\ndescription: This skill should be used when the user asks to \"add MCP server\", \"integrate MCP\", \"configure MCP in plugin\", \"use .mcp.json\", \"set up Model Context Protocol\", \"connect external service\", mentions \"${CLAUDE_PLUGIN_ROOT} with MCP\", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.\nversion: 0.1.0\n---\n\n# MCP Integration for Claude Code Plugins\n\n## Overview\n\nModel Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.\n\n**Key capabilities:**\n- Connect to external services (databases, APIs, file systems)\n- Provide 10+ related tools from a single service\n- Handle OAuth and complex authentication flows\n- Bundle MCP servers with plugins for automatic setup\n\n## MCP Server Configuration Methods\n\nPlugins can bundle MCP servers in two ways:\n\n### Method 1: Dedicated .mcp.json (Recommended)\n\nCreate `.mcp.json` at plugin root:\n\n```json\n{\n \"database-tools\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server\",\n \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config.json\"],\n \"env\": {\n \"DB_URL\": \"${DB_URL}\"\n }\n }\n}\n```\n\n**Benefits:**\n- Clear separation of concerns\n- Easier to maintain\n- Better for multiple servers\n\n### Method 2: Inline in plugin.json\n\nAdd `mcpServers` field to plugin.json:\n\n```json\n{\n \"name\": \"my-plugin\",\n \"version\": \"1.0.0\",\n \"mcpServers\": {\n \"plugin-api\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/api-server\",\n \"args\": [\"--port\", \"8080\"]\n }\n }\n}\n```\n\n**Benefits:**\n- Single configuration file\n- Good for simple single-server plugins\n\n## MCP Server Types\n\n### stdio (Local Process)\n\nExecute local MCP servers as child processes. Best for local tools and custom servers.\n\n**Configuration:**\n```json\n{\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/allowed/path\"],\n \"env\": {\n \"LOG_LEVEL\": \"debug\"\n }\n }\n}\n```\n\n**Use cases:**\n- File system access\n- Local database connections\n- Custom MCP servers\n- NPM-packaged MCP servers\n\n**Process management:**\n- Claude Code spawns and manages the process\n- Communicates via stdin/stdout\n- Terminates when Claude Code exits\n\n### SSE (Server-Sent Events)\n\nConnect to hosted MCP servers with OAuth support. Best for cloud services.\n\n**Configuration:**\n```json\n{\n \"asana\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.asana.com/sse\"\n }\n}\n```\n\n**Use cases:**\n- Official hosted MCP servers (Asana, GitHub, etc.)\n- Cloud services with MCP endpoints\n- OAuth-based authentication\n- No local installation needed\n\n**Authentication:**\n- OAuth flows handled automatically\n- User prompted on first use\n- Tokens managed by Claude Code\n\n### HTTP (REST API)\n\nConnect to RESTful MCP servers with token authentication.\n\n**Configuration:**\n```json\n{\n \"api-service\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"X-Custom-Header\": \"value\"\n }\n }\n}\n```\n\n**Use cases:**\n- REST API-based MCP servers\n- Token-based authentication\n- Custom API backends\n- Stateless interactions\n\n### WebSocket (Real-time)\n\nConnect to WebSocket MCP servers for real-time bidirectional communication.\n\n**Configuration:**\n```json\n{\n \"realtime-service\": {\n \"type\": \"ws\",\n \"url\": \"wss://mcp.example.com/ws\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TOKEN}\"\n }\n }\n}\n```\n\n**Use cases:**\n- Real-time data streaming\n- Persistent connections\n- Push notifications from server\n- Low-latency requirements\n\n## Environment Variable Expansion\n\nAll MCP configurations support environment variable substitution:\n\n**${CLAUDE_PLUGIN_ROOT}** - Plugin directory (always use for portability):\n```json\n{\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/my-server\"\n}\n```\n\n**User environment variables** - From user's shell:\n```json\n{\n \"env\": {\n \"API_KEY\": \"${MY_API_KEY}\",\n \"DATABASE_URL\": \"${DB_URL}\"\n }\n}\n```\n\n**Best practice:** Document all required environment variables in plugin README.\n\n## MCP Tool Naming\n\nWhen MCP servers provide tools, they're automatically prefixed:\n\n**Format:** `mcp__plugin____`\n\n**Example:**\n- Plugin: `asana`\n- Server: `asana`\n- Tool: `create_task`\n- **Full name:** `mcp__plugin_asana_asana__asana_create_task`\n\n### Using MCP Tools in Commands\n\nPre-allow specific MCP tools in command frontmatter:\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\",\n \"mcp__plugin_asana_asana__asana_search_tasks\"\n]\n---\n```\n\n**Wildcard (use sparingly):**\n```markdown\n---\nallowed-tools: [\"mcp__plugin_asana_asana__*\"]\n---\n```\n\n**Best practice:** Pre-allow specific tools, not wildcards, for security.\n\n## Lifecycle Management\n\n**Automatic startup:**\n- MCP servers start when plugin enables\n- Connection established before first tool use\n- Restart required for configuration changes\n\n**Lifecycle:**\n1. Plugin loads\n2. MCP configuration parsed\n3. Server process started (stdio) or connection established (SSE/HTTP/WS)\n4. Tools discovered and registered\n5. Tools available as `mcp__plugin_...__...`\n\n**Viewing servers:**\nUse `/mcp` command to see all servers including plugin-provided ones.\n\n## Authentication Patterns\n\n### OAuth (SSE/HTTP)\n\nOAuth handled automatically by Claude Code:\n\n```json\n{\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\"\n}\n```\n\nUser authenticates in browser on first use. No additional configuration needed.\n\n### Token-Based (Headers)\n\nStatic or environment variable tokens:\n\n```json\n{\n \"type\": \"http\",\n \"url\": \"https://api.example.com\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\"\n }\n}\n```\n\nDocument required environment variables in README.\n\n### Environment Variables (stdio)\n\nPass configuration to MCP server:\n\n```json\n{\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\"],\n \"env\": {\n \"DATABASE_URL\": \"${DB_URL}\",\n \"API_KEY\": \"${API_KEY}\",\n \"LOG_LEVEL\": \"info\"\n }\n}\n```\n\n## Integration Patterns\n\n### Pattern 1: Simple Tool Wrapper\n\nCommands use MCP tools with user interaction:\n\n```markdown\n# Command: create-item.md\n---\nallowed-tools: [\"mcp__plugin_name_server__create_item\"]\n---\n\nSteps:\n1. Gather item details from user\n2. Use mcp__plugin_name_server__create_item\n3. Confirm creation\n```\n\n**Use for:** Adding validation or preprocessing before MCP calls.\n\n### Pattern 2: Autonomous Agent\n\nAgents use MCP tools autonomously:\n\n```markdown\n# Agent: data-analyzer.md\n\nAnalysis Process:\n1. Query data via mcp__plugin_db_server__query\n2. Process and analyze results\n3. Generate insights report\n```\n\n**Use for:** Multi-step MCP workflows without user interaction.\n\n### Pattern 3: Multi-Server Plugin\n\nIntegrate multiple MCP servers:\n\n```json\n{\n \"github\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.github.com/sse\"\n },\n \"jira\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.jira.com/sse\"\n }\n}\n```\n\n**Use for:** Workflows spanning multiple services.\n\n## Security Best Practices\n\n### Use HTTPS/WSS\n\nAlways use secure connections:\n\n```json\n✅ \"url\": \"https://mcp.example.com/sse\"\n❌ \"url\": \"http://mcp.example.com/sse\"\n```\n\n### Token Management\n\n**DO:**\n- ✅ Use environment variables for tokens\n- ✅ Document required env vars in README\n- ✅ Let OAuth flow handle authentication\n\n**DON'T:**\n- ❌ Hardcode tokens in configuration\n- ❌ Commit tokens to git\n- ❌ Share tokens in documentation\n\n### Permission Scoping\n\nPre-allow only necessary MCP tools:\n\n```markdown\n✅ allowed-tools: [\n \"mcp__plugin_api_server__read_data\",\n \"mcp__plugin_api_server__create_item\"\n]\n\n❌ allowed-tools: [\"mcp__plugin_api_server__*\"]\n```\n\n## Error Handling\n\n### Connection Failures\n\nHandle MCP server unavailability:\n- Provide fallback behavior in commands\n- Inform user of connection issues\n- Check server URL and configuration\n\n### Tool Call Errors\n\nHandle failed MCP operations:\n- Validate inputs before calling MCP tools\n- Provide clear error messages\n- Check rate limiting and quotas\n\n### Configuration Errors\n\nValidate MCP configuration:\n- Test server connectivity during development\n- Validate JSON syntax\n- Check required environment variables\n\n## Performance Considerations\n\n### Lazy Loading\n\nMCP servers connect on-demand:\n- Not all servers connect at startup\n- First tool use triggers connection\n- Connection pooling managed automatically\n\n### Batching\n\nBatch similar requests when possible:\n\n```\n# Good: Single query with filters\ntasks = search_tasks(project=\"X\", assignee=\"me\", limit=50)\n\n# Avoid: Many individual queries\nfor id in task_ids:\n task = get_task(id)\n```\n\n## Testing MCP Integration\n\n### Local Testing\n\n1. Configure MCP server in `.mcp.json`\n2. Install plugin locally (`.claude-plugin/`)\n3. Run `/mcp` to verify server appears\n4. Test tool calls in commands\n5. Check `claude --debug` logs for connection issues\n\n### Validation Checklist\n\n- [ ] MCP configuration is valid JSON\n- [ ] Server URL is correct and accessible\n- [ ] Required environment variables documented\n- [ ] Tools appear in `/mcp` output\n- [ ] Authentication works (OAuth or tokens)\n- [ ] Tool calls succeed from commands\n- [ ] Error cases handled gracefully\n\n## Debugging\n\n### Enable Debug Logging\n\n```bash\nclaude --debug\n```\n\nLook for:\n- MCP server connection attempts\n- Tool discovery logs\n- Authentication flows\n- Tool call errors\n\n### Common Issues\n\n**Server not connecting:**\n- Check URL is correct\n- Verify server is running (stdio)\n- Check network connectivity\n- Review authentication configuration\n\n**Tools not available:**\n- Verify server connected successfully\n- Check tool names match exactly\n- Run `/mcp` to see available tools\n- Restart Claude Code after config changes\n\n**Authentication failing:**\n- Clear cached auth tokens\n- Re-authenticate\n- Check token scopes and permissions\n- Verify environment variables set\n\n## Quick Reference\n\n### MCP Server Types\n\n| Type | Transport | Best For | Auth |\n|------|-----------|----------|------|\n| stdio | Process | Local tools, custom servers | Env vars |\n| SSE | HTTP | Hosted services, cloud APIs | OAuth |\n| HTTP | REST | API backends, token auth | Tokens |\n| ws | WebSocket | Real-time, streaming | Tokens |\n\n### Configuration Checklist\n\n- [ ] Server type specified (stdio/SSE/HTTP/ws)\n- [ ] Type-specific fields complete (command or url)\n- [ ] Authentication configured\n- [ ] Environment variables documented\n- [ ] HTTPS/WSS used (not HTTP/WS)\n- [ ] ${CLAUDE_PLUGIN_ROOT} used for paths\n\n### Best Practices\n\n**DO:**\n- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths\n- ✅ Document required environment variables\n- ✅ Use secure connections (HTTPS/WSS)\n- ✅ Pre-allow specific MCP tools in commands\n- ✅ Test MCP integration before publishing\n- ✅ Handle connection and tool errors gracefully\n\n**DON'T:**\n- ❌ Hardcode absolute paths\n- ❌ Commit credentials to git\n- ❌ Use HTTP instead of HTTPS\n- ❌ Pre-allow all tools with wildcards\n- ❌ Skip error handling\n- ❌ Forget to document setup\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed information, consult:\n\n- **`references/server-types.md`** - Deep dive on each server type\n- **`references/authentication.md`** - Authentication patterns and OAuth\n- **`references/tool-usage.md`** - Using MCP tools in commands and agents\n\n### Example Configurations\n\nWorking examples in `examples/`:\n\n- **`stdio-server.json`** - Local stdio MCP server\n- **`sse-server.json`** - Hosted SSE server with OAuth\n- **`http-server.json`** - REST API with token auth\n\n### External Resources\n\n- **Official MCP Docs**: https://modelcontextprotocol.io/\n- **Claude Code MCP Docs**: https://docs.claude.com/en/docs/claude-code/mcp\n- **MCP SDK**: @modelcontextprotocol/sdk\n- **Testing**: Use `claude --debug` and `/mcp` command\n\n## Implementation Workflow\n\nTo add MCP integration to a plugin:\n\n1. Choose MCP server type (stdio, SSE, HTTP, ws)\n2. Create `.mcp.json` at plugin root with configuration\n3. Use ${CLAUDE_PLUGIN_ROOT} for all file references\n4. Document required environment variables in README\n5. Test locally with `/mcp` command\n6. Pre-allow MCP tools in relevant commands\n7. Handle authentication (OAuth or tokens)\n8. Test error cases (connection failures, auth errors)\n9. Document MCP integration in plugin README\n\nFocus on stdio for custom/local servers, SSE for hosted services with OAuth.\n","plugins/plugin-dev/skills/mcp-integration/examples/http-server.json":"{\n \"_comment\": \"Example HTTP MCP server configuration for REST APIs\",\n \"rest-api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"Content-Type\": \"application/json\",\n \"X-API-Version\": \"2024-01-01\"\n }\n },\n \"internal-service\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"X-Service-Name\": \"claude-plugin\"\n }\n }\n}\n","plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json":"{\n \"_comment\": \"Example SSE MCP server configuration for hosted cloud services\",\n \"asana\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.asana.com/sse\"\n },\n \"github\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.github.com/sse\"\n },\n \"custom-service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-API-Version\": \"v1\",\n \"X-Client-ID\": \"${CLIENT_ID}\"\n }\n }\n}\n","plugins/plugin-dev/skills/mcp-integration/examples/stdio-server.json":"{\n \"_comment\": \"Example stdio MCP server configuration for local file system access\",\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"${CLAUDE_PROJECT_DIR}\"],\n \"env\": {\n \"LOG_LEVEL\": \"info\"\n }\n },\n \"database\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server.js\",\n \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config/db.json\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_POOL_SIZE\": \"10\"\n }\n },\n \"custom-tools\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\", \"--port\", \"8080\"],\n \"env\": {\n \"API_KEY\": \"${CUSTOM_API_KEY}\",\n \"DEBUG\": \"false\"\n }\n }\n}\n","plugins/plugin-dev/skills/mcp-integration/references/authentication.md":"# MCP Authentication Patterns\n\nComplete guide to authentication methods for MCP servers in Claude Code plugins.\n\n## Overview\n\nMCP servers support multiple authentication methods depending on the server type and service requirements. Choose the method that best matches your use case and security requirements.\n\n## OAuth (Automatic)\n\n### How It Works\n\nClaude Code automatically handles the complete OAuth 2.0 flow for SSE and HTTP servers:\n\n1. User attempts to use MCP tool\n2. Claude Code detects authentication needed\n3. Opens browser for OAuth consent\n4. User authorizes in browser\n5. Tokens stored securely by Claude Code\n6. Automatic token refresh\n\n### Configuration\n\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\"\n }\n}\n```\n\nNo additional auth configuration needed! Claude Code handles everything.\n\n### Supported Services\n\n**Known OAuth-enabled MCP servers:**\n- Asana: `https://mcp.asana.com/sse`\n- GitHub (when available)\n- Google services (when available)\n- Custom OAuth servers\n\n### OAuth Scopes\n\nOAuth scopes are determined by the MCP server. Users see required scopes during the consent flow.\n\n**Document required scopes in your README:**\n```markdown\n## Authentication\n\nThis plugin requires the following Asana permissions:\n- Read tasks and projects\n- Create and update tasks\n- Access workspace data\n```\n\n### Token Storage\n\nTokens are stored securely by Claude Code:\n- Not accessible to plugins\n- Encrypted at rest\n- Automatic refresh\n- Cleared on sign-out\n\n### Troubleshooting OAuth\n\n**Authentication loop:**\n- Clear cached tokens (sign out and sign in)\n- Check OAuth redirect URLs\n- Verify server OAuth configuration\n\n**Scope issues:**\n- User may need to re-authorize for new scopes\n- Check server documentation for required scopes\n\n**Token expiration:**\n- Claude Code auto-refreshes\n- If refresh fails, prompts re-authentication\n\n## Token-Based Authentication\n\n### Bearer Tokens\n\nMost common for HTTP and WebSocket servers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\"\n }\n }\n}\n```\n\n**Environment variable:**\n```bash\nexport API_TOKEN=\"your-secret-token-here\"\n```\n\n### API Keys\n\nAlternative to Bearer tokens, often in custom headers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"X-API-Key\": \"${API_KEY}\",\n \"X-API-Secret\": \"${API_SECRET}\"\n }\n }\n}\n```\n\n### Custom Headers\n\nServices may use custom authentication headers.\n\n**Configuration:**\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-Auth-Token\": \"${AUTH_TOKEN}\",\n \"X-User-ID\": \"${USER_ID}\",\n \"X-Tenant-ID\": \"${TENANT_ID}\"\n }\n }\n}\n```\n\n### Documenting Token Requirements\n\nAlways document in your README:\n\n```markdown\n## Setup\n\n### Required Environment Variables\n\nSet these environment variables before using the plugin:\n\n\\`\\`\\`bash\nexport API_TOKEN=\"your-token-here\"\nexport API_SECRET=\"your-secret-here\"\n\\`\\`\\`\n\n### Obtaining Tokens\n\n1. Visit https://api.example.com/tokens\n2. Create a new API token\n3. Copy the token and secret\n4. Set environment variables as shown above\n\n### Token Permissions\n\nThe API token needs the following permissions:\n- Read access to resources\n- Write access for creating items\n- Delete access (optional, for cleanup operations)\n\\`\\`\\`\n```\n\n## Environment Variable Authentication (stdio)\n\n### Passing Credentials to Server\n\nFor stdio servers, pass credentials via environment variables:\n\n```json\n{\n \"database\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server_db\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_USER\": \"${DB_USER}\",\n \"DB_PASSWORD\": \"${DB_PASSWORD}\"\n }\n }\n}\n```\n\n### User Environment Variables\n\n```bash\n# User sets these in their shell\nexport DATABASE_URL=\"postgresql://localhost/mydb\"\nexport DB_USER=\"myuser\"\nexport DB_PASSWORD=\"mypassword\"\n```\n\n### Documentation Template\n\n```markdown\n## Database Configuration\n\nSet these environment variables:\n\n\\`\\`\\`bash\nexport DATABASE_URL=\"postgresql://host:port/database\"\nexport DB_USER=\"username\"\nexport DB_PASSWORD=\"password\"\n\\`\\`\\`\n\nOr create a `.env` file (add to `.gitignore`):\n\n\\`\\`\\`\nDATABASE_URL=postgresql://localhost:5432/mydb\nDB_USER=myuser\nDB_PASSWORD=mypassword\n\\`\\`\\`\n\nLoad with: \\`source .env\\` or \\`export $(cat .env | xargs)\\`\n\\`\\`\\`\n```\n\n## Dynamic Headers\n\n### Headers Helper Script\n\nFor tokens that change or expire, use a helper script:\n\n```json\n{\n \"api\": {\n \"type\": \"sse\",\n \"url\": \"https://api.example.com\",\n \"headersHelper\": \"${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh\"\n }\n}\n```\n\n**Script (get-headers.sh):**\n```bash\n#!/bin/bash\n# Generate dynamic authentication headers\n\n# Fetch fresh token\nTOKEN=$(get-fresh-token-from-somewhere)\n\n# Output JSON headers\ncat <___`. Use these tools in commands and agents just like built-in Claude Code tools.\n\n## Tool Naming Convention\n\n### Format\n\n```\nmcp__plugin____\n```\n\n### Examples\n\n**Asana plugin with asana server:**\n- `mcp__plugin_asana_asana__asana_create_task`\n- `mcp__plugin_asana_asana__asana_search_tasks`\n- `mcp__plugin_asana_asana__asana_get_project`\n\n**Custom plugin with database server:**\n- `mcp__plugin_myplug_database__query`\n- `mcp__plugin_myplug_database__execute`\n- `mcp__plugin_myplug_database__list_tables`\n\n### Discovering Tool Names\n\n**Use `/mcp` command:**\n```bash\n/mcp\n```\n\nThis shows:\n- All available MCP servers\n- Tools provided by each server\n- Tool schemas and descriptions\n- Full tool names for use in configuration\n\n## Using Tools in Commands\n\n### Pre-Allowing Tools\n\nSpecify MCP tools in command frontmatter:\n\n```markdown\n---\ndescription: Create a new Asana task\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\"\n]\n---\n\n# Create Task Command\n\nTo create a task:\n1. Gather task details from user\n2. Use mcp__plugin_asana_asana__asana_create_task with the details\n3. Confirm creation to user\n```\n\n### Multiple Tools\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\",\n \"mcp__plugin_asana_asana__asana_search_tasks\",\n \"mcp__plugin_asana_asana__asana_get_project\"\n]\n---\n```\n\n### Wildcard (Use Sparingly)\n\n```markdown\n---\nallowed-tools: [\"mcp__plugin_asana_asana__*\"]\n---\n```\n\n**Caution:** Only use wildcards if the command truly needs access to all tools from a server.\n\n### Tool Usage in Command Instructions\n\n**Example command:**\n```markdown\n---\ndescription: Search and create Asana tasks\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_search_tasks\",\n \"mcp__plugin_asana_asana__asana_create_task\"\n]\n---\n\n# Asana Task Management\n\n## Searching Tasks\n\nTo search for tasks:\n1. Use mcp__plugin_asana_asana__asana_search_tasks\n2. Provide search filters (assignee, project, etc.)\n3. Display results to user\n\n## Creating Tasks\n\nTo create a task:\n1. Gather task details:\n - Title (required)\n - Description\n - Project\n - Assignee\n - Due date\n2. Use mcp__plugin_asana_asana__asana_create_task\n3. Show confirmation with task link\n```\n\n## Using Tools in Agents\n\n### Agent Configuration\n\nAgents can use MCP tools autonomously without pre-allowing them:\n\n```markdown\n---\nname: asana-status-updater\ndescription: This agent should be used when the user asks to \"update Asana status\", \"generate project report\", or \"sync Asana tasks\"\nmodel: inherit\ncolor: blue\n---\n\n## Role\n\nAutonomous agent for generating Asana project status reports.\n\n## Process\n\n1. **Query tasks**: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks\n2. **Analyze progress**: Calculate completion rates and identify blockers\n3. **Generate report**: Create formatted status update\n4. **Update Asana**: Use mcp__plugin_asana_asana__asana_create_comment to post report\n\n## Available Tools\n\nThe agent has access to all Asana MCP tools without pre-approval.\n```\n\n### Agent Tool Access\n\nAgents have broader tool access than commands:\n- Can use any tool Claude determines is necessary\n- Don't need pre-allowed lists\n- Should document which tools they typically use\n\n## Tool Call Patterns\n\n### Pattern 1: Simple Tool Call\n\nSingle tool call with validation:\n\n```markdown\nSteps:\n1. Validate user provided required fields\n2. Call mcp__plugin_api_server__create_item with validated data\n3. Check for errors\n4. Display confirmation\n```\n\n### Pattern 2: Sequential Tools\n\nChain multiple tool calls:\n\n```markdown\nSteps:\n1. Search for existing items: mcp__plugin_api_server__search\n2. If not found, create new: mcp__plugin_api_server__create\n3. Add metadata: mcp__plugin_api_server__update_metadata\n4. Return final item ID\n```\n\n### Pattern 3: Batch Operations\n\nMultiple calls with same tool:\n\n```markdown\nSteps:\n1. Get list of items to process\n2. For each item:\n - Call mcp__plugin_api_server__update_item\n - Track success/failure\n3. Report results summary\n```\n\n### Pattern 4: Error Handling\n\nGraceful error handling:\n\n```markdown\nSteps:\n1. Try to call mcp__plugin_api_server__get_data\n2. If error (rate limit, network, etc.):\n - Wait and retry (max 3 attempts)\n - If still failing, inform user\n - Suggest checking configuration\n3. On success, process data\n```\n\n## Tool Parameters\n\n### Understanding Tool Schemas\n\nEach MCP tool has a schema defining its parameters. View with `/mcp`.\n\n**Example schema:**\n```json\n{\n \"name\": \"asana_create_task\",\n \"description\": \"Create a new Asana task\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Task title\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"Task description\"\n },\n \"workspace\": {\n \"type\": \"string\",\n \"description\": \"Workspace GID\"\n }\n },\n \"required\": [\"name\", \"workspace\"]\n }\n}\n```\n\n### Calling Tools with Parameters\n\nClaude automatically structures tool calls based on schema:\n\n```typescript\n// Claude generates this internally\n{\n toolName: \"mcp__plugin_asana_asana__asana_create_task\",\n input: {\n name: \"Review PR #123\",\n notes: \"Code review for new feature\",\n workspace: \"12345\",\n assignee: \"67890\",\n due_on: \"2025-01-15\"\n }\n}\n```\n\n### Parameter Validation\n\n**In commands, validate before calling:**\n\n```markdown\nSteps:\n1. Check required parameters:\n - Title is not empty\n - Workspace ID is provided\n - Due date is valid format (YYYY-MM-DD)\n2. If validation fails, ask user to provide missing data\n3. If validation passes, call MCP tool\n4. Handle tool errors gracefully\n```\n\n## Response Handling\n\n### Success Responses\n\n```markdown\nSteps:\n1. Call MCP tool\n2. On success:\n - Extract relevant data from response\n - Format for user display\n - Provide confirmation message\n - Include relevant links or IDs\n```\n\n### Error Responses\n\n```markdown\nSteps:\n1. Call MCP tool\n2. On error:\n - Check error type (auth, rate limit, validation, etc.)\n - Provide helpful error message\n - Suggest remediation steps\n - Don't expose internal error details to user\n```\n\n### Partial Success\n\n```markdown\nSteps:\n1. Batch operation with multiple MCP calls\n2. Track successes and failures separately\n3. Report summary:\n - \"Successfully processed 8 of 10 items\"\n - \"Failed items: [item1, item2] due to [reason]\"\n - Suggest retry or manual intervention\n```\n\n## Performance Optimization\n\n### Batching Requests\n\n**Good: Single query with filters**\n```markdown\nSteps:\n1. Call mcp__plugin_api_server__search with filters:\n - project_id: \"123\"\n - status: \"active\"\n - limit: 100\n2. Process all results\n```\n\n**Avoid: Many individual queries**\n```markdown\nSteps:\n1. For each item ID:\n - Call mcp__plugin_api_server__get_item\n - Process item\n```\n\n### Caching Results\n\n```markdown\nSteps:\n1. Call expensive MCP operation: mcp__plugin_api_server__analyze\n2. Store results in variable for reuse\n3. Use cached results for subsequent operations\n4. Only re-fetch if data changes\n```\n\n### Parallel Tool Calls\n\nWhen tools don't depend on each other, call in parallel:\n\n```markdown\nSteps:\n1. Make parallel calls (Claude handles this automatically):\n - mcp__plugin_api_server__get_project\n - mcp__plugin_api_server__get_users\n - mcp__plugin_api_server__get_tags\n2. Wait for all to complete\n3. Combine results\n```\n\n## Integration Best Practices\n\n### User Experience\n\n**Provide feedback:**\n```markdown\nSteps:\n1. Inform user: \"Searching Asana tasks...\"\n2. Call mcp__plugin_asana_asana__asana_search_tasks\n3. Show progress: \"Found 15 tasks, analyzing...\"\n4. Present results\n```\n\n**Handle long operations:**\n```markdown\nSteps:\n1. Warn user: \"This may take a minute...\"\n2. Break into smaller steps with updates\n3. Show incremental progress\n4. Final summary when complete\n```\n\n### Error Messages\n\n**Good error messages:**\n```\n❌ \"Could not create task. Please check:\n 1. You're logged into Asana\n 2. You have access to workspace 'Engineering'\n 3. The project 'Q1 Goals' exists\"\n```\n\n**Poor error messages:**\n```\n❌ \"Error: MCP tool returned 403\"\n```\n\n### Documentation\n\n**Document MCP tool usage in command:**\n```markdown\n## MCP Tools Used\n\nThis command uses the following Asana MCP tools:\n- **asana_search_tasks**: Search for tasks matching criteria\n- **asana_create_task**: Create new task with details\n- **asana_update_task**: Update existing task properties\n\nEnsure you're authenticated to Asana before running this command.\n```\n\n## Testing Tool Usage\n\n### Local Testing\n\n1. **Configure MCP server** in `.mcp.json`\n2. **Install plugin locally** in `.claude-plugin/`\n3. **Verify tools available** with `/mcp`\n4. **Test command** that uses tools\n5. **Check debug output**: `claude --debug`\n\n### Test Scenarios\n\n**Test successful calls:**\n```markdown\nSteps:\n1. Create test data in external service\n2. Run command that queries this data\n3. Verify correct results returned\n```\n\n**Test error cases:**\n```markdown\nSteps:\n1. Test with missing authentication\n2. Test with invalid parameters\n3. Test with non-existent resources\n4. Verify graceful error handling\n```\n\n**Test edge cases:**\n```markdown\nSteps:\n1. Test with empty results\n2. Test with maximum results\n3. Test with special characters\n4. Test with concurrent access\n```\n\n## Common Patterns\n\n### Pattern: CRUD Operations\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_api_server__create_item\",\n \"mcp__plugin_api_server__read_item\",\n \"mcp__plugin_api_server__update_item\",\n \"mcp__plugin_api_server__delete_item\"\n]\n---\n\n# Item Management\n\n## Create\nUse create_item with required fields...\n\n## Read\nUse read_item with item ID...\n\n## Update\nUse update_item with item ID and changes...\n\n## Delete\nUse delete_item with item ID (ask for confirmation first)...\n```\n\n### Pattern: Search and Process\n\n```markdown\nSteps:\n1. **Search**: mcp__plugin_api_server__search with filters\n2. **Filter**: Apply additional local filtering if needed\n3. **Transform**: Process each result\n4. **Present**: Format and display to user\n```\n\n### Pattern: Multi-Step Workflow\n\n```markdown\nSteps:\n1. **Setup**: Gather all required information\n2. **Validate**: Check data completeness\n3. **Execute**: Chain of MCP tool calls:\n - Create parent resource\n - Create child resources\n - Link resources together\n - Add metadata\n4. **Verify**: Confirm all steps succeeded\n5. **Report**: Provide summary to user\n```\n\n## Troubleshooting\n\n### Tools Not Available\n\n**Check:**\n- MCP server configured correctly\n- Server connected (check `/mcp`)\n- Tool names match exactly (case-sensitive)\n- Restart Claude Code after config changes\n\n### Tool Calls Failing\n\n**Check:**\n- Authentication is valid\n- Parameters match tool schema\n- Required parameters provided\n- Check `claude --debug` logs\n\n### Performance Issues\n\n**Check:**\n- Batching queries instead of individual calls\n- Caching results when appropriate\n- Not making unnecessary tool calls\n- Parallel calls when possible\n\n## Conclusion\n\nEffective MCP tool usage requires:\n1. **Understanding tool schemas** via `/mcp`\n2. **Pre-allowing tools** in commands appropriately\n3. **Handling errors gracefully**\n4. **Optimizing performance** with batching and caching\n5. **Providing good UX** with feedback and clear errors\n6. **Testing thoroughly** before deployment\n\nFollow these patterns for robust MCP tool integration in your plugin commands and agents.\n","plugins/plugin-dev/skills/plugin-settings/SKILL.md":"---\nname: Plugin Settings\ndescription: This skill should be used when the user asks about \"plugin settings\", \"store plugin configuration\", \"user-configurable plugin\", \".local.md files\", \"plugin state files\", \"read YAML frontmatter\", \"per-project plugin settings\", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.\nversion: 0.1.0\n---\n\n# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store user-configurable settings and state in `.claude/plugin-name.local.md` files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.\n\n**Key characteristics:**\n- File location: `.claude/plugin-name.local.md` in project root\n- Structure: YAML frontmatter + markdown body\n- Purpose: Per-project plugin configuration and state\n- Usage: Read from hooks, commands, and agents\n- Lifecycle: User-managed (not in git, should be in `.gitignore`)\n\n## File Structure\n\n### Basic Template\n\n```markdown\n---\nenabled: true\nsetting1: value1\nsetting2: value2\nnumeric_setting: 42\nlist_setting: [\"item1\", \"item2\"]\n---\n\n# Additional Context\n\nThis markdown body can contain:\n- Task descriptions\n- Additional instructions\n- Prompts to feed back to Claude\n- Documentation or notes\n```\n\n### Example: Plugin State File\n\n**.claude/my-plugin.local.md:**\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_retries: 3\nnotification_level: info\ncoordinator_session: team-leader\n---\n\n# Plugin Configuration\n\nThis plugin is configured for standard validation mode.\nContact @team-lead with questions.\n```\n\n## Reading Settings Files\n\n### From Hooks (Bash Scripts)\n\n**Pattern: Check existence and parse frontmatter**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Define state file path\nSTATE_FILE=\".claude/my-plugin.local.md\"\n\n# Quick exit if file doesn't exist\nif [[ ! -f \"$STATE_FILE\" ]]; then\n exit 0 # Plugin not configured, skip\nfi\n\n# Parse YAML frontmatter (between --- markers)\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$STATE_FILE\")\n\n# Extract individual fields\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0 # Disabled\nfi\n\n# Use configuration in hook logic\nif [[ \"$STRICT_MODE\" == \"true\" ]]; then\n # Apply strict validation\n # ...\nfi\n```\n\nSee `examples/read-settings-hook.sh` for complete working example.\n\n### From Commands\n\nCommands can read settings files to customize behavior:\n\n```markdown\n---\ndescription: Process data with plugin\nallowed-tools: [\"Read\", \"Bash\"]\n---\n\n# Process Command\n\nSteps:\n1. Check if settings exist at `.claude/my-plugin.local.md`\n2. Read configuration using Read tool\n3. Parse YAML frontmatter to extract settings\n4. Apply settings to processing logic\n5. Execute with configured behavior\n```\n\n### From Agents\n\nAgents can reference settings in their instructions:\n\n```markdown\n---\nname: configured-agent\ndescription: Agent that adapts to project settings\n---\n\nCheck for plugin settings at `.claude/my-plugin.local.md`.\nIf present, parse YAML frontmatter and adapt behavior according to:\n- enabled: Whether plugin is active\n- mode: Processing mode (strict, standard, lenient)\n- Additional configuration fields\n```\n\n## Parsing Techniques\n\n### Extract Frontmatter\n\n```bash\n# Extract everything between --- markers\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n```\n\n### Read Individual Fields\n\n**String fields:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n# Compare: if [[ \"$ENABLED\" == \"true\" ]]; then\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n# Use: if [[ $MAX -gt 100 ]]; then\n```\n\n### Read Markdown Body\n\nExtract content after second `---`:\n\n```bash\n# Get everything after closing ---\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n## Common Patterns\n\n### Pattern 1: Temporarily Active Hooks\n\nUse settings file to control hook activation:\n\n```bash\n#!/bin/bash\nSTATE_FILE=\".claude/security-scan.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Read enabled flag\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0 # Disabled\nfi\n\n# Run hook logic\n# ...\n```\n\n**Use case:** Enable/disable hooks without editing hooks.json (requires restart).\n\n### Pattern 2: Agent State Management\n\nStore agent-specific state and configuration:\n\n**.claude/multi-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-agent\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\n---\n\n# Task Assignment\n\nImplement JWT authentication for the API.\n\n**Success Criteria:**\n- Authentication endpoints created\n- Tests passing\n- PR created and CI green\n```\n\nRead from hooks to coordinate agents:\n\n```bash\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's/agent_name: *//')\nCOORDINATOR=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')\n\n# Send notification to coordinator\ntmux send-keys -t \"$COORDINATOR\" \"Agent $AGENT_NAME completed task\" Enter\n```\n\n### Pattern 3: Configuration-Driven Behavior\n\n**.claude/my-plugin.local.md:**\n```markdown\n---\nvalidation_level: strict\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\n---\n\n# Validation Configuration\n\nStrict mode enabled for this project.\nAll writes validated against security policies.\n```\n\nUse in hooks or commands:\n\n```bash\nLEVEL=$(echo \"$FRONTMATTER\" | grep '^validation_level:' | sed 's/validation_level: *//')\n\ncase \"$LEVEL\" in\n strict)\n # Apply strict validation\n ;;\n standard)\n # Apply standard validation\n ;;\n lenient)\n # Apply lenient validation\n ;;\nesac\n```\n\n## Creating Settings Files\n\n### From Commands\n\nCommands can create settings files:\n\n```markdown\n# Setup Command\n\nSteps:\n1. Ask user for configuration preferences\n2. Create `.claude/my-plugin.local.md` with YAML frontmatter\n3. Set appropriate values based on user input\n4. Inform user that settings are saved\n5. Remind user to restart Claude Code for hooks to recognize changes\n```\n\n### Template Generation\n\nProvide template in plugin README:\n\n```markdown\n## Configuration\n\nCreate `.claude/my-plugin.local.md` in your project:\n\n\\`\\`\\`markdown\n---\nenabled: true\nmode: standard\nmax_retries: 3\n---\n\n# Plugin Configuration\n\nYour settings are active.\n\\`\\`\\`\n\nAfter creating or editing, restart Claude Code for changes to take effect.\n```\n\n## Best Practices\n\n### File Naming\n\n✅ **DO:**\n- Use `.claude/plugin-name.local.md` format\n- Match plugin name exactly\n- Use `.local.md` suffix for user-local files\n\n❌ **DON'T:**\n- Use different directory (not `.claude/`)\n- Use inconsistent naming\n- Use `.md` without `.local` (might be committed)\n\n### Gitignore\n\nAlways add to `.gitignore`:\n\n```gitignore\n.claude/*.local.md\n.claude/*.local.json\n```\n\nDocument this in plugin README.\n\n### Defaults\n\nProvide sensible defaults when settings file doesn't exist:\n\n```bash\nif [[ ! -f \"$STATE_FILE\" ]]; then\n # Use defaults\n ENABLED=true\n MODE=standard\nelse\n # Read from file\n # ...\nfi\n```\n\n### Validation\n\nValidate settings values:\n\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n\n# Validate numeric range\nif ! [[ \"$MAX\" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then\n echo \"⚠️ Invalid max_value in settings (must be 1-100)\" >&2\n MAX=10 # Use default\nfi\n```\n\n### Restart Requirement\n\n**Important:** Settings changes require Claude Code restart.\n\nDocument in your README:\n\n```markdown\n## Changing Settings\n\nAfter editing `.claude/my-plugin.local.md`:\n1. Save the file\n2. Exit Claude Code\n3. Restart: `claude` or `cc`\n4. New settings will be loaded\n```\n\nHooks cannot be hot-swapped within a session.\n\n## Security Considerations\n\n### Sanitize User Input\n\nWhen writing settings files from user input:\n\n```bash\n# Escape quotes in user input\nSAFE_VALUE=$(echo \"$USER_INPUT\" | sed 's/\"/\\\\\"/g')\n\n# Write to file\ncat > \"$STATE_FILE\" <&2\n exit 2\nfi\n```\n\n### Permissions\n\nSettings files should be:\n- Readable by user only (`chmod 600`)\n- Not committed to git\n- Not shared between users\n\n## Real-World Examples\n\n### multi-agent-swarm Plugin\n\n**.claude/multi-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: Use JWT tokens, not sessions\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\nCoordinate with auth-agent on shared types.\n```\n\n**Hook usage (agent-stop-notification.sh):**\n- Checks if file exists (line 15-18: quick exit if not)\n- Parses frontmatter to get coordinator_session, agent_name, enabled\n- Sends notifications to coordinator if enabled\n- Allows quick activation/deactivation via `enabled: true/false`\n\n### ralph-wiggum Plugin\n\n**.claude/ralph-loop.local.md:**\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\n```\n\n**Hook usage (stop-hook.sh):**\n- Checks if file exists (line 15-18: quick exit if not active)\n- Reads iteration count and max_iterations\n- Extracts completion_promise for loop termination\n- Reads body as the prompt to feed back\n- Updates iteration count on each loop\n\n## Quick Reference\n\n### File Location\n\n```\nproject-root/\n└── .claude/\n └── plugin-name.local.md\n```\n\n### Frontmatter Parsing\n\n```bash\n# Extract frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Read field\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n### Body Parsing\n\n```bash\n# Extract body (after second ---)\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n### Quick Exit Pattern\n\n```bash\nif [[ ! -f \".claude/my-plugin.local.md\" ]]; then\n exit 0 # Not configured\nfi\n```\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed implementation patterns:\n\n- **`references/parsing-techniques.md`** - Complete guide to parsing YAML frontmatter and markdown bodies\n- **`references/real-world-examples.md`** - Deep dive into multi-agent-swarm and ralph-wiggum implementations\n\n### Example Files\n\nWorking examples in `examples/`:\n\n- **`read-settings-hook.sh`** - Hook that reads and uses settings\n- **`create-settings-command.md`** - Command that creates settings file\n- **`example-settings.md`** - Template settings file\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-settings.sh`** - Validate settings file structure\n- **`parse-frontmatter.sh`** - Extract frontmatter fields\n\n## Implementation Workflow\n\nTo add settings to a plugin:\n\n1. Design settings schema (which fields, types, defaults)\n2. Create template file in plugin documentation\n3. Add gitignore entry for `.claude/*.local.md`\n4. Implement settings parsing in hooks/commands\n5. Use quick-exit pattern (check file exists, check enabled field)\n6. Document settings in plugin README with template\n7. Remind users that changes require Claude Code restart\n\nFocus on keeping settings simple and providing good defaults when settings file doesn't exist.\n","plugins/plugin-dev/skills/plugin-settings/examples/create-settings-command.md":"---\ndescription: \"Create plugin settings file with user preferences\"\nallowed-tools: [\"Write\", \"AskUserQuestion\"]\n---\n\n# Create Plugin Settings\n\nThis command helps users create a `.claude/my-plugin.local.md` settings file.\n\n## Steps\n\n### Step 1: Ask User for Preferences\n\nUse AskUserQuestion to gather configuration:\n\n```json\n{\n \"questions\": [\n {\n \"question\": \"Enable plugin for this project?\",\n \"header\": \"Enable Plugin\",\n \"multiSelect\": false,\n \"options\": [\n {\n \"label\": \"Yes\",\n \"description\": \"Plugin will be active\"\n },\n {\n \"label\": \"No\",\n \"description\": \"Plugin will be disabled\"\n }\n ]\n },\n {\n \"question\": \"Validation mode?\",\n \"header\": \"Mode\",\n \"multiSelect\": false,\n \"options\": [\n {\n \"label\": \"Strict\",\n \"description\": \"Maximum validation and security checks\"\n },\n {\n \"label\": \"Standard\",\n \"description\": \"Balanced validation (recommended)\"\n },\n {\n \"label\": \"Lenient\",\n \"description\": \"Minimal validation only\"\n }\n ]\n }\n ]\n}\n```\n\n### Step 2: Parse Answers\n\nExtract answers from AskUserQuestion result:\n\n- answers[\"0\"]: enabled (Yes/No)\n- answers[\"1\"]: mode (Strict/Standard/Lenient)\n\n### Step 3: Create Settings File\n\nUse Write tool to create `.claude/my-plugin.local.md`:\n\n```markdown\n---\nenabled: \nvalidation_mode: \nmax_file_size: 1000000\nnotify_on_errors: true\n---\n\n# Plugin Configuration\n\nYour plugin is configured with validation mode.\n\nTo modify settings, edit this file and restart Claude Code.\n```\n\n### Step 4: Inform User\n\nTell the user:\n- Settings file created at `.claude/my-plugin.local.md`\n- Current configuration summary\n- How to edit manually if needed\n- Reminder: Restart Claude Code for changes to take effect\n- Settings file is gitignored (won't be committed)\n\n## Implementation Notes\n\nAlways validate user input before writing:\n- Check mode is valid\n- Validate numeric fields are numbers\n- Ensure paths don't have traversal attempts\n- Sanitize any free-text fields\n","plugins/plugin-dev/skills/plugin-settings/examples/example-settings.md":"# Example Plugin Settings File\n\n## Template: Basic Configuration\n\n**.claude/my-plugin.local.md:**\n\n```markdown\n---\nenabled: true\nmode: standard\n---\n\n# My Plugin Configuration\n\nPlugin is active in standard mode.\n```\n\n## Template: Advanced Configuration\n\n**.claude/my-plugin.local.md:**\n\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\nnotification_level: info\nretry_attempts: 3\ntimeout_seconds: 60\ncustom_path: \"/path/to/data\"\n---\n\n# My Plugin Advanced Configuration\n\nThis project uses custom plugin configuration with:\n- Standard validation mode\n- 1MB file size limit\n- JavaScript/TypeScript files allowed\n- Info-level logging\n- 3 retry attempts\n\n## Additional Notes\n\nContact @team-lead with questions about this configuration.\n```\n\n## Template: Agent State File\n\n**.claude/multi-agent-swarm.local.md:**\n\n```markdown\n---\nagent_name: database-implementation\ntask_number: 4.2\npr_number: 5678\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.5\", \"Task 4.1\"]\nadditional_instructions: \"Use PostgreSQL, not MySQL\"\n---\n\n# Task Assignment: Database Schema Implementation\n\nImplement the database schema for the new features module.\n\n## Requirements\n\n- Create migration files\n- Add indexes for performance\n- Write tests for constraints\n- Document schema in README\n\n## Success Criteria\n\n- Migrations run successfully\n- All tests pass\n- PR created with CI green\n- Schema documented\n\n## Coordination\n\nDepends on:\n- Task 3.5: API endpoint definitions\n- Task 4.1: Data model design\n\nReport status to coordinator session 'team-leader'.\n```\n\n## Template: Feature Flag Pattern\n\n**.claude/experimental-features.local.md:**\n\n```markdown\n---\nenabled: true\nfeatures:\n - ai_suggestions\n - auto_formatting\n - advanced_refactoring\nexperimental_mode: false\n---\n\n# Experimental Features Configuration\n\nCurrent enabled features:\n- AI-powered code suggestions\n- Automatic code formatting\n- Advanced refactoring tools\n\nExperimental mode is OFF (stable features only).\n```\n\n## Usage in Hooks\n\nThese templates can be read by hooks:\n\n```bash\n# Check if plugin is configured\nif [[ ! -f \".claude/my-plugin.local.md\" ]]; then\n exit 0 # Not configured, skip hook\nfi\n\n# Read settings\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \".claude/my-plugin.local.md\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Apply settings\nif [[ \"$ENABLED\" == \"true\" ]]; then\n # Hook is active\n # ...\nfi\n```\n\n## Gitignore\n\nAlways add to project `.gitignore`:\n\n```gitignore\n# Plugin settings (user-local, not committed)\n.claude/*.local.md\n.claude/*.local.json\n```\n\n## Editing Settings\n\nUsers can edit settings files manually:\n\n```bash\n# Edit settings\nvim .claude/my-plugin.local.md\n\n# Changes take effect after restart\nexit # Exit Claude Code\nclaude # Restart\n```\n\nChanges require Claude Code restart - hooks can't be hot-swapped.\n","plugins/plugin-dev/skills/plugin-settings/references/parsing-techniques.md":"# Settings File Parsing Techniques\n\nComplete guide to parsing `.claude/plugin-name.local.md` files in bash scripts.\n\n## File Structure\n\nSettings files use markdown with YAML frontmatter:\n\n```markdown\n---\nfield1: value1\nfield2: \"value with spaces\"\nnumeric_field: 42\nboolean_field: true\nlist_field: [\"item1\", \"item2\", \"item3\"]\n---\n\n# Markdown Content\n\nThis body content can be extracted separately.\nIt's useful for prompts, documentation, or additional context.\n```\n\n## Parsing Frontmatter\n\n### Extract Frontmatter Block\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\n\n# Extract everything between --- markers (excluding the markers themselves)\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n```\n\n**How it works:**\n- `sed -n` - Suppress automatic printing\n- `/^---$/,/^---$/` - Range from first `---` to second `---`\n- `{ /^---$/d; p; }` - Delete the `---` lines, print everything else\n\n### Extract Individual Fields\n\n**String fields:**\n```bash\n# Simple value\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//')\n\n# Quoted value (removes surrounding quotes)\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Use in condition\nif [[ \"$ENABLED\" == \"true\" ]]; then\n # Enabled\nfi\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n\n# Validate it's a number\nif [[ \"$MAX\" =~ ^[0-9]+$ ]]; then\n # Use in numeric comparison\n if [[ $MAX -gt 100 ]]; then\n # Too large\n fi\nfi\n```\n\n**List fields (simple):**\n```bash\n# YAML: list: [\"item1\", \"item2\", \"item3\"]\nLIST=$(echo \"$FRONTMATTER\" | grep '^list:' | sed 's/list: *//')\n# Result: [\"item1\", \"item2\", \"item3\"]\n\n# For simple checks:\nif [[ \"$LIST\" == *\"item1\"* ]]; then\n # List contains item1\nfi\n```\n\n**List fields (proper parsing with jq):**\n```bash\n# For proper list handling, use yq or convert to JSON\n# This requires yq to be installed (brew install yq)\n\n# Extract list as JSON array\nLIST=$(echo \"$FRONTMATTER\" | yq -o json '.list' 2>/dev/null)\n\n# Iterate over items\necho \"$LIST\" | jq -r '.[]' | while read -r item; do\n echo \"Processing: $item\"\ndone\n```\n\n## Parsing Markdown Body\n\n### Extract Body Content\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\n\n# Extract everything after the closing ---\n# Counts --- markers: first is opening, second is closing, everything after is body\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n**How it works:**\n- `/^---$/` - Match `---` lines\n- `{i++; next}` - Increment counter and skip the `---` line\n- `i>=2` - Print all lines after second `---`\n\n**Handles edge case:** If `---` appears in the markdown body, it still works because we only count the first two `---` at the start.\n\n### Use Body as Prompt\n\n```bash\n# Extract body\nPROMPT=$(awk '/^---$/{i++; next} i>=2' \"$RALPH_STATE_FILE\")\n\n# Feed back to Claude\necho '{\"decision\": \"block\", \"reason\": \"'\"$PROMPT\"'\"}' | jq .\n```\n\n**Important:** Use `jq -n --arg` for safer JSON construction with user content:\n\n```bash\nPROMPT=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n\n# Safe JSON construction\njq -n --arg prompt \"$PROMPT\" '{\n \"decision\": \"block\",\n \"reason\": $prompt\n}'\n```\n\n## Common Parsing Patterns\n\n### Pattern: Field with Default\n\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Use default if empty\nif [[ -z \"$VALUE\" ]]; then\n VALUE=\"default_value\"\nfi\n```\n\n### Pattern: Optional Field\n\n```bash\nOPTIONAL=$(echo \"$FRONTMATTER\" | grep '^optional_field:' | sed 's/optional_field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Only use if present\nif [[ -n \"$OPTIONAL\" ]] && [[ \"$OPTIONAL\" != \"null\" ]]; then\n # Field is set, use it\n echo \"Optional field: $OPTIONAL\"\nfi\n```\n\n### Pattern: Multiple Fields at Once\n\n```bash\n# Parse all fields in one pass\nwhile IFS=': ' read -r key value; do\n # Remove quotes if present\n value=$(echo \"$value\" | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n case \"$key\" in\n enabled)\n ENABLED=\"$value\"\n ;;\n mode)\n MODE=\"$value\"\n ;;\n max_size)\n MAX_SIZE=\"$value\"\n ;;\n esac\ndone <<< \"$FRONTMATTER\"\n```\n\n## Updating Settings Files\n\n### Atomic Updates\n\nAlways use temp file + atomic move to prevent corruption:\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\nNEW_VALUE=\"updated_value\"\n\n# Create temp file\nTEMP_FILE=\"${FILE}.tmp.$$\"\n\n# Update field using sed\nsed \"s/^field_name: .*/field_name: $NEW_VALUE/\" \"$FILE\" > \"$TEMP_FILE\"\n\n# Atomic replace\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### Update Single Field\n\n```bash\n# Increment iteration counter\nCURRENT=$(echo \"$FRONTMATTER\" | grep '^iteration:' | sed 's/iteration: *//')\nNEXT=$((CURRENT + 1))\n\n# Update file\nTEMP_FILE=\"${FILE}.tmp.$$\"\nsed \"s/^iteration: .*/iteration: $NEXT/\" \"$FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### Update Multiple Fields\n\n```bash\n# Update several fields at once\nTEMP_FILE=\"${FILE}.tmp.$$\"\n\nsed -e \"s/^iteration: .*/iteration: $NEXT_ITERATION/\" \\\n -e \"s/^pr_number: .*/pr_number: $PR_NUMBER/\" \\\n -e \"s/^status: .*/status: $NEW_STATUS/\" \\\n \"$FILE\" > \"$TEMP_FILE\"\n\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n## Validation Techniques\n\n### Validate File Exists and Is Readable\n\n```bash\nFILE=\".claude/my-plugin.local.md\"\n\nif [[ ! -f \"$FILE\" ]]; then\n echo \"Settings file not found\" >&2\n exit 1\nfi\n\nif [[ ! -r \"$FILE\" ]]; then\n echo \"Settings file not readable\" >&2\n exit 1\nfi\n```\n\n### Validate Frontmatter Structure\n\n```bash\n# Count --- markers (should be exactly 2 at start)\nMARKER_COUNT=$(grep -c '^---$' \"$FILE\" 2>/dev/null || echo \"0\")\n\nif [[ $MARKER_COUNT -lt 2 ]]; then\n echo \"Invalid settings file: missing frontmatter markers\" >&2\n exit 1\nfi\n```\n\n### Validate Field Values\n\n```bash\nMODE=$(echo \"$FRONTMATTER\" | grep '^mode:' | sed 's/mode: *//')\n\ncase \"$MODE\" in\n strict|standard|lenient)\n # Valid mode\n ;;\n *)\n echo \"Invalid mode: $MODE (must be strict, standard, or lenient)\" >&2\n exit 1\n ;;\nesac\n```\n\n### Validate Numeric Ranges\n\n```bash\nMAX_SIZE=$(echo \"$FRONTMATTER\" | grep '^max_size:' | sed 's/max_size: *//')\n\nif ! [[ \"$MAX_SIZE\" =~ ^[0-9]+$ ]]; then\n echo \"max_size must be a number\" >&2\n exit 1\nfi\n\nif [[ $MAX_SIZE -lt 1 ]] || [[ $MAX_SIZE -gt 10000000 ]]; then\n echo \"max_size out of range (1-10000000)\" >&2\n exit 1\nfi\n```\n\n## Edge Cases and Gotchas\n\n### Quotes in Values\n\nYAML allows both quoted and unquoted strings:\n\n```yaml\n# These are equivalent:\nfield1: value\nfield2: \"value\"\nfield3: 'value'\n```\n\n**Handle both:**\n```bash\n# Remove surrounding quotes if present\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/' | sed \"s/^'\\\\(.*\\\\)'$/\\\\1/\")\n```\n\n### --- in Markdown Body\n\nIf the markdown body contains `---`, the parsing still works because we only match the first two:\n\n```markdown\n---\nfield: value\n---\n\n# Body\n\nHere's a separator:\n---\n\nMore content after the separator.\n```\n\nThe `awk '/^---$/{i++; next} i>=2'` pattern handles this correctly.\n\n### Empty Values\n\nHandle missing or empty fields:\n\n```yaml\nfield1:\nfield2: \"\"\nfield3: null\n```\n\n**Parsing:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field1:' | sed 's/field1: *//')\n# VALUE will be empty string\n\n# Check for empty/null\nif [[ -z \"$VALUE\" ]] || [[ \"$VALUE\" == \"null\" ]]; then\n VALUE=\"default\"\nfi\n```\n\n### Special Characters\n\nValues with special characters need careful handling:\n\n```yaml\nmessage: \"Error: Something went wrong!\"\npath: \"/path/with spaces/file.txt\"\nregex: \"^[a-zA-Z0-9_]+$\"\n```\n\n**Safe parsing:**\n```bash\n# Always quote variables when using\nMESSAGE=$(echo \"$FRONTMATTER\" | grep '^message:' | sed 's/message: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\necho \"Message: $MESSAGE\" # Quoted!\n```\n\n## Performance Optimization\n\n### Cache Parsed Values\n\nIf reading settings multiple times:\n\n```bash\n# Parse once\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Extract multiple fields from cached frontmatter\nFIELD1=$(echo \"$FRONTMATTER\" | grep '^field1:' | sed 's/field1: *//')\nFIELD2=$(echo \"$FRONTMATTER\" | grep '^field2:' | sed 's/field2: *//')\nFIELD3=$(echo \"$FRONTMATTER\" | grep '^field3:' | sed 's/field3: *//')\n```\n\n**Don't:** Re-parse file for each field.\n\n### Lazy Loading\n\nOnly parse settings when needed:\n\n```bash\n#!/bin/bash\ninput=$(cat)\n\n# Quick checks first (no file I/O)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\nif [[ \"$tool_name\" != \"Write\" ]]; then\n exit 0 # Not a write operation, skip\nfi\n\n# Only now check settings file\nif [[ -f \".claude/my-plugin.local.md\" ]]; then\n # Parse settings\n # ...\nfi\n```\n\n## Debugging\n\n### Print Parsed Values\n\n```bash\n#!/bin/bash\nset -x # Enable debug tracing\n\nFILE=\".claude/my-plugin.local.md\"\n\nif [[ -f \"$FILE\" ]]; then\n echo \"Settings file found\" >&2\n\n FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n echo \"Frontmatter:\" >&2\n echo \"$FRONTMATTER\" >&2\n\n ENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n echo \"Enabled: $ENABLED\" >&2\nfi\n```\n\n### Validate Parsing\n\n```bash\n# Show what was parsed\necho \"Parsed values:\" >&2\necho \" enabled: $ENABLED\" >&2\necho \" mode: $MODE\" >&2\necho \" max_size: $MAX_SIZE\" >&2\n\n# Verify expected values\nif [[ \"$ENABLED\" != \"true\" ]] && [[ \"$ENABLED\" != \"false\" ]]; then\n echo \"⚠️ Unexpected enabled value: $ENABLED\" >&2\nfi\n```\n\n## Alternative: Using yq\n\nFor complex YAML, consider using `yq`:\n\n```bash\n# Install: brew install yq\n\n# Parse YAML properly\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Extract fields with yq\nENABLED=$(echo \"$FRONTMATTER\" | yq '.enabled')\nMODE=$(echo \"$FRONTMATTER\" | yq '.mode')\nLIST=$(echo \"$FRONTMATTER\" | yq -o json '.list_field')\n\n# Iterate list properly\necho \"$LIST\" | jq -r '.[]' | while read -r item; do\n echo \"Item: $item\"\ndone\n```\n\n**Pros:**\n- Proper YAML parsing\n- Handles complex structures\n- Better list/object support\n\n**Cons:**\n- Requires yq installation\n- Additional dependency\n- May not be available on all systems\n\n**Recommendation:** Use sed/grep for simple fields, yq for complex structures.\n\n## Complete Example\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Configuration\nSETTINGS_FILE=\".claude/my-plugin.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$SETTINGS_FILE\" ]]; then\n # Use defaults\n ENABLED=true\n MODE=standard\n MAX_SIZE=1000000\nelse\n # Parse frontmatter\n FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$SETTINGS_FILE\")\n\n # Extract fields with defaults\n ENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n ENABLED=${ENABLED:-true}\n\n MODE=$(echo \"$FRONTMATTER\" | grep '^mode:' | sed 's/mode: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n MODE=${MODE:-standard}\n\n MAX_SIZE=$(echo \"$FRONTMATTER\" | grep '^max_size:' | sed 's/max_size: *//')\n MAX_SIZE=${MAX_SIZE:-1000000}\n\n # Validate values\n if [[ \"$ENABLED\" != \"true\" ]] && [[ \"$ENABLED\" != \"false\" ]]; then\n echo \"⚠️ Invalid enabled value, using default\" >&2\n ENABLED=true\n fi\n\n if ! [[ \"$MAX_SIZE\" =~ ^[0-9]+$ ]]; then\n echo \"⚠️ Invalid max_size, using default\" >&2\n MAX_SIZE=1000000\n fi\nfi\n\n# Quick exit if disabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0\nfi\n\n# Use configuration\necho \"Configuration loaded: mode=$MODE, max_size=$MAX_SIZE\" >&2\n\n# Apply logic based on settings\ncase \"$MODE\" in\n strict)\n # Strict validation\n ;;\n standard)\n # Standard validation\n ;;\n lenient)\n # Lenient validation\n ;;\nesac\n```\n\nThis provides robust settings handling with defaults, validation, and error recovery.\n","plugins/plugin-dev/skills/plugin-settings/references/real-world-examples.md":"# Real-World Plugin Settings Examples\n\nDetailed analysis of how production plugins use the `.claude/plugin-name.local.md` pattern.\n\n## multi-agent-swarm Plugin\n\n### Settings File Structure\n\n**.claude/multi-agent-swarm.local.md:**\n\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: \"Use JWT tokens, not sessions\"\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\n\n## Requirements\n- JWT token generation and validation\n- Refresh token flow\n- Secure password hashing\n\n## Success Criteria\n- Auth endpoints implemented\n- Tests passing (100% coverage)\n- PR created and CI green\n- Documentation updated\n\n## Coordination\nDepends on Task 3.4 (user model).\nReport status to 'team-leader' session.\n```\n\n### How It's Used\n\n**File:** `hooks/agent-stop-notification.sh`\n\n**Purpose:** Send notifications to coordinator when agent becomes idle\n\n**Implementation:**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nSWARM_STATE_FILE=\".claude/multi-agent-swarm.local.md\"\n\n# Quick exit if no swarm active\nif [[ ! -f \"$SWARM_STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Parse frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$SWARM_STATE_FILE\")\n\n# Extract configuration\nCOORDINATOR_SESSION=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's/coordinator_session: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's/agent_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nTASK_NUMBER=$(echo \"$FRONTMATTER\" | grep '^task_number:' | sed 's/task_number: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nPR_NUMBER=$(echo \"$FRONTMATTER\" | grep '^pr_number:' | sed 's/pr_number: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0\nfi\n\n# Send notification to coordinator\nNOTIFICATION=\"🤖 Agent ${AGENT_NAME} (Task ${TASK_NUMBER}, PR #${PR_NUMBER}) is idle.\"\n\nif tmux has-session -t \"$COORDINATOR_SESSION\" 2>/dev/null; then\n tmux send-keys -t \"$COORDINATOR_SESSION\" \"$NOTIFICATION\" Enter\n sleep 0.5\n tmux send-keys -t \"$COORDINATOR_SESSION\" Enter\nfi\n\nexit 0\n```\n\n**Key patterns:**\n1. **Quick exit** (line 7-9): Returns immediately if file doesn't exist\n2. **Field extraction** (lines 11-17): Parses each frontmatter field\n3. **Enabled check** (lines 19-21): Respects enabled flag\n4. **Action based on settings** (lines 23-29): Uses coordinator_session to send notification\n\n### Creation\n\n**File:** `commands/launch-swarm.md`\n\nSettings files are created during swarm launch with:\n\n```bash\ncat > \"$WORKTREE_PATH/.claude/multi-agent-swarm.local.md\" < temp.md\nmv temp.md \".claude/multi-agent-swarm.local.md\"\n```\n\n## ralph-wiggum Plugin\n\n### Settings File Structure\n\n**.claude/ralph-loop.local.md:**\n\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\nstarted_at: \"2025-01-15T14:30:00Z\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\nDocument any changes needed in CLAUDE.md.\n```\n\n### How It's Used\n\n**File:** `hooks/stop-hook.sh`\n\n**Purpose:** Prevent session exit and loop Claude's output back as input\n\n**Implementation:**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nRALPH_STATE_FILE=\".claude/ralph-loop.local.md\"\n\n# Quick exit if no active loop\nif [[ ! -f \"$RALPH_STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Parse frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$RALPH_STATE_FILE\")\n\n# Extract configuration\nITERATION=$(echo \"$FRONTMATTER\" | grep '^iteration:' | sed 's/iteration: *//')\nMAX_ITERATIONS=$(echo \"$FRONTMATTER\" | grep '^max_iterations:' | sed 's/max_iterations: *//')\nCOMPLETION_PROMISE=$(echo \"$FRONTMATTER\" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Check max iterations\nif [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then\n echo \"🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached.\"\n rm \"$RALPH_STATE_FILE\"\n exit 0\nfi\n\n# Get transcript and check for completion promise\nTRANSCRIPT_PATH=$(echo \"$HOOK_INPUT\" | jq -r '.transcript_path')\nLAST_OUTPUT=$(grep '\"role\":\"assistant\"' \"$TRANSCRIPT_PATH\" | tail -1 | jq -r '.message.content | map(select(.type == \"text\")) | map(.text) | join(\"\\n\")')\n\n# Check for completion\nif [[ \"$COMPLETION_PROMISE\" != \"null\" ]] && [[ -n \"$COMPLETION_PROMISE\" ]]; then\n PROMISE_TEXT=$(echo \"$LAST_OUTPUT\" | perl -0777 -pe 's/.*?(.*?)<\\/promise>.*/$1/s; s/^\\s+|\\s+$//g')\n\n if [[ \"$PROMISE_TEXT\" = \"$COMPLETION_PROMISE\" ]]; then\n echo \"✅ Ralph loop: Detected completion\"\n rm \"$RALPH_STATE_FILE\"\n exit 0\n fi\nfi\n\n# Continue loop - increment iteration\nNEXT_ITERATION=$((ITERATION + 1))\n\n# Extract prompt from markdown body\nPROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' \"$RALPH_STATE_FILE\")\n\n# Update iteration counter\nTEMP_FILE=\"${RALPH_STATE_FILE}.tmp.$$\"\nsed \"s/^iteration: .*/iteration: $NEXT_ITERATION/\" \"$RALPH_STATE_FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$RALPH_STATE_FILE\"\n\n# Block exit and feed prompt back\njq -n \\\n --arg prompt \"$PROMPT_TEXT\" \\\n --arg msg \"🔄 Ralph iteration $NEXT_ITERATION\" \\\n '{\n \"decision\": \"block\",\n \"reason\": $prompt,\n \"systemMessage\": $msg\n }'\n\nexit 0\n```\n\n**Key patterns:**\n1. **Quick exit** (line 7-9): Skip if not active\n2. **Iteration tracking** (lines 11-20): Count and enforce max iterations\n3. **Promise detection** (lines 25-33): Check for completion signal in output\n4. **Prompt extraction** (line 38): Read markdown body as next prompt\n5. **State update** (lines 40-43): Increment iteration atomically\n6. **Loop continuation** (lines 45-53): Block exit and feed prompt back\n\n### Creation\n\n**File:** `scripts/setup-ralph-loop.sh`\n\n```bash\n#!/bin/bash\nPROMPT=\"$1\"\nMAX_ITERATIONS=\"${2:-0}\"\nCOMPLETION_PROMISE=\"${3:-}\"\n\n# Create state file\ncat > \".claude/ralph-loop.local.md\" < \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n**Why:** Prevents corruption if process is interrupted.\n\n### 4. Quote Handling\n\nBoth strip surrounding quotes from YAML values:\n\n```bash\nsed 's/^\"\\(.*\\)\"$/\\1/'\n```\n\n**Why:** YAML allows both `field: value` and `field: \"value\"`.\n\n### 5. Error Handling\n\nBoth handle missing/corrupt files gracefully:\n\n```bash\nif [[ ! -f \"$FILE\" ]]; then\n exit 0 # No error, just not configured\nfi\n\nif [[ -z \"$CRITICAL_FIELD\" ]]; then\n echo \"Settings file corrupt\" >&2\n rm \"$FILE\" # Clean up\n exit 0\nfi\n```\n\n**Why:** Fails gracefully instead of crashing.\n\n## Anti-Patterns to Avoid\n\n### ❌ Hardcoded Paths\n\n```bash\n# BAD\nFILE=\"/Users/alice/.claude/my-plugin.local.md\"\n\n# GOOD\nFILE=\".claude/my-plugin.local.md\"\n```\n\n### ❌ Unquoted Variables\n\n```bash\n# BAD\necho $VALUE\n\n# GOOD\necho \"$VALUE\"\n```\n\n### ❌ Non-Atomic Updates\n\n```bash\n# BAD: Can corrupt file if interrupted\nsed -i \"s/field: .*/field: $VALUE/\" \"$FILE\"\n\n# GOOD: Atomic\nTEMP_FILE=\"${FILE}.tmp.$$\"\nsed \"s/field: .*/field: $VALUE/\" \"$FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### ❌ No Default Values\n\n```bash\n# BAD: Fails if field missing\nif [[ $MAX -gt 100 ]]; then\n # MAX might be empty!\nfi\n\n# GOOD: Provide default\nMAX=${MAX:-10}\n```\n\n### ❌ Ignoring Edge Cases\n\n```bash\n# BAD: Assumes exactly 2 --- markers\nsed -n '/^---$/,/^---$/{ /^---$/d; p; }'\n\n# GOOD: Handles --- in body\nawk '/^---$/{i++; next} i>=2' # For body\n```\n\n## Conclusion\n\nThe `.claude/plugin-name.local.md` pattern provides:\n- Simple, human-readable configuration\n- Version-control friendly (gitignored)\n- Per-project settings\n- Easy parsing with standard bash tools\n- Supports both structured config (YAML) and freeform content (markdown)\n\nUse this pattern for any plugin that needs user-configurable behavior or state persistence.\n","plugins/plugin-dev/skills/plugin-structure/README.md":"","plugins/plugin-dev/skills/plugin-structure/SKILL.md":"---\nname: Plugin Structure\ndescription: This skill should be used when the user asks to \"create a plugin\", \"scaffold a plugin\", \"understand plugin structure\", \"organize plugin components\", \"set up plugin.json\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"add commands/agents/skills/hooks\", \"configure auto-discovery\", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.\nversion: 0.1.0\n---\n\n# Plugin Structure for Claude Code\n\n## Overview\n\nClaude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.\n\n**Key concepts:**\n- Conventional directory layout for automatic discovery\n- Manifest-driven configuration in `.claude-plugin/plugin.json`\n- Component-based organization (commands, agents, skills, hooks)\n- Portable path references using `${CLAUDE_PLUGIN_ROOT}`\n- Explicit vs. auto-discovered component loading\n\n## Directory Structure\n\nEvery Claude Code plugin follows this organizational pattern:\n\n```\nplugin-name/\n├── .claude-plugin/\n│ └── plugin.json # Required: Plugin manifest\n├── commands/ # Slash commands (.md files)\n├── agents/ # Subagent definitions (.md files)\n├── skills/ # Agent skills (subdirectories)\n│ └── skill-name/\n│ └── SKILL.md # Required for each skill\n├── hooks/\n│ └── hooks.json # Event handler configuration\n├── .mcp.json # MCP server definitions\n└── scripts/ # Helper scripts and utilities\n```\n\n**Critical rules:**\n\n1. **Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory\n2. **Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`\n3. **Optional components**: Only create directories for components the plugin actually uses\n4. **Naming convention**: Use kebab-case for all directory and file names\n\n## Plugin Manifest (plugin.json)\n\nThe manifest defines plugin metadata and configuration. Located at `.claude-plugin/plugin.json`:\n\n### Required Fields\n\n```json\n{\n \"name\": \"plugin-name\"\n}\n```\n\n**Name requirements:**\n- Use kebab-case format (lowercase with hyphens)\n- Must be unique across installed plugins\n- No spaces or special characters\n- Example: `code-review-assistant`, `test-runner`, `api-docs`\n\n### Recommended Metadata\n\n```json\n{\n \"name\": \"plugin-name\",\n \"version\": \"1.0.0\",\n \"description\": \"Brief explanation of plugin purpose\",\n \"author\": {\n \"name\": \"Author Name\",\n \"email\": \"author@example.com\",\n \"url\": \"https://example.com\"\n },\n \"homepage\": \"https://docs.example.com\",\n \"repository\": \"https://github.com/user/plugin-name\",\n \"license\": \"MIT\",\n \"keywords\": [\"testing\", \"automation\", \"ci-cd\"]\n}\n```\n\n**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)\n**Keywords**: Use for plugin discovery and categorization\n\n### Component Path Configuration\n\nSpecify custom paths for components (supplements default directories):\n\n```json\n{\n \"name\": \"plugin-name\",\n \"commands\": \"./custom-commands\",\n \"agents\": [\"./agents\", \"./specialized-agents\"],\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.\n\n**Path rules:**\n- Must be relative to plugin root\n- Must start with `./`\n- Cannot use absolute paths\n- Support arrays for multiple locations\n\n## Component Organization\n\n### Commands\n\n**Location**: `commands/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `commands/` load automatically\n\n**Example structure**:\n```\ncommands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**File format**:\n```markdown\n---\nname: command-name\ndescription: Command description\n---\n\nCommand implementation instructions...\n```\n\n**Usage**: Commands integrate as native slash commands in Claude Code\n\n### Agents\n\n**Location**: `agents/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `agents/` load automatically\n\n**Example structure**:\n```\nagents/\n├── code-reviewer.md\n├── test-generator.md\n└── refactorer.md\n```\n\n**File format**:\n```markdown\n---\ndescription: Agent role and expertise\ncapabilities:\n - Specific task 1\n - Specific task 2\n---\n\nDetailed agent instructions and knowledge...\n```\n\n**Usage**: Users can invoke agents manually, or Claude Code selects them automatically based on task context\n\n### Skills\n\n**Location**: `skills/` directory with subdirectories per skill\n**Format**: Each skill in its own directory with `SKILL.md` file\n**Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically\n\n**Example structure**:\n```\nskills/\n├── api-testing/\n│ ├── SKILL.md\n│ ├── scripts/\n│ │ └── test-runner.py\n│ └── references/\n│ └── api-spec.md\n└── database-migrations/\n ├── SKILL.md\n └── examples/\n └── migration-template.sql\n```\n\n**SKILL.md format**:\n```markdown\n---\nname: Skill Name\ndescription: When to use this skill\nversion: 1.0.0\n---\n\nSkill instructions and guidance...\n```\n\n**Supporting files**: Skills can include scripts, references, examples, or assets in subdirectories\n\n**Usage**: Claude Code autonomously activates skills based on task context matching the description\n\n### Hooks\n\n**Location**: `hooks/hooks.json` or inline in `plugin.json`\n**Format**: JSON configuration defining event handlers\n**Registration**: Hooks register automatically when plugin enables\n\n**Example structure**:\n```\nhooks/\n├── hooks.json # Hook configuration\n└── scripts/\n ├── validate.sh # Hook script\n └── check-style.sh # Hook script\n```\n\n**Configuration format**:\n```json\n{\n \"PreToolUse\": [{\n \"matcher\": \"Write|Edit\",\n \"hooks\": [{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh\",\n \"timeout\": 30\n }]\n }]\n}\n```\n\n**Available events**: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification\n\n**Usage**: Hooks execute automatically in response to Claude Code events\n\n### MCP Servers\n\n**Location**: `.mcp.json` at plugin root or inline in `plugin.json`\n**Format**: JSON configuration for MCP server definitions\n**Auto-start**: Servers start automatically when plugin enables\n\n**Example format**:\n```json\n{\n \"mcpServers\": {\n \"server-name\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/server.js\"],\n \"env\": {\n \"API_KEY\": \"${API_KEY}\"\n }\n }\n }\n}\n```\n\n**Usage**: MCP servers integrate seamlessly with Claude Code's tool system\n\n## Portable Path References\n\n### ${CLAUDE_PLUGIN_ROOT}\n\nUse `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path references:\n\n```json\n{\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh\"\n}\n```\n\n**Why it matters**: Plugins install in different locations depending on:\n- User installation method (marketplace, local, npm)\n- Operating system conventions\n- User preferences\n\n**Where to use it**:\n- Hook command paths\n- MCP server command arguments\n- Script execution references\n- Resource file paths\n\n**Never use**:\n- Hardcoded absolute paths (`/Users/name/plugins/...`)\n- Relative paths from working directory (`./scripts/...` in commands)\n- Home directory shortcuts (`~/plugins/...`)\n\n### Path Resolution Rules\n\n**In manifest JSON fields** (hooks, MCP servers):\n```json\n\"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh\"\n```\n\n**In component files** (commands, agents, skills):\n```markdown\nReference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py\n```\n\n**In executed scripts**:\n```bash\n#!/bin/bash\n# ${CLAUDE_PLUGIN_ROOT} available as environment variable\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/common.sh\"\n```\n\n## File Naming Conventions\n\n### Component Files\n\n**Commands**: Use kebab-case `.md` files\n- `code-review.md` → `/code-review`\n- `run-tests.md` → `/run-tests`\n- `api-docs.md` → `/api-docs`\n\n**Agents**: Use kebab-case `.md` files describing role\n- `test-generator.md`\n- `code-reviewer.md`\n- `performance-analyzer.md`\n\n**Skills**: Use kebab-case directory names\n- `api-testing/`\n- `database-migrations/`\n- `error-handling/`\n\n### Supporting Files\n\n**Scripts**: Use descriptive kebab-case names with appropriate extensions\n- `validate-input.sh`\n- `generate-report.py`\n- `process-data.js`\n\n**Documentation**: Use kebab-case markdown files\n- `api-reference.md`\n- `migration-guide.md`\n- `best-practices.md`\n\n**Configuration**: Use standard names\n- `hooks.json`\n- `.mcp.json`\n- `plugin.json`\n\n## Auto-Discovery Mechanism\n\nClaude Code automatically discovers and loads components:\n\n1. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables\n2. **Commands**: Scans `commands/` directory for `.md` files\n3. **Agents**: Scans `agents/` directory for `.md` files\n4. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`\n5. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest\n6. **MCP servers**: Loads configuration from `.mcp.json` or manifest\n\n**Discovery timing**:\n- Plugin installation: Components register with Claude Code\n- Plugin enable: Components become available for use\n- No restart required: Changes take effect on next Claude Code session\n\n**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories\n\n## Best Practices\n\n### Organization\n\n1. **Logical grouping**: Group related components together\n - Put test-related commands, agents, and skills together\n - Create subdirectories in `scripts/` for different purposes\n\n2. **Minimal manifest**: Keep `plugin.json` lean\n - Only specify custom paths when necessary\n - Rely on auto-discovery for standard layouts\n - Use inline configuration only for simple cases\n\n3. **Documentation**: Include README files\n - Plugin root: Overall purpose and usage\n - Component directories: Specific guidance\n - Script directories: Usage and requirements\n\n### Naming\n\n1. **Consistency**: Use consistent naming across components\n - If command is `test-runner`, name related agent `test-runner-agent`\n - Match skill directory names to their purpose\n\n2. **Clarity**: Use descriptive names that indicate purpose\n - Good: `api-integration-testing/`, `code-quality-checker.md`\n - Avoid: `utils/`, `misc.md`, `temp.sh`\n\n3. **Length**: Balance brevity with clarity\n - Commands: 2-3 words (`review-pr`, `run-ci`)\n - Agents: Describe role clearly (`code-reviewer`, `test-generator`)\n - Skills: Topic-focused (`error-handling`, `api-design`)\n\n### Portability\n\n1. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths\n2. **Test on multiple systems**: Verify on macOS, Linux, Windows\n3. **Document dependencies**: List required tools and versions\n4. **Avoid system-specific features**: Use portable bash/Python constructs\n\n### Maintenance\n\n1. **Version consistently**: Update version in plugin.json for releases\n2. **Deprecate gracefully**: Mark old components clearly before removal\n3. **Document breaking changes**: Note changes affecting existing users\n4. **Test thoroughly**: Verify all components work after changes\n\n## Common Patterns\n\n### Minimal Plugin\n\nSingle command with no dependencies:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json # Just name field\n└── commands/\n └── hello.md # Single command\n```\n\n### Full-Featured Plugin\n\nComplete plugin with all component types:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/ # User-facing commands\n├── agents/ # Specialized subagents\n├── skills/ # Auto-activating skills\n├── hooks/ # Event handlers\n│ ├── hooks.json\n│ └── scripts/\n├── .mcp.json # External integrations\n└── scripts/ # Shared utilities\n```\n\n### Skill-Focused Plugin\n\nPlugin providing only skills:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n└── skills/\n ├── skill-one/\n │ └── SKILL.md\n └── skill-two/\n └── SKILL.md\n```\n\n## Troubleshooting\n\n**Component not loading**:\n- Verify file is in correct directory with correct extension\n- Check YAML frontmatter syntax (commands, agents, skills)\n- Ensure skill has `SKILL.md` (not `README.md` or other name)\n- Confirm plugin is enabled in Claude Code settings\n\n**Path resolution errors**:\n- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`\n- Verify paths are relative and start with `./` in manifest\n- Check that referenced files exist at specified paths\n- Test with `echo $CLAUDE_PLUGIN_ROOT` in hook scripts\n\n**Auto-discovery not working**:\n- Confirm directories are at plugin root (not in `.claude-plugin/`)\n- Check file naming follows conventions (kebab-case, correct extensions)\n- Verify custom paths in manifest are correct\n- Restart Claude Code to reload plugin configuration\n\n**Conflicts between plugins**:\n- Use unique, descriptive component names\n- Namespace commands with plugin name if needed\n- Document potential conflicts in plugin README\n- Consider command prefixes for related functionality\n\n---\n\nFor detailed examples and advanced patterns, see files in `references/` and `examples/` directories.\n","plugins/plugin-dev/skills/plugin-structure/examples/advanced-plugin.md":"# Advanced Plugin Example\n\nA complex, enterprise-grade plugin with MCP integration and advanced organization.\n\n## Directory Structure\n\n```\nenterprise-devops/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n│ ├── ci/\n│ │ ├── build.md\n│ │ ├── test.md\n│ │ └── deploy.md\n│ ├── monitoring/\n│ │ ├── status.md\n│ │ └── logs.md\n│ └── admin/\n│ ├── configure.md\n│ └── manage.md\n├── agents/\n│ ├── orchestration/\n│ │ ├── deployment-orchestrator.md\n│ │ └── rollback-manager.md\n│ └── specialized/\n│ ├── kubernetes-expert.md\n│ ├── terraform-expert.md\n│ └── security-auditor.md\n├── skills/\n│ ├── kubernetes-ops/\n│ │ ├── SKILL.md\n│ │ ├── references/\n│ │ │ ├── deployment-patterns.md\n│ │ │ ├── troubleshooting.md\n│ │ │ └── security.md\n│ │ ├── examples/\n│ │ │ ├── basic-deployment.yaml\n│ │ │ ├── stateful-set.yaml\n│ │ │ └── ingress-config.yaml\n│ │ └── scripts/\n│ │ ├── validate-manifest.sh\n│ │ └── health-check.sh\n│ ├── terraform-iac/\n│ │ ├── SKILL.md\n│ │ ├── references/\n│ │ │ └── best-practices.md\n│ │ └── examples/\n│ │ └── module-template/\n│ └── ci-cd-pipelines/\n│ ├── SKILL.md\n│ └── references/\n│ └── pipeline-patterns.md\n├── hooks/\n│ ├── hooks.json\n│ └── scripts/\n│ ├── security/\n│ │ ├── scan-secrets.sh\n│ │ ├── validate-permissions.sh\n│ │ └── audit-changes.sh\n│ ├── quality/\n│ │ ├── check-config.sh\n│ │ └── verify-tests.sh\n│ └── workflow/\n│ ├── notify-team.sh\n│ └── update-status.sh\n├── .mcp.json\n├── servers/\n│ ├── kubernetes-mcp/\n│ │ ├── index.js\n│ │ ├── package.json\n│ │ └── lib/\n│ ├── terraform-mcp/\n│ │ ├── main.py\n│ │ └── requirements.txt\n│ └── github-actions-mcp/\n│ ├── server.js\n│ └── package.json\n├── lib/\n│ ├── core/\n│ │ ├── logger.js\n│ │ ├── config.js\n│ │ └── auth.js\n│ ├── integrations/\n│ │ ├── slack.js\n│ │ ├── pagerduty.js\n│ │ └── datadog.js\n│ └── utils/\n│ ├── retry.js\n│ └── validation.js\n└── config/\n ├── environments/\n │ ├── production.json\n │ ├── staging.json\n │ └── development.json\n └── templates/\n ├── deployment.yaml\n └── service.yaml\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"enterprise-devops\",\n \"version\": \"2.3.1\",\n \"description\": \"Comprehensive DevOps automation for enterprise CI/CD pipelines, infrastructure management, and monitoring\",\n \"author\": {\n \"name\": \"DevOps Platform Team\",\n \"email\": \"devops-platform@company.com\",\n \"url\": \"https://company.com/teams/devops\"\n },\n \"homepage\": \"https://docs.company.com/plugins/devops\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/company/devops-plugin.git\"\n },\n \"license\": \"Apache-2.0\",\n \"keywords\": [\n \"devops\",\n \"ci-cd\",\n \"kubernetes\",\n \"terraform\",\n \"automation\",\n \"infrastructure\",\n \"deployment\",\n \"monitoring\"\n ],\n \"commands\": [\n \"./commands/ci\",\n \"./commands/monitoring\",\n \"./commands/admin\"\n ],\n \"agents\": [\n \"./agents/orchestration\",\n \"./agents/specialized\"\n ],\n \"hooks\": \"./hooks/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n### .mcp.json\n\n```json\n{\n \"mcpServers\": {\n \"kubernetes\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/kubernetes-mcp/index.js\"],\n \"env\": {\n \"KUBECONFIG\": \"${KUBECONFIG}\",\n \"K8S_NAMESPACE\": \"${K8S_NAMESPACE:-default}\"\n }\n },\n \"terraform\": {\n \"command\": \"python\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/terraform-mcp/main.py\"],\n \"env\": {\n \"TF_STATE_BUCKET\": \"${TF_STATE_BUCKET}\",\n \"AWS_REGION\": \"${AWS_REGION}\"\n }\n },\n \"github-actions\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/github-actions-mcp/server.js\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\",\n \"GITHUB_ORG\": \"${GITHUB_ORG}\"\n }\n }\n }\n}\n```\n\n### commands/ci/build.md\n\n```markdown\n---\nname: build\ndescription: Trigger and monitor CI build pipeline\n---\n\n# Build Command\n\nTrigger CI/CD build pipeline and monitor progress in real-time.\n\n## Process\n\n1. **Validation**: Check prerequisites\n - Verify branch status\n - Check for uncommitted changes\n - Validate configuration files\n\n2. **Trigger**: Start build via MCP server\n \\`\\`\\`javascript\n // Uses github-actions MCP server\n const build = await tools.github_actions_trigger_workflow({\n workflow: 'build.yml',\n ref: currentBranch\n })\n \\`\\`\\`\n\n3. **Monitor**: Track build progress\n - Display real-time logs\n - Show test results as they complete\n - Alert on failures\n\n4. **Report**: Summarize results\n - Build status\n - Test coverage\n - Performance metrics\n - Deploy readiness\n\n## Integration\n\nAfter successful build:\n- Offer to deploy to staging\n- Suggest performance optimizations\n- Generate deployment checklist\n```\n\n### agents/orchestration/deployment-orchestrator.md\n\n```markdown\n---\ndescription: Orchestrates complex multi-environment deployments with rollback capabilities and health monitoring\ncapabilities:\n - Plan and execute multi-stage deployments\n - Coordinate service dependencies\n - Monitor deployment health\n - Execute automated rollbacks\n - Manage deployment approvals\n---\n\n# Deployment Orchestrator Agent\n\nSpecialized agent for orchestrating complex deployments across multiple environments.\n\n## Expertise\n\n- **Deployment strategies**: Blue-green, canary, rolling updates\n- **Dependency management**: Service startup ordering, dependency injection\n- **Health monitoring**: Service health checks, metric validation\n- **Rollback automation**: Automatic rollback on failure detection\n- **Approval workflows**: Multi-stage approval processes\n\n## Orchestration Process\n\n1. **Planning Phase**\n - Analyze deployment requirements\n - Identify service dependencies\n - Generate deployment plan\n - Calculate rollback strategy\n\n2. **Validation Phase**\n - Verify environment readiness\n - Check resource availability\n - Validate configurations\n - Run pre-deployment tests\n\n3. **Execution Phase**\n - Deploy services in dependency order\n - Monitor health after each stage\n - Validate metrics and logs\n - Proceed to next stage on success\n\n4. **Verification Phase**\n - Run smoke tests\n - Validate service integration\n - Check performance metrics\n - Confirm deployment success\n\n5. **Rollback Phase** (if needed)\n - Detect failure conditions\n - Execute rollback plan\n - Restore previous state\n - Notify stakeholders\n\n## MCP Integration\n\nUses multiple MCP servers:\n- `kubernetes`: Deploy and manage containers\n- `terraform`: Provision infrastructure\n- `github-actions`: Trigger deployment pipelines\n\n## Monitoring Integration\n\nIntegrates with monitoring tools via lib:\n\\`\\`\\`javascript\nconst { DatadogClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/datadog')\nconst metrics = await DatadogClient.getMetrics(service, timeRange)\n\\`\\`\\`\n\n## Notification Integration\n\nSends updates via Slack and PagerDuty:\n\\`\\`\\`javascript\nconst { SlackClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/slack')\nawait SlackClient.notify({\n channel: '#deployments',\n message: 'Deployment started',\n metadata: deploymentPlan\n})\n\\`\\`\\`\n```\n\n### skills/kubernetes-ops/SKILL.md\n\n```markdown\n---\nname: Kubernetes Operations\ndescription: This skill should be used when deploying to Kubernetes, managing K8s resources, troubleshooting cluster issues, configuring ingress/services, scaling deployments, or working with Kubernetes manifests. Provides comprehensive Kubernetes operational knowledge and best practices.\nversion: 2.0.0\n---\n\n# Kubernetes Operations\n\nComprehensive operational knowledge for managing Kubernetes clusters and workloads.\n\n## Overview\n\nManage Kubernetes infrastructure effectively through:\n- Deployment strategies and patterns\n- Resource configuration and optimization\n- Troubleshooting and debugging\n- Security best practices\n- Performance tuning\n\n## Core Concepts\n\n### Resource Management\n\n**Deployments**: Use for stateless applications\n- Rolling updates for zero-downtime deployments\n- Rollback capabilities for failed deployments\n- Replica management for scaling\n\n**StatefulSets**: Use for stateful applications\n- Stable network identities\n- Persistent storage\n- Ordered deployment and scaling\n\n**DaemonSets**: Use for node-level services\n- Log collectors\n- Monitoring agents\n- Network plugins\n\n### Configuration\n\n**ConfigMaps**: Store non-sensitive configuration\n- Environment-specific settings\n- Application configuration files\n- Feature flags\n\n**Secrets**: Store sensitive data\n- API keys and tokens\n- Database credentials\n- TLS certificates\n\nUse external secret management (Vault, AWS Secrets Manager) for production.\n\n### Networking\n\n**Services**: Expose applications internally\n- ClusterIP for internal communication\n- NodePort for external access (non-production)\n- LoadBalancer for external access (production)\n\n**Ingress**: HTTP/HTTPS routing\n- Path-based routing\n- Host-based routing\n- TLS termination\n- Load balancing\n\n## Deployment Strategies\n\n### Rolling Update\n\nDefault strategy, gradual replacement:\n\\`\\`\\`yaml\nstrategy:\n type: RollingUpdate\n rollingUpdate:\n maxSurge: 1\n maxUnavailable: 0\n\\`\\`\\`\n\n**When to use**: Standard deployments, minor updates\n\n### Recreate\n\nStop all pods, then create new ones:\n\\`\\`\\`yaml\nstrategy:\n type: Recreate\n\\`\\`\\`\n\n**When to use**: Stateful apps that can't run multiple versions\n\n### Blue-Green\n\nRun two complete environments, switch traffic:\n1. Deploy new version (green)\n2. Test green environment\n3. Switch traffic to green\n4. Keep blue for quick rollback\n\n**When to use**: Critical services, need instant rollback\n\n### Canary\n\nGradually roll out to subset of users:\n1. Deploy canary version (10% traffic)\n2. Monitor metrics and errors\n3. Increase traffic gradually\n4. Complete rollout or rollback\n\n**When to use**: High-risk changes, want gradual validation\n\n## Resource Configuration\n\n### Resource Requests and Limits\n\nAlways set for production workloads:\n\\`\\`\\`yaml\nresources:\n requests:\n memory: \"256Mi\"\n cpu: \"250m\"\n limits:\n memory: \"512Mi\"\n cpu: \"500m\"\n\\`\\`\\`\n\n**Requests**: Guaranteed resources\n**Limits**: Maximum allowed resources\n\n### Health Checks\n\nEssential for reliability:\n\\`\\`\\`yaml\nlivenessProbe:\n httpGet:\n path: /health\n port: 8080\n initialDelaySeconds: 30\n periodSeconds: 10\n\nreadinessProbe:\n httpGet:\n path: /ready\n port: 8080\n initialDelaySeconds: 5\n periodSeconds: 5\n\\`\\`\\`\n\n**Liveness**: Restart unhealthy pods\n**Readiness**: Remove unready pods from service\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Pods not starting**\n - Check: `kubectl describe pod `\n - Look for: Image pull errors, resource constraints\n - Fix: Verify image name, increase resources\n\n2. **Service not reachable**\n - Check: `kubectl get svc`, `kubectl get endpoints`\n - Look for: No endpoints, wrong selector\n - Fix: Verify pod labels match service selector\n\n3. **High memory usage**\n - Check: `kubectl top pods`\n - Look for: Pods near memory limit\n - Fix: Increase limits, optimize application\n\n4. **Frequent restarts**\n - Check: `kubectl get pods`, `kubectl logs `\n - Look for: Liveness probe failures, OOMKilled\n - Fix: Adjust health checks, increase memory\n\n### Debugging Commands\n\nGet pod details:\n\\`\\`\\`bash\nkubectl describe pod \nkubectl logs \nkubectl logs --previous # logs from crashed container\n\\`\\`\\`\n\nExecute commands in pod:\n\\`\\`\\`bash\nkubectl exec -it -- /bin/sh\nkubectl exec -- env\n\\`\\`\\`\n\nCheck resource usage:\n\\`\\`\\`bash\nkubectl top nodes\nkubectl top pods\n\\`\\`\\`\n\n## Security Best Practices\n\n### Pod Security\n\n- Run as non-root user\n- Use read-only root filesystem\n- Drop unnecessary capabilities\n- Use security contexts\n\nExample:\n\\`\\`\\`yaml\nsecurityContext:\n runAsNonRoot: true\n runAsUser: 1000\n readOnlyRootFilesystem: true\n capabilities:\n drop:\n - ALL\n\\`\\`\\`\n\n### Network Policies\n\nRestrict pod communication:\n\\`\\`\\`yaml\napiVersion: networking.k8s.io/v1\nkind: NetworkPolicy\nmetadata:\n name: api-allow\nspec:\n podSelector:\n matchLabels:\n app: api\n ingress:\n - from:\n - podSelector:\n matchLabels:\n app: frontend\n\\`\\`\\`\n\n### Secrets Management\n\n- Never commit secrets to git\n- Use external secret managers\n- Rotate secrets regularly\n- Limit secret access with RBAC\n\n## Performance Optimization\n\n### Resource Tuning\n\n1. **Start conservative**: Set low limits initially\n2. **Monitor usage**: Track actual resource consumption\n3. **Adjust gradually**: Increase based on metrics\n4. **Set appropriate requests**: Match typical usage\n5. **Set safe limits**: 2x requests for headroom\n\n### Horizontal Pod Autoscaling\n\nAutomatically scale based on metrics:\n\\`\\`\\`yaml\napiVersion: autoscaling/v2\nkind: HorizontalPodAutoscaler\nmetadata:\n name: api-hpa\nspec:\n scaleTargetRef:\n apiVersion: apps/v1\n kind: Deployment\n name: api\n minReplicas: 2\n maxReplicas: 10\n metrics:\n - type: Resource\n resource:\n name: cpu\n target:\n type: Utilization\n averageUtilization: 70\n\\`\\`\\`\n\n## MCP Server Integration\n\nThis skill works with the kubernetes MCP server for operations:\n\n**List pods**:\n\\`\\`\\`javascript\nconst pods = await tools.k8s_list_pods({ namespace: 'default' })\n\\`\\`\\`\n\n**Get pod logs**:\n\\`\\`\\`javascript\nconst logs = await tools.k8s_get_logs({ pod: 'api-xyz', container: 'app' })\n\\`\\`\\`\n\n**Apply manifests**:\n\\`\\`\\`javascript\nconst result = await tools.k8s_apply_manifest({ file: 'deployment.yaml' })\n\\`\\`\\`\n\n## Detailed References\n\nFor in-depth information:\n- **Deployment patterns**: `references/deployment-patterns.md`\n- **Troubleshooting guide**: `references/troubleshooting.md`\n- **Security hardening**: `references/security.md`\n\n## Example Manifests\n\nFor copy-paste examples:\n- **Basic deployment**: `examples/basic-deployment.yaml`\n- **StatefulSet**: `examples/stateful-set.yaml`\n- **Ingress config**: `examples/ingress-config.yaml`\n\n## Validation Scripts\n\nFor manifest validation:\n\\`\\`\\`bash\nbash ${CLAUDE_PLUGIN_ROOT}/skills/kubernetes-ops/scripts/validate-manifest.sh deployment.yaml\n\\`\\`\\`\n```\n\n### hooks/hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/scan-secrets.sh\",\n \"timeout\": 30\n }\n ]\n },\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Evaluate if this bash command is safe for production environment. Check for destructive operations, missing safeguards, and potential security issues. Commands should be idempotent and reversible.\",\n \"timeout\": 20\n }\n ]\n }\n ],\n \"PostToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/update-status.sh\",\n \"timeout\": 15\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quality/check-config.sh\",\n \"timeout\": 45\n },\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/notify-team.sh\",\n \"timeout\": 30\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/validate-permissions.sh\",\n \"timeout\": 20\n }\n ]\n }\n ]\n}\n```\n\n## Key Features\n\n### Multi-Level Organization\n\n**Commands**: Organized by function (CI, monitoring, admin)\n**Agents**: Separated by role (orchestration vs. specialized)\n**Skills**: Rich resources (references, examples, scripts)\n\n### MCP Integration\n\nThree custom MCP servers:\n- **Kubernetes**: Cluster operations\n- **Terraform**: Infrastructure provisioning\n- **GitHub Actions**: CI/CD automation\n\n### Shared Libraries\n\nReusable code in `lib/`:\n- **Core**: Common utilities (logging, config, auth)\n- **Integrations**: External services (Slack, Datadog)\n- **Utils**: Helper functions (retry, validation)\n\n### Configuration Management\n\nEnvironment-specific configs in `config/`:\n- **Environments**: Per-environment settings\n- **Templates**: Reusable deployment templates\n\n### Security Automation\n\nMultiple security hooks:\n- Secret scanning before writes\n- Permission validation on session start\n- Configuration auditing on completion\n\n### Monitoring Integration\n\nBuilt-in monitoring via lib integrations:\n- Datadog for metrics\n- PagerDuty for alerts\n- Slack for notifications\n\n## Use Cases\n\n1. **Multi-environment deployments**: Orchestrated rollouts across dev/staging/prod\n2. **Infrastructure as code**: Terraform automation with state management\n3. **CI/CD automation**: Build, test, deploy pipelines\n4. **Monitoring and observability**: Integrated metrics and alerting\n5. **Security enforcement**: Automated security scanning and validation\n6. **Team collaboration**: Slack notifications and status updates\n\n## When to Use This Pattern\n\n- Large-scale enterprise deployments\n- Multiple environment management\n- Complex CI/CD workflows\n- Integrated monitoring requirements\n- Security-critical infrastructure\n- Team collaboration needs\n\n## Scaling Considerations\n\n- **Performance**: Separate MCP servers for parallel operations\n- **Organization**: Multi-level directories for scalability\n- **Maintainability**: Shared libraries reduce duplication\n- **Flexibility**: Environment configs enable customization\n- **Security**: Layered security hooks and validation\n","plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md":"# Minimal Plugin Example\n\nA bare-bones plugin with a single command.\n\n## Directory Structure\n\n```\nhello-world/\n├── .claude-plugin/\n│ └── plugin.json\n└── commands/\n └── hello.md\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"hello-world\"\n}\n```\n\n### commands/hello.md\n\n```markdown\n---\nname: hello\ndescription: Prints a friendly greeting message\n---\n\n# Hello Command\n\nPrint a friendly greeting to the user.\n\n## Implementation\n\nOutput the following message to the user:\n\n> Hello! This is a simple command from the hello-world plugin.\n>\n> Use this as a starting point for building more complex plugins.\n\nInclude the current timestamp in the greeting to show the command executed successfully.\n```\n\n## Usage\n\nAfter installing the plugin:\n\n```\n$ claude\n> /hello\nHello! This is a simple command from the hello-world plugin.\n\nUse this as a starting point for building more complex plugins.\n\nExecuted at: 2025-01-15 14:30:22 UTC\n```\n\n## Key Points\n\n1. **Minimal manifest**: Only the required `name` field\n2. **Single command**: One markdown file in `commands/` directory\n3. **Auto-discovery**: Claude Code finds the command automatically\n4. **No dependencies**: No scripts, hooks, or external resources\n\n## When to Use This Pattern\n\n- Quick prototypes\n- Single-purpose utilities\n- Learning plugin development\n- Internal team tools with one specific function\n\n## Extending This Plugin\n\nTo add more functionality:\n\n1. **Add commands**: Create more `.md` files in `commands/`\n2. **Add metadata**: Update `plugin.json` with version, description, author\n3. **Add agents**: Create `agents/` directory with agent definitions\n4. **Add hooks**: Create `hooks/hooks.json` for event handling\n","plugins/plugin-dev/skills/plugin-structure/examples/standard-plugin.md":"# Standard Plugin Example\n\nA well-structured plugin with commands, agents, and skills.\n\n## Directory Structure\n\n```\ncode-quality/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n│ ├── lint.md\n│ ├── test.md\n│ └── review.md\n├── agents/\n│ ├── code-reviewer.md\n│ └── test-generator.md\n├── skills/\n│ ├── code-standards/\n│ │ ├── SKILL.md\n│ │ └── references/\n│ │ └── style-guide.md\n│ └── testing-patterns/\n│ ├── SKILL.md\n│ └── examples/\n│ ├── unit-test.js\n│ └── integration-test.js\n├── hooks/\n│ ├── hooks.json\n│ └── scripts/\n│ └── validate-commit.sh\n└── scripts/\n ├── run-linter.sh\n └── generate-report.py\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"code-quality\",\n \"version\": \"1.0.0\",\n \"description\": \"Comprehensive code quality tools including linting, testing, and review automation\",\n \"author\": {\n \"name\": \"Quality Team\",\n \"email\": \"quality@example.com\"\n },\n \"homepage\": \"https://docs.example.com/plugins/code-quality\",\n \"repository\": \"https://github.com/example/code-quality-plugin\",\n \"license\": \"MIT\",\n \"keywords\": [\"code-quality\", \"linting\", \"testing\", \"code-review\", \"automation\"]\n}\n```\n\n### commands/lint.md\n\n```markdown\n---\nname: lint\ndescription: Run linting checks on the codebase\n---\n\n# Lint Command\n\nRun comprehensive linting checks on the project codebase.\n\n## Process\n\n1. Detect project type and installed linters\n2. Run appropriate linters (ESLint, Pylint, RuboCop, etc.)\n3. Collect and format results\n4. Report issues with file locations and severity\n\n## Implementation\n\nExecute the linting script:\n\n\\`\\`\\`bash\nbash ${CLAUDE_PLUGIN_ROOT}/scripts/run-linter.sh\n\\`\\`\\`\n\nParse the output and present issues organized by:\n- Critical issues (must fix)\n- Warnings (should fix)\n- Style suggestions (optional)\n\nFor each issue, show:\n- File path and line number\n- Issue description\n- Suggested fix (if available)\n```\n\n### commands/test.md\n\n```markdown\n---\nname: test\ndescription: Run test suite with coverage reporting\n---\n\n# Test Command\n\nExecute the project test suite and generate coverage reports.\n\n## Process\n\n1. Identify test framework (Jest, pytest, RSpec, etc.)\n2. Run all tests\n3. Generate coverage report\n4. Identify untested code\n\n## Output\n\nPresent results in structured format:\n- Test summary (passed/failed/skipped)\n- Coverage percentage by file\n- Critical untested areas\n- Failed test details\n\n## Integration\n\nAfter test completion, offer to:\n- Fix failing tests\n- Generate tests for untested code (using test-generator agent)\n- Update documentation based on test changes\n```\n\n### agents/code-reviewer.md\n\n```markdown\n---\ndescription: Expert code reviewer specializing in identifying bugs, security issues, and improvement opportunities\ncapabilities:\n - Analyze code for potential bugs and logic errors\n - Identify security vulnerabilities\n - Suggest performance improvements\n - Ensure code follows project standards\n - Review test coverage adequacy\n---\n\n# Code Reviewer Agent\n\nSpecialized agent for comprehensive code review.\n\n## Expertise\n\n- **Bug detection**: Logic errors, edge cases, error handling\n- **Security analysis**: Injection vulnerabilities, authentication issues, data exposure\n- **Performance**: Algorithm efficiency, resource usage, optimization opportunities\n- **Standards compliance**: Style guide adherence, naming conventions, documentation\n- **Test coverage**: Adequacy of test cases, missing scenarios\n\n## Review Process\n\n1. **Initial scan**: Quick pass for obvious issues\n2. **Deep analysis**: Line-by-line review of changed code\n3. **Context evaluation**: Check impact on related code\n4. **Best practices**: Compare against project and language standards\n5. **Recommendations**: Prioritized list of improvements\n\n## Integration with Skills\n\nAutomatically loads `code-standards` skill for project-specific guidelines.\n\n## Output Format\n\nFor each file reviewed:\n- Overall assessment\n- Critical issues (must fix before merge)\n- Important issues (should fix)\n- Suggestions (nice to have)\n- Positive feedback (what was done well)\n```\n\n### agents/test-generator.md\n\n```markdown\n---\ndescription: Generates comprehensive test suites from code analysis\ncapabilities:\n - Analyze code structure and logic flow\n - Generate unit tests for functions and methods\n - Create integration tests for modules\n - Design edge case and error condition tests\n - Suggest test fixtures and mocks\n---\n\n# Test Generator Agent\n\nSpecialized agent for generating comprehensive test suites.\n\n## Expertise\n\n- **Unit testing**: Individual function/method tests\n- **Integration testing**: Module interaction tests\n- **Edge cases**: Boundary conditions, error paths\n- **Test organization**: Proper test structure and naming\n- **Mocking**: Appropriate use of mocks and stubs\n\n## Generation Process\n\n1. **Code analysis**: Understand function purpose and logic\n2. **Path identification**: Map all execution paths\n3. **Input design**: Create test inputs covering all paths\n4. **Assertion design**: Define expected outputs\n5. **Test generation**: Write tests in project's framework\n\n## Integration with Skills\n\nAutomatically loads `testing-patterns` skill for project-specific test conventions.\n\n## Test Quality\n\nGenerated tests include:\n- Happy path scenarios\n- Edge cases and boundary conditions\n- Error handling verification\n- Mock data for external dependencies\n- Clear test descriptions\n```\n\n### skills/code-standards/SKILL.md\n\n```markdown\n---\nname: Code Standards\ndescription: This skill should be used when reviewing code, enforcing style guidelines, checking naming conventions, or ensuring code quality standards. Provides project-specific coding standards and best practices.\nversion: 1.0.0\n---\n\n# Code Standards\n\nComprehensive coding standards and best practices for maintaining code quality.\n\n## Overview\n\nEnforce consistent code quality through standardized conventions for:\n- Code style and formatting\n- Naming conventions\n- Documentation requirements\n- Error handling patterns\n- Security practices\n\n## Style Guidelines\n\n### Formatting\n\n- **Indentation**: 2 spaces (JavaScript/TypeScript), 4 spaces (Python)\n- **Line length**: Maximum 100 characters\n- **Braces**: Same line for opening brace (K&R style)\n- **Whitespace**: Space after commas, around operators\n\n### Naming Conventions\n\n- **Variables**: camelCase for JavaScript, snake_case for Python\n- **Functions**: camelCase, descriptive verb-noun pairs\n- **Classes**: PascalCase\n- **Constants**: UPPER_SNAKE_CASE\n- **Files**: kebab-case for modules\n\n## Documentation Requirements\n\n### Function Documentation\n\nEvery function must include:\n- Purpose description\n- Parameter descriptions with types\n- Return value description with type\n- Example usage (for public functions)\n\n### Module Documentation\n\nEvery module must include:\n- Module purpose\n- Public API overview\n- Usage examples\n- Dependencies\n\n## Error Handling\n\n### Required Practices\n\n- Never swallow errors silently\n- Always log errors with context\n- Use specific error types\n- Provide actionable error messages\n- Clean up resources in finally blocks\n\n### Example Pattern\n\n\\`\\`\\`javascript\nasync function processData(data) {\n try {\n const result = await transform(data)\n return result\n } catch (error) {\n logger.error('Data processing failed', {\n data: sanitize(data),\n error: error.message,\n stack: error.stack\n })\n throw new DataProcessingError('Failed to process data', { cause: error })\n }\n}\n\\`\\`\\`\n\n## Security Practices\n\n- Validate all external input\n- Sanitize data before output\n- Use parameterized queries\n- Never log sensitive information\n- Keep dependencies updated\n\n## Detailed Guidelines\n\nFor comprehensive style guides by language, see:\n- `references/style-guide.md`\n```\n\n### skills/code-standards/references/style-guide.md\n\n```markdown\n# Comprehensive Style Guide\n\nDetailed style guidelines for all supported languages.\n\n## JavaScript/TypeScript\n\n### Variable Declarations\n\nUse `const` by default, `let` when reassignment needed, never `var`:\n\n\\`\\`\\`javascript\n// Good\nconst MAX_RETRIES = 3\nlet currentTry = 0\n\n// Bad\nvar MAX_RETRIES = 3\n\\`\\`\\`\n\n### Function Declarations\n\nUse function expressions for consistency:\n\n\\`\\`\\`javascript\n// Good\nconst calculateTotal = (items) => {\n return items.reduce((sum, item) => sum + item.price, 0)\n}\n\n// Bad (inconsistent style)\nfunction calculateTotal(items) {\n return items.reduce((sum, item) => sum + item.price, 0)\n}\n\\`\\`\\`\n\n### Async/Await\n\nPrefer async/await over promise chains:\n\n\\`\\`\\`javascript\n// Good\nasync function fetchUserData(userId) {\n const user = await db.getUser(userId)\n const orders = await db.getOrders(user.id)\n return { user, orders }\n}\n\n// Bad\nfunction fetchUserData(userId) {\n return db.getUser(userId)\n .then(user => db.getOrders(user.id)\n .then(orders => ({ user, orders })))\n}\n\\`\\`\\`\n\n## Python\n\n### Import Organization\n\nOrder imports: standard library, third-party, local:\n\n\\`\\`\\`python\n# Good\nimport os\nimport sys\n\nimport numpy as np\nimport pandas as pd\n\nfrom app.models import User\nfrom app.utils import helper\n\n# Bad - mixed order\nfrom app.models import User\nimport numpy as np\nimport os\n\\`\\`\\`\n\n### Type Hints\n\nUse type hints for all function signatures:\n\n\\`\\`\\`python\n# Good\ndef calculate_average(numbers: list[float]) -> float:\n return sum(numbers) / len(numbers)\n\n# Bad\ndef calculate_average(numbers):\n return sum(numbers) / len(numbers)\n\\`\\`\\`\n\n## Additional Languages\n\nSee language-specific guides for:\n- Go: `references/go-style.md`\n- Rust: `references/rust-style.md`\n- Ruby: `references/ruby-style.md`\n```\n\n### hooks/hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Before modifying code, verify it meets our coding standards from the code-standards skill. Check formatting, naming conventions, and documentation. If standards aren't met, suggest improvements.\",\n \"timeout\": 30\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate-commit.sh\",\n \"timeout\": 45\n }\n ]\n }\n ]\n}\n```\n\n### hooks/scripts/validate-commit.sh\n\n```bash\n#!/bin/bash\n# Validate code quality before task completion\n\nset -e\n\n# Check if there are any uncommitted changes\nif [[ -z $(git status -s) ]]; then\n echo '{\"systemMessage\": \"No changes to validate. Task complete.\"}'\n exit 0\nfi\n\n# Run linter on changed files\nCHANGED_FILES=$(git diff --name-only --cached | grep -E '\\.(js|ts|py)$' || true)\n\nif [[ -z \"$CHANGED_FILES\" ]]; then\n echo '{\"systemMessage\": \"No code files changed. Validation passed.\"}'\n exit 0\nfi\n\n# Run appropriate linters\nISSUES=0\n\nfor file in $CHANGED_FILES; do\n case \"$file\" in\n *.js|*.ts)\n if ! npx eslint \"$file\" --quiet; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n *.py)\n if ! python -m pylint \"$file\" --errors-only; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n esac\ndone\n\nif [[ $ISSUES -gt 0 ]]; then\n echo \"{\\\"systemMessage\\\": \\\"Found $ISSUES code quality issues. Please fix before completing.\\\"}\"\n exit 1\nfi\n\necho '{\"systemMessage\": \"Code quality checks passed. Ready to commit.\"}'\nexit 0\n```\n\n## Usage Examples\n\n### Running Commands\n\n```\n$ claude\n> /lint\nRunning linter checks...\n\nCritical Issues (2):\n src/api/users.js:45 - SQL injection vulnerability\n src/utils/helpers.js:12 - Unhandled promise rejection\n\nWarnings (5):\n src/components/Button.tsx:23 - Missing PropTypes\n ...\n\nStyle Suggestions (8):\n src/index.js:1 - Use const instead of let\n ...\n\n> /test\nRunning test suite...\n\nTest Results:\n ✓ 245 passed\n ✗ 3 failed\n ○ 2 skipped\n\nCoverage: 87.3%\n\nUntested Files:\n src/utils/cache.js - 0% coverage\n src/api/webhooks.js - 23% coverage\n\nFailed Tests:\n 1. User API › GET /users › should handle pagination\n Expected 200, received 500\n ...\n```\n\n### Using Agents\n\n```\n> Review the changes in src/api/users.js\n\n[code-reviewer agent selected automatically]\n\nCode Review: src/api/users.js\n\nCritical Issues:\n 1. Line 45: SQL injection vulnerability\n - Using string concatenation for SQL query\n - Replace with parameterized query\n - Priority: CRITICAL\n\n 2. Line 67: Missing error handling\n - Database query without try/catch\n - Could crash server on DB error\n - Priority: HIGH\n\nSuggestions:\n 1. Line 23: Consider caching user data\n - Frequent DB queries for same users\n - Add Redis caching layer\n - Priority: MEDIUM\n```\n\n## Key Points\n\n1. **Complete manifest**: All recommended metadata fields\n2. **Multiple components**: Commands, agents, skills, hooks\n3. **Rich skills**: References and examples for detailed information\n4. **Automation**: Hooks enforce standards automatically\n5. **Integration**: Components work together cohesively\n\n## When to Use This Pattern\n\n- Production plugins for distribution\n- Team collaboration tools\n- Plugins requiring consistency enforcement\n- Complex workflows with multiple entry points\n","plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md":"# Component Organization Patterns\n\nAdvanced patterns for organizing plugin components effectively.\n\n## Component Lifecycle\n\n### Discovery Phase\n\nWhen Claude Code starts:\n\n1. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each\n2. **Discover components**: Look in default and custom paths\n3. **Parse definitions**: Read YAML frontmatter and configurations\n4. **Register components**: Make available to Claude Code\n5. **Initialize**: Start MCP servers, register hooks\n\n**Timing**: Component registration happens during Claude Code initialization, not continuously.\n\n### Activation Phase\n\nWhen components are used:\n\n**Commands**: User types slash command → Claude Code looks up → Executes\n**Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent\n**Skills**: Task context matches description → Claude Code loads skill\n**Hooks**: Event occurs → Claude Code calls matching hooks\n**MCP Servers**: Tool call matches server capability → Forwards to server\n\n## Command Organization Patterns\n\n### Flat Structure\n\nSingle directory with all commands:\n\n```\ncommands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**When to use**:\n- 5-15 commands total\n- All commands at same abstraction level\n- No clear categorization\n\n**Advantages**:\n- Simple, easy to navigate\n- No configuration needed\n- Fast discovery\n\n### Categorized Structure\n\nMultiple directories for different command types:\n\n```\ncommands/ # Core commands\n├── build.md\n└── test.md\n\nadmin-commands/ # Administrative\n├── configure.md\n└── manage.md\n\nworkflow-commands/ # Workflow automation\n├── review.md\n└── deploy.md\n```\n\n**Manifest configuration**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./workflow-commands\"\n ]\n}\n```\n\n**When to use**:\n- 15+ commands\n- Clear functional categories\n- Different permission levels\n\n**Advantages**:\n- Organized by purpose\n- Easier to maintain\n- Can restrict access by directory\n\n### Hierarchical Structure\n\nNested organization for complex plugins:\n\n```\ncommands/\n├── ci/\n│ ├── build.md\n│ ├── test.md\n│ └── lint.md\n├── deployment/\n│ ├── staging.md\n│ └── production.md\n└── management/\n ├── config.md\n └── status.md\n```\n\n**Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths:\n\n```json\n{\n \"commands\": [\n \"./commands/ci\",\n \"./commands/deployment\",\n \"./commands/management\"\n ]\n}\n```\n\n**When to use**:\n- 20+ commands\n- Multi-level categorization\n- Complex workflows\n\n**Advantages**:\n- Maximum organization\n- Clear boundaries\n- Scalable structure\n\n## Agent Organization Patterns\n\n### Role-Based Organization\n\nOrganize agents by their primary role:\n\n```\nagents/\n├── code-reviewer.md # Reviews code\n├── test-generator.md # Generates tests\n├── documentation-writer.md # Writes docs\n└── refactorer.md # Refactors code\n```\n\n**When to use**:\n- Agents have distinct, non-overlapping roles\n- Users invoke agents manually\n- Clear agent responsibilities\n\n### Capability-Based Organization\n\nOrganize by specific capabilities:\n\n```\nagents/\n├── python-expert.md # Python-specific\n├── typescript-expert.md # TypeScript-specific\n├── api-specialist.md # API design\n└── database-specialist.md # Database work\n```\n\n**When to use**:\n- Technology-specific agents\n- Domain expertise focus\n- Automatic agent selection\n\n### Workflow-Based Organization\n\nOrganize by workflow stage:\n\n```\nagents/\n├── planning-agent.md # Planning phase\n├── implementation-agent.md # Coding phase\n├── testing-agent.md # Testing phase\n└── deployment-agent.md # Deployment phase\n```\n\n**When to use**:\n- Sequential workflows\n- Stage-specific expertise\n- Pipeline automation\n\n## Skill Organization Patterns\n\n### Topic-Based Organization\n\nEach skill covers a specific topic:\n\n```\nskills/\n├── api-design/\n│ └── SKILL.md\n├── error-handling/\n│ └── SKILL.md\n├── testing-strategies/\n│ └── SKILL.md\n└── performance-optimization/\n └── SKILL.md\n```\n\n**When to use**:\n- Knowledge-based skills\n- Educational or reference content\n- Broad applicability\n\n### Tool-Based Organization\n\nSkills for specific tools or technologies:\n\n```\nskills/\n├── docker/\n│ ├── SKILL.md\n│ └── references/\n│ └── dockerfile-best-practices.md\n├── kubernetes/\n│ ├── SKILL.md\n│ └── examples/\n│ └── deployment.yaml\n└── terraform/\n ├── SKILL.md\n └── scripts/\n └── validate-config.sh\n```\n\n**When to use**:\n- Tool-specific expertise\n- Complex tool configurations\n- Tool best practices\n\n### Workflow-Based Organization\n\nSkills for complete workflows:\n\n```\nskills/\n├── code-review-workflow/\n│ ├── SKILL.md\n│ └── references/\n│ ├── checklist.md\n│ └── standards.md\n├── deployment-workflow/\n│ ├── SKILL.md\n│ └── scripts/\n│ ├── pre-deploy.sh\n│ └── post-deploy.sh\n└── testing-workflow/\n ├── SKILL.md\n └── examples/\n └── test-structure.md\n```\n\n**When to use**:\n- Multi-step processes\n- Company-specific workflows\n- Process automation\n\n### Skill with Rich Resources\n\nComprehensive skill with all resource types:\n\n```\nskills/\n└── api-testing/\n ├── SKILL.md # Core skill (1500 words)\n ├── references/\n │ ├── rest-api-guide.md\n │ ├── graphql-guide.md\n │ └── authentication.md\n ├── examples/\n │ ├── basic-test.js\n │ ├── authenticated-test.js\n │ └── integration-test.js\n ├── scripts/\n │ ├── run-tests.sh\n │ └── generate-report.py\n └── assets/\n └── test-template.json\n```\n\n**Resource usage**:\n- **SKILL.md**: Overview and when to use resources\n- **references/**: Detailed guides (loaded as needed)\n- **examples/**: Copy-paste code samples\n- **scripts/**: Executable test runners\n- **assets/**: Templates and configurations\n\n## Hook Organization Patterns\n\n### Monolithic Configuration\n\nSingle hooks.json with all hooks:\n\n```\nhooks/\n├── hooks.json # All hook definitions\n└── scripts/\n ├── validate-write.sh\n ├── validate-bash.sh\n └── load-context.sh\n```\n\n**hooks.json**:\n```json\n{\n \"PreToolUse\": [...],\n \"PostToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**When to use**:\n- 5-10 hooks total\n- Simple hook logic\n- Centralized configuration\n\n### Event-Based Organization\n\nSeparate files per event type:\n\n```\nhooks/\n├── hooks.json # Combines all\n├── pre-tool-use.json # PreToolUse hooks\n├── post-tool-use.json # PostToolUse hooks\n├── stop.json # Stop hooks\n└── scripts/\n ├── validate/\n │ ├── write.sh\n │ └── bash.sh\n └── context/\n └── load.sh\n```\n\n**hooks.json** (combines):\n```json\n{\n \"PreToolUse\": ${file:./pre-tool-use.json},\n \"PostToolUse\": ${file:./post-tool-use.json},\n \"Stop\": ${file:./stop.json}\n}\n```\n\n**Note**: Use build script to combine files, Claude Code doesn't support file references.\n\n**When to use**:\n- 10+ hooks\n- Different teams managing different events\n- Complex hook configurations\n\n### Purpose-Based Organization\n\nGroup by functional purpose:\n\n```\nhooks/\n├── hooks.json\n└── scripts/\n ├── security/\n │ ├── validate-paths.sh\n │ ├── check-credentials.sh\n │ └── scan-malware.sh\n ├── quality/\n │ ├── lint-code.sh\n │ ├── check-tests.sh\n │ └── verify-docs.sh\n └── workflow/\n ├── notify-team.sh\n └── update-status.sh\n```\n\n**When to use**:\n- Many hook scripts\n- Clear functional boundaries\n- Team specialization\n\n## Script Organization Patterns\n\n### Flat Scripts\n\nAll scripts in single directory:\n\n```\nscripts/\n├── build.sh\n├── test.py\n├── deploy.sh\n├── validate.js\n└── report.py\n```\n\n**When to use**:\n- 5-10 scripts\n- All scripts related\n- Simple plugin\n\n### Categorized Scripts\n\nGroup by purpose:\n\n```\nscripts/\n├── build/\n│ ├── compile.sh\n│ └── package.sh\n├── test/\n│ ├── run-unit.sh\n│ └── run-integration.sh\n├── deploy/\n│ ├── staging.sh\n│ └── production.sh\n└── utils/\n ├── log.sh\n └── notify.sh\n```\n\n**When to use**:\n- 10+ scripts\n- Clear categories\n- Reusable utilities\n\n### Language-Based Organization\n\nGroup by programming language:\n\n```\nscripts/\n├── bash/\n│ ├── build.sh\n│ └── deploy.sh\n├── python/\n│ ├── analyze.py\n│ └── report.py\n└── javascript/\n ├── bundle.js\n └── optimize.js\n```\n\n**When to use**:\n- Multi-language scripts\n- Different runtime requirements\n- Language-specific dependencies\n\n## Cross-Component Patterns\n\n### Shared Resources\n\nComponents sharing common resources:\n\n```\nplugin/\n├── commands/\n│ ├── test.md # Uses lib/test-utils.sh\n│ └── deploy.md # Uses lib/deploy-utils.sh\n├── agents/\n│ └── tester.md # References lib/test-utils.sh\n├── hooks/\n│ └── scripts/\n│ └── pre-test.sh # Sources lib/test-utils.sh\n└── lib/\n ├── test-utils.sh\n └── deploy-utils.sh\n```\n\n**Usage in components**:\n```bash\n#!/bin/bash\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh\"\nrun_tests\n```\n\n**Benefits**:\n- Code reuse\n- Consistent behavior\n- Easier maintenance\n\n### Layered Architecture\n\nSeparate concerns into layers:\n\n```\nplugin/\n├── commands/ # User interface layer\n├── agents/ # Orchestration layer\n├── skills/ # Knowledge layer\n└── lib/\n ├── core/ # Core business logic\n ├── integrations/ # External services\n └── utils/ # Helper functions\n```\n\n**When to use**:\n- Large plugins (100+ files)\n- Multiple developers\n- Clear separation of concerns\n\n### Plugin Within Plugin\n\nNested plugin structure:\n\n```\nplugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── core/ # Core functionality\n│ ├── commands/\n│ └── agents/\n└── extensions/ # Optional extensions\n ├── extension-a/\n │ ├── commands/\n │ └── agents/\n └── extension-b/\n ├── commands/\n └── agents/\n```\n\n**Manifest**:\n```json\n{\n \"commands\": [\n \"./core/commands\",\n \"./extensions/extension-a/commands\",\n \"./extensions/extension-b/commands\"\n ]\n}\n```\n\n**When to use**:\n- Modular functionality\n- Optional features\n- Plugin families\n\n## Best Practices\n\n### Naming\n\n1. **Consistent naming**: Match file names to component purpose\n2. **Descriptive names**: Indicate what component does\n3. **Avoid abbreviations**: Use full words for clarity\n\n### Organization\n\n1. **Start simple**: Use flat structure, reorganize when needed\n2. **Group related items**: Keep related components together\n3. **Separate concerns**: Don't mix unrelated functionality\n\n### Scalability\n\n1. **Plan for growth**: Choose structure that scales\n2. **Refactor early**: Reorganize before it becomes painful\n3. **Document structure**: Explain organization in README\n\n### Maintainability\n\n1. **Consistent patterns**: Use same structure throughout\n2. **Minimize nesting**: Keep directory depth manageable\n3. **Use conventions**: Follow community standards\n\n### Performance\n\n1. **Avoid deep nesting**: Impacts discovery time\n2. **Minimize custom paths**: Use defaults when possible\n3. **Keep configurations small**: Large configs slow loading\n","plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md":"# Plugin Manifest Reference\n\nComplete reference for `plugin.json` configuration.\n\n## File Location\n\n**Required path**: `.claude-plugin/plugin.json`\n\nThe manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location.\n\n## Complete Field Reference\n\n### Core Fields\n\n#### name (required)\n\n**Type**: String\n**Format**: kebab-case\n**Example**: `\"test-automation-suite\"`\n\nThe unique identifier for the plugin. Used for:\n- Plugin identification in Claude Code\n- Conflict detection with other plugins\n- Command namespacing (optional)\n\n**Requirements**:\n- Must be unique across all installed plugins\n- Use only lowercase letters, numbers, and hyphens\n- No spaces or special characters\n- Start with a letter\n- End with a letter or number\n\n**Validation**:\n```javascript\n/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/\n```\n\n**Examples**:\n- ✅ Good: `api-tester`, `code-review`, `git-workflow-automation`\n- ❌ Bad: `API Tester`, `code_review`, `-git-workflow`, `test-`\n\n#### version\n\n**Type**: String\n**Format**: Semantic versioning (MAJOR.MINOR.PATCH)\n**Example**: `\"2.1.0\"`\n**Default**: `\"0.1.0\"` if not specified\n\nSemantic versioning guidelines:\n- **MAJOR**: Incompatible API changes, breaking changes\n- **MINOR**: New functionality, backward-compatible\n- **PATCH**: Bug fixes, backward-compatible\n\n**Pre-release versions**:\n- `\"1.0.0-alpha.1\"` - Alpha release\n- `\"1.0.0-beta.2\"` - Beta release\n- `\"1.0.0-rc.1\"` - Release candidate\n\n**Examples**:\n- `\"0.1.0\"` - Initial development\n- `\"1.0.0\"` - First stable release\n- `\"1.2.3\"` - Patch update to 1.2\n- `\"2.0.0\"` - Major version with breaking changes\n\n#### description\n\n**Type**: String\n**Length**: 50-200 characters recommended\n**Example**: `\"Automates code review workflows with style checks and automated feedback\"`\n\nBrief explanation of plugin purpose and functionality.\n\n**Best practices**:\n- Focus on what the plugin does, not how\n- Use active voice\n- Mention key features or benefits\n- Keep under 200 characters for marketplace display\n\n**Examples**:\n- ✅ \"Generates comprehensive test suites from code analysis and coverage reports\"\n- ✅ \"Integrates with Jira for automatic issue tracking and sprint management\"\n- ❌ \"A plugin that helps you do testing stuff\"\n- ❌ \"This is a very long description that goes on and on about every single feature...\"\n\n### Metadata Fields\n\n#### author\n\n**Type**: Object\n**Fields**: name (required), email (optional), url (optional)\n\n```json\n{\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"jane@example.com\",\n \"url\": \"https://janedeveloper.com\"\n }\n}\n```\n\n**Alternative format** (string only):\n```json\n{\n \"author\": \"Jane Developer (https://janedeveloper.com)\"\n}\n```\n\n**Use cases**:\n- Credit and attribution\n- Contact for support or questions\n- Marketplace display\n- Community recognition\n\n#### homepage\n\n**Type**: String (URL)\n**Example**: `\"https://docs.example.com/plugins/my-plugin\"`\n\nLink to plugin documentation or landing page.\n\n**Should point to**:\n- Plugin documentation site\n- Project homepage\n- Detailed usage guide\n- Installation instructions\n\n**Not for**:\n- Source code (use `repository` field)\n- Issue tracker (include in documentation)\n- Personal websites (use `author.url`)\n\n#### repository\n\n**Type**: String (URL) or Object\n**Example**: `\"https://github.com/user/plugin-name\"`\n\nSource code repository location.\n\n**String format**:\n```json\n{\n \"repository\": \"https://github.com/user/plugin-name\"\n}\n```\n\n**Object format** (detailed):\n```json\n{\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/user/plugin-name.git\",\n \"directory\": \"packages/plugin-name\"\n }\n}\n```\n\n**Use cases**:\n- Source code access\n- Issue reporting\n- Community contributions\n- Transparency and trust\n\n#### license\n\n**Type**: String\n**Format**: SPDX identifier\n**Example**: `\"MIT\"`\n\nSoftware license identifier.\n\n**Common licenses**:\n- `\"MIT\"` - Permissive, popular choice\n- `\"Apache-2.0\"` - Permissive with patent grant\n- `\"GPL-3.0\"` - Copyleft\n- `\"BSD-3-Clause\"` - Permissive\n- `\"ISC\"` - Permissive, similar to MIT\n- `\"UNLICENSED\"` - Proprietary, not open source\n\n**Full list**: https://spdx.org/licenses/\n\n**Multiple licenses**:\n```json\n{\n \"license\": \"(MIT OR Apache-2.0)\"\n}\n```\n\n#### keywords\n\n**Type**: Array of strings\n**Example**: `[\"testing\", \"automation\", \"ci-cd\", \"quality-assurance\"]`\n\nTags for plugin discovery and categorization.\n\n**Best practices**:\n- Use 5-10 keywords\n- Include functionality categories\n- Add technology names\n- Use common search terms\n- Avoid duplicating plugin name\n\n**Categories to consider**:\n- Functionality: `testing`, `debugging`, `documentation`, `deployment`\n- Technologies: `typescript`, `python`, `docker`, `aws`\n- Workflows: `ci-cd`, `code-review`, `git-workflow`\n- Domains: `web-development`, `data-science`, `devops`\n\n### Component Path Fields\n\n#### commands\n\n**Type**: String or Array of strings\n**Default**: `[\"./commands\"]`\n**Example**: `\"./cli-commands\"`\n\nAdditional directories or files containing command definitions.\n\n**Single path**:\n```json\n{\n \"commands\": \"./custom-commands\"\n}\n```\n\n**Multiple paths**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./experimental-commands\"\n ]\n}\n```\n\n**Behavior**: Supplements default `commands/` directory (does not replace)\n\n**Use cases**:\n- Organizing commands by category\n- Separating stable from experimental commands\n- Loading commands from shared locations\n\n#### agents\n\n**Type**: String or Array of strings\n**Default**: `[\"./agents\"]`\n**Example**: `\"./specialized-agents\"`\n\nAdditional directories or files containing agent definitions.\n\n**Format**: Same as `commands` field\n\n**Use cases**:\n- Grouping agents by specialization\n- Separating general-purpose from task-specific agents\n- Loading agents from plugin dependencies\n\n#### hooks\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `\"./hooks/hooks.json\"`\n\nHook configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"hooks\": \"./config/hooks.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 30\n }\n ]\n }\n ]\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Inline configuration (< 50 lines)\n- Complex plugins: External JSON file\n- Multiple hook sets: Separate files for different contexts\n\n#### mcpServers\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `./.mcp.json`\n\nMCP server configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\"\n }\n }\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Single inline server (< 20 lines)\n- Complex plugins: External `.mcp.json` file\n- Multiple servers: Always use external file\n\n## Path Resolution\n\n### Relative Path Rules\n\nAll paths in component fields must follow these rules:\n\n1. **Must be relative**: No absolute paths\n2. **Must start with `./`**: Indicates relative to plugin root\n3. **Cannot use `../`**: No parent directory navigation\n4. **Forward slashes only**: Even on Windows\n\n**Examples**:\n- ✅ `\"./commands\"`\n- ✅ `\"./src/commands\"`\n- ✅ `\"./configs/hooks.json\"`\n- ❌ `\"/Users/name/plugin/commands\"`\n- ❌ `\"commands\"` (missing `./`)\n- ❌ `\"../shared/commands\"`\n- ❌ `\".\\\\commands\"` (backslash)\n\n### Resolution Order\n\nWhen Claude Code loads components:\n\n1. **Default directories**: Scans standard locations first\n - `./commands/`\n - `./agents/`\n - `./skills/`\n - `./hooks/hooks.json`\n - `./.mcp.json`\n\n2. **Custom paths**: Scans paths specified in manifest\n - Paths from `commands` field\n - Paths from `agents` field\n - Files from `hooks` and `mcpServers` fields\n\n3. **Merge behavior**: Components from all locations load\n - No overwriting\n - All discovered components register\n - Name conflicts cause errors\n\n## Validation\n\n### Manifest Validation\n\nClaude Code validates the manifest on plugin load:\n\n**Syntax validation**:\n- Valid JSON format\n- No syntax errors\n- Correct field types\n\n**Field validation**:\n- `name` field present and valid format\n- `version` follows semantic versioning (if present)\n- Paths are relative with `./` prefix\n- URLs are valid (if present)\n\n**Component validation**:\n- Referenced paths exist\n- Hook and MCP configurations are valid\n- No circular dependencies\n\n### Common Validation Errors\n\n**Invalid name format**:\n```json\n{\n \"name\": \"My Plugin\" // ❌ Contains spaces\n}\n```\nFix: Use kebab-case\n```json\n{\n \"name\": \"my-plugin\" // ✅\n}\n```\n\n**Absolute path**:\n```json\n{\n \"commands\": \"/Users/name/commands\" // ❌ Absolute path\n}\n```\nFix: Use relative path\n```json\n{\n \"commands\": \"./commands\" // ✅\n}\n```\n\n**Missing ./ prefix**:\n```json\n{\n \"hooks\": \"hooks/hooks.json\" // ❌ No ./\n}\n```\nFix: Add ./ prefix\n```json\n{\n \"hooks\": \"./hooks/hooks.json\" // ✅\n}\n```\n\n**Invalid version**:\n```json\n{\n \"version\": \"1.0\" // ❌ Not semantic versioning\n}\n```\nFix: Use MAJOR.MINOR.PATCH\n```json\n{\n \"version\": \"1.0.0\" // ✅\n}\n```\n\n## Minimal vs. Complete Examples\n\n### Minimal Plugin\n\nBare minimum for a working plugin:\n\n```json\n{\n \"name\": \"hello-world\"\n}\n```\n\nRelies entirely on default directory discovery.\n\n### Recommended Plugin\n\nGood metadata for distribution:\n\n```json\n{\n \"name\": \"code-review-assistant\",\n \"version\": \"1.0.0\",\n \"description\": \"Automates code review with style checks and suggestions\",\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"jane@example.com\"\n },\n \"homepage\": \"https://docs.example.com/code-review\",\n \"repository\": \"https://github.com/janedev/code-review-assistant\",\n \"license\": \"MIT\",\n \"keywords\": [\"code-review\", \"automation\", \"quality\", \"ci-cd\"]\n}\n```\n\n### Complete Plugin\n\nFull configuration with all features:\n\n```json\n{\n \"name\": \"enterprise-devops\",\n \"version\": \"2.3.1\",\n \"description\": \"Comprehensive DevOps automation for enterprise CI/CD pipelines\",\n \"author\": {\n \"name\": \"DevOps Team\",\n \"email\": \"devops@company.com\",\n \"url\": \"https://company.com/devops\"\n },\n \"homepage\": \"https://docs.company.com/plugins/devops\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/company/devops-plugin.git\"\n },\n \"license\": \"Apache-2.0\",\n \"keywords\": [\n \"devops\",\n \"ci-cd\",\n \"automation\",\n \"kubernetes\",\n \"docker\",\n \"deployment\"\n ],\n \"commands\": [\n \"./commands\",\n \"./admin-commands\"\n ],\n \"agents\": \"./specialized-agents\",\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n## Best Practices\n\n### Metadata\n\n1. **Always include version**: Track changes and updates\n2. **Write clear descriptions**: Help users understand plugin purpose\n3. **Provide contact information**: Enable user support\n4. **Link to documentation**: Reduce support burden\n5. **Choose appropriate license**: Match project goals\n\n### Paths\n\n1. **Use defaults when possible**: Minimize configuration\n2. **Organize logically**: Group related components\n3. **Document custom paths**: Explain why non-standard layout used\n4. **Test path resolution**: Verify on multiple systems\n\n### Maintenance\n\n1. **Bump version on changes**: Follow semantic versioning\n2. **Update keywords**: Reflect new functionality\n3. **Keep description current**: Match actual capabilities\n4. **Maintain changelog**: Track version history\n5. **Update repository links**: Keep URLs current\n\n### Distribution\n\n1. **Complete metadata before publishing**: All fields filled\n2. **Test on clean install**: Verify plugin works without dev environment\n3. **Validate manifest**: Use validation tools\n4. **Include README**: Document installation and usage\n5. **Specify license file**: Include LICENSE file in plugin root\n","plugins/plugin-dev/skills/skill-development/SKILL.md":"---\nname: Skill Development\ndescription: This skill should be used when the user wants to \"create a skill\", \"add a skill to plugin\", \"write a new skill\", \"improve skill description\", \"organize skill content\", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.\nversion: 0.1.0\n---\n\n# Skill Development for Claude Code Plugins\n\nThis skill provides guidance for creating effective skills for Claude Code plugins.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Claude's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Claude from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\n**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. \"This skill should be used when...\" instead of \"Use this skill when...\").\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.\n\n- **When to include**: For documentation that Claude should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Claude produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Claude (Unlimited*)\n\n*Unlimited because scripts can be executed without reading into context window.\n\n## Skill Creation Process\n\nTo create a skill, follow the \"Skill Creation Process\" in order, skipping steps only if there is a clear reason why they are not applicable.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\n**For Claude Code plugins:** When building a hooks skill, the analysis shows:\n1. Developers repeatedly need to validate hooks.json and test hook scripts\n2. `scripts/validate-hook-schema.sh` and `scripts/test-hook.sh` utilities would be helpful\n3. `references/patterns.md` for detailed hook patterns to avoid bloating SKILL.md\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Create Skill Structure\n\nFor Claude Code plugins, create the skill directory structure:\n\n```bash\nmkdir -p plugin-name/skills/skill-name/{references,examples,scripts}\ntouch plugin-name/skills/skill-name/SKILL.md\n```\n\n**Note:** Unlike the generic skill-creator which uses `init_skill.py`, plugin skills are created directly in the plugin's `skills/` directory with a simpler manual structure.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-created or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAlso, delete any example files and directories not needed for the skill. Create only the directories you actually need (references/, examples/, scripts/).\n\n#### Update SKILL.md\n\n**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., \"To accomplish X, do Y\" rather than \"You should do X\" or \"If you need to do X\"). This maintains consistency and clarity for AI consumption.\n\n**Description (Frontmatter):** Use third-person format with specific trigger phrases:\n\n```yaml\n---\nname: Skill Name\ndescription: This skill should be used when the user asks to \"specific phrase 1\", \"specific phrase 2\", \"specific phrase 3\". Include exact phrases users would say that should trigger this skill. Be concrete and specific.\nversion: 0.1.0\n---\n```\n\n**Good description examples:**\n```yaml\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse hook\", \"validate tool use\", \"implement prompt-based hooks\", or mentions hook events (PreToolUse, PostToolUse, Stop).\n```\n\n**Bad description examples:**\n```yaml\ndescription: Use this skill when working with hooks. # Wrong person, vague\ndescription: Load when user needs hook help. # Not third person\ndescription: Provides hook guidance. # No trigger phrases\n```\n\nTo complete SKILL.md body, answer the following questions:\n\n1. What is the purpose of the skill, in a few sentences?\n2. When should the skill be used? (Include this in frontmatter description with specific triggers)\n3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.\n\n**Keep SKILL.md lean:** Target 1,500-2,000 words for the body. Move detailed content to references/:\n- Detailed patterns → `references/patterns.md`\n- Advanced techniques → `references/advanced.md`\n- Migration guides → `references/migration.md`\n- API references → `references/api-reference.md`\n\n**Reference resources in SKILL.md:**\n```markdown\n## Additional Resources\n\n### Reference Files\n\nFor detailed patterns and techniques, consult:\n- **`references/patterns.md`** - Common patterns\n- **`references/advanced.md`** - Advanced use cases\n\n### Example Files\n\nWorking examples in `examples/`:\n- **`example-script.sh`** - Working example\n```\n\n### Step 5: Validate and Test\n\n**For plugin skills, validation is different from generic skills:**\n\n1. **Check structure**: Skill directory in `plugin-name/skills/skill-name/`\n2. **Validate SKILL.md**: Has frontmatter with name and description\n3. **Check trigger phrases**: Description includes specific user queries\n4. **Verify writing style**: Body uses imperative/infinitive form, not second person\n5. **Test progressive disclosure**: SKILL.md is lean (~1,500-2,000 words), detailed content in references/\n6. **Check references**: All referenced files exist\n7. **Validate examples**: Examples are complete and correct\n8. **Test scripts**: Scripts are executable and work correctly\n\n**Use the skill-reviewer agent:**\n```\nAsk: \"Review my skill and check if it follows best practices\"\n```\n\nThe skill-reviewer agent will check description quality, content organization, and progressive disclosure.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n\n**Common improvements:**\n- Strengthen trigger phrases in description\n- Move long sections from SKILL.md to references/\n- Add missing examples or scripts\n- Clarify ambiguous instructions\n- Add edge case handling\n\n## Plugin-Specific Considerations\n\n### Skill Location in Plugins\n\nPlugin skills live in the plugin's `skills/` directory:\n\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n├── agents/\n└── skills/\n └── my-skill/\n ├── SKILL.md\n ├── references/\n ├── examples/\n └── scripts/\n```\n\n### Auto-Discovery\n\nClaude Code automatically discovers skills:\n- Scans `skills/` directory\n- Finds subdirectories containing `SKILL.md`\n- Loads skill metadata (name + description) always\n- Loads SKILL.md body when skill triggers\n- Loads references/examples when needed\n\n### No Packaging Needed\n\nPlugin skills are distributed as part of the plugin, not as separate ZIP files. Users get skills when they install the plugin.\n\n### Testing in Plugins\n\nTest skills by installing plugin locally:\n\n```bash\n# Test with --plugin-dir\ncc --plugin-dir /path/to/plugin\n\n# Ask questions that should trigger the skill\n# Verify skill loads correctly\n```\n\n## Examples from Plugin-Dev\n\nStudy the skills in this plugin as examples of best practices:\n\n**hook-development skill:**\n- Excellent trigger phrases: \"create a hook\", \"add a PreToolUse hook\", etc.\n- Lean SKILL.md (1,651 words)\n- 3 references/ files for detailed content\n- 3 examples/ of working hooks\n- 3 scripts/ utilities\n\n**agent-development skill:**\n- Strong triggers: \"create an agent\", \"agent frontmatter\", etc.\n- Focused SKILL.md (1,438 words)\n- References include the AI generation prompt from Claude Code\n- Complete agent examples\n\n**plugin-settings skill:**\n- Specific triggers: \"plugin settings\", \".local.md files\", \"YAML frontmatter\"\n- References show real implementations (multi-agent-swarm, ralph-wiggum)\n- Working parsing scripts\n\nEach demonstrates progressive disclosure and strong triggering.\n\n## Progressive Disclosure in Practice\n\n### What Goes in SKILL.md\n\n**Include (always loaded when skill triggers):**\n- Core concepts and overview\n- Essential procedures and workflows\n- Quick reference tables\n- Pointers to references/examples/scripts\n- Most common use cases\n\n**Keep under 3,000 words, ideally 1,500-2,000 words**\n\n### What Goes in references/\n\n**Move to references/ (loaded as needed):**\n- Detailed patterns and advanced techniques\n- Comprehensive API documentation\n- Migration guides\n- Edge cases and troubleshooting\n- Extensive examples and walkthroughs\n\n**Each reference file can be large (2,000-5,000+ words)**\n\n### What Goes in examples/\n\n**Working code examples:**\n- Complete, runnable scripts\n- Configuration files\n- Template files\n- Real-world usage examples\n\n**Users can copy and adapt these directly**\n\n### What Goes in scripts/\n\n**Utility scripts:**\n- Validation tools\n- Testing helpers\n- Parsing utilities\n- Automation scripts\n\n**Should be executable and documented**\n\n## Writing Style Requirements\n\n### Imperative/Infinitive Form\n\nWrite using verb-first instructions, not second person:\n\n**Correct (imperative):**\n```\nTo create a hook, define the event type.\nConfigure the MCP server with authentication.\nValidate settings before use.\n```\n\n**Incorrect (second person):**\n```\nYou should create a hook by defining the event type.\nYou need to configure the MCP server.\nYou must validate settings before use.\n```\n\n### Third-Person in Description\n\nThe frontmatter description must use third person:\n\n**Correct:**\n```yaml\ndescription: This skill should be used when the user asks to \"create X\", \"configure Y\"...\n```\n\n**Incorrect:**\n```yaml\ndescription: Use this skill when you want to create X...\ndescription: Load this skill when user asks...\n```\n\n### Objective, Instructional Language\n\nFocus on what to do, not who should do it:\n\n**Correct:**\n```\nParse the frontmatter using sed.\nExtract fields with grep.\nValidate values before use.\n```\n\n**Incorrect:**\n```\nYou can parse the frontmatter...\nClaude should extract fields...\nThe user might validate values...\n```\n\n## Validation Checklist\n\nBefore finalizing a skill:\n\n**Structure:**\n- [ ] SKILL.md file exists with valid YAML frontmatter\n- [ ] Frontmatter has `name` and `description` fields\n- [ ] Markdown body is present and substantial\n- [ ] Referenced files actually exist\n\n**Description Quality:**\n- [ ] Uses third person (\"This skill should be used when...\")\n- [ ] Includes specific trigger phrases users would say\n- [ ] Lists concrete scenarios (\"create X\", \"configure Y\")\n- [ ] Not vague or generic\n\n**Content Quality:**\n- [ ] SKILL.md body uses imperative/infinitive form\n- [ ] Body is focused and lean (1,500-2,000 words ideal, <5k max)\n- [ ] Detailed content moved to references/\n- [ ] Examples are complete and working\n- [ ] Scripts are executable and documented\n\n**Progressive Disclosure:**\n- [ ] Core concepts in SKILL.md\n- [ ] Detailed docs in references/\n- [ ] Working code in examples/\n- [ ] Utilities in scripts/\n- [ ] SKILL.md references these resources\n\n**Testing:**\n- [ ] Skill triggers on expected user queries\n- [ ] Content is helpful for intended tasks\n- [ ] No duplicated information across files\n- [ ] References load when needed\n\n## Common Mistakes to Avoid\n\n### Mistake 1: Weak Trigger Description\n\n❌ **Bad:**\n```yaml\ndescription: Provides guidance for working with hooks.\n```\n\n**Why bad:** Vague, no specific trigger phrases, not third person\n\n✅ **Good:**\n```yaml\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse hook\", \"validate tool use\", or mentions hook events. Provides comprehensive hooks API guidance.\n```\n\n**Why good:** Third person, specific phrases, concrete scenarios\n\n### Mistake 2: Too Much in SKILL.md\n\n❌ **Bad:**\n```\nskill-name/\n└── SKILL.md (8,000 words - everything in one file)\n```\n\n**Why bad:** Bloats context when skill loads, detailed content always loaded\n\n✅ **Good:**\n```\nskill-name/\n├── SKILL.md (1,800 words - core essentials)\n└── references/\n ├── patterns.md (2,500 words)\n └── advanced.md (3,700 words)\n```\n\n**Why good:** Progressive disclosure, detailed content loaded only when needed\n\n### Mistake 3: Second Person Writing\n\n❌ **Bad:**\n```markdown\nYou should start by reading the configuration file.\nYou need to validate the input.\nYou can use the grep tool to search.\n```\n\n**Why bad:** Second person, not imperative form\n\n✅ **Good:**\n```markdown\nStart by reading the configuration file.\nValidate the input before processing.\nUse the grep tool to search for patterns.\n```\n\n**Why good:** Imperative form, direct instructions\n\n### Mistake 4: Missing Resource References\n\n❌ **Bad:**\n```markdown\n# SKILL.md\n\n[Core content]\n\n[No mention of references/ or examples/]\n```\n\n**Why bad:** Claude doesn't know references exist\n\n✅ **Good:**\n```markdown\n# SKILL.md\n\n[Core content]\n\n## Additional Resources\n\n### Reference Files\n- **`references/patterns.md`** - Detailed patterns\n- **`references/advanced.md`** - Advanced techniques\n\n### Examples\n- **`examples/script.sh`** - Working example\n```\n\n**Why good:** Claude knows where to find additional information\n\n## Quick Reference\n\n### Minimal Skill\n\n```\nskill-name/\n└── SKILL.md\n```\n\nGood for: Simple knowledge, no complex resources needed\n\n### Standard Skill (Recommended)\n\n```\nskill-name/\n├── SKILL.md\n├── references/\n│ └── detailed-guide.md\n└── examples/\n └── working-example.sh\n```\n\nGood for: Most plugin skills with detailed documentation\n\n### Complete Skill\n\n```\nskill-name/\n├── SKILL.md\n├── references/\n│ ├── patterns.md\n│ └── advanced.md\n├── examples/\n│ ├── example1.sh\n│ └── example2.json\n└── scripts/\n └── validate.sh\n```\n\nGood for: Complex domains with validation utilities\n\n## Best Practices Summary\n\n✅ **DO:**\n- Use third-person in description (\"This skill should be used when...\")\n- Include specific trigger phrases (\"create X\", \"configure Y\")\n- Keep SKILL.md lean (1,500-2,000 words)\n- Use progressive disclosure (move details to references/)\n- Write in imperative/infinitive form\n- Reference supporting files clearly\n- Provide working examples\n- Create utility scripts for common operations\n- Study plugin-dev's skills as templates\n\n❌ **DON'T:**\n- Use second person anywhere\n- Have vague trigger conditions\n- Put everything in SKILL.md (>3,000 words without references/)\n- Write in second person (\"You should...\")\n- Leave resources unreferenced\n- Include broken or incomplete examples\n- Skip validation\n\n## Additional Resources\n\n### Study These Skills\n\nPlugin-dev's skills demonstrate best practices:\n- `../hook-development/` - Progressive disclosure, utilities\n- `../agent-development/` - AI-assisted creation, references\n- `../mcp-integration/` - Comprehensive references\n- `../plugin-settings/` - Real-world examples\n- `../command-development/` - Clear critical concepts\n- `../plugin-structure/` - Good organization\n\n### Reference Files\n\nFor complete skill-creator methodology:\n- **`references/skill-creator-original.md`** - Full original skill-creator content\n\n## Implementation Workflow\n\nTo create a skill for your plugin:\n\n1. **Understand use cases**: Identify concrete examples of skill usage\n2. **Plan resources**: Determine what scripts/references/examples needed\n3. **Create structure**: `mkdir -p skills/skill-name/{references,examples,scripts}`\n4. **Write SKILL.md**:\n - Frontmatter with third-person description and trigger phrases\n - Lean body (1,500-2,000 words) in imperative form\n - Reference supporting files\n5. **Add resources**: Create references/, examples/, scripts/ as needed\n6. **Validate**: Check description, writing style, organization\n7. **Test**: Verify skill loads on expected triggers\n8. **Iterate**: Improve based on usage\n\nFocus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.\n","plugins/plugin-dev/skills/skill-development/references/skill-creator-original.md":"---\nname: skill-creator\ndescription: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.\nlicense: Complete terms in LICENSE.txt\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Claude's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Claude from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\n**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. \"This skill should be used when...\" instead of \"Use this skill when...\").\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.\n\n- **When to include**: For documentation that Claude should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Claude produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Claude (Unlimited*)\n\n*Unlimited because scripts can be executed without reading into context window.\n\n## Skill Creation Process\n\nTo create a skill, follow the \"Skill Creation Process\" in order, skipping steps only if there is a clear reason why they are not applicable.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.\n\nUsage:\n\n```bash\nscripts/init_skill.py --path \n```\n\nThe script:\n\n- Creates the skill directory at the specified path\n- Generates a SKILL.md template with proper frontmatter and TODO placeholders\n- Creates example resource directories: `scripts/`, `references/`, and `assets/`\n- Adds example files in each directory that can be customized or deleted\n\nAfter initialization, customize or remove the generated SKILL.md and example files as needed.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAlso, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.\n\n#### Update SKILL.md\n\n**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., \"To accomplish X, do Y\" rather than \"You should do X\" or \"If you need to do X\"). This maintains consistency and clarity for AI consumption.\n\nTo complete SKILL.md, answer the following questions:\n\n1. What is the purpose of the skill, in a few sentences?\n2. When should the skill be used?\n3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.\n\n### Step 5: Packaging a Skill\n\nOnce the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:\n\n```bash\nscripts/package_skill.py \n```\n\nOptional output directory specification:\n\n```bash\nscripts/package_skill.py ./dist\n```\n\nThe packaging script will:\n\n1. **Validate** the skill automatically, checking:\n - YAML frontmatter format and required fields\n - Skill naming conventions and directory structure\n - Description completeness and quality\n - File organization and resource references\n\n2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.\n\nIf validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n","plugins/pr-review-toolkit/.claude-plugin/plugin.json":"","plugins/pr-review-toolkit/README.md":"","plugins/ralph-wiggum/.claude-plugin/plugin.json":"","plugins/ralph-wiggum/README.md":"","plugins/security-guidance/.claude-plugin/plugin.json":"","plugins/security-guidance/README.md":""},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nGuidance for Claude Code and other coding agents working in this repository.\n\n## Security hardening for GitHub Actions\n\nWorkflow jobs in this repository that call Claude run with three protections.\nKeep them when you add or edit a workflow.\n\n1. **Egress-firewall runner.** The job has `runs-on: ubuntu-24.04-firewall`,\n a GitHub-hosted runner that filters the job's outbound network traffic. Do\n not move a job that calls Claude to another runner.\n2. **Network allow list.** `.github/egress-firewall.yaml` lists the hosts\n those jobs may reach, besides any that GitHub's firewall allows by default.\n Keep `mode: enforce`, which is what makes the firewall block the rest. Follow\n that file's header when you add a host.\n3. **Auto permission mode.** Every step that runs the Claude Code action\n (`uses: anthropics/claude-code-action`, or a local action with a\n `claude_args` input) passes `--permission-mode auto` in `claude_args`. A tool\n call that needs permission and that the allowed tools do not cover then runs\n only if Claude Code's safety review passes it. Allow only the tools the job\n needs, and keep any `--disallowedTools` list a step has. Use `claude-opus-4-6`\n or a newer model: on an older one Claude Code falls back to its default\n permission mode.\n\n`claude.yml` answers `@claude` mentions. The Claude Code action sets\n`--permission-mode acceptEdits` for those, and the `--permission-mode auto` in\nthe workflow's `claude_args`, which comes after it, replaces it.\n\n`.github/workflows/workflow-hardening.yml` fails when a job that runs the Claude\nCode action or mentions `ANTHROPIC_FEDERATION_RULE_ID` breaks protection 1 or 3,\nor when the allow list is missing, empty, not `mode: enforce`, or names a host\nwith `*`. It cannot see a job that calls Claude another way, so check new\nworkflows by hand too. If a job cannot meet protection 1 or 3, add it with the\nreason to the matching exemption table in\n`.github/scripts/check_workflow_hardening.py`. A job in `EXEMPT_FROM_AUTO_MODE`\nmust set no permission mode at all. Do not skip or weaken the check.\n\nKeep each workflow's `permissions:` block minimal, and never print tokens or\nenvironment variables in workflow logs.\n","isInternal":false,"tokens":544,"sizeBytes":2218},{"name":"effort.md","path":"plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/effort.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/effort.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Effort Parameter (Beta)\n\n**Add effort set to `\"high\"` during migration.** This is the default configuration for best performance with Opus 4.5.\n\n## Overview\n\nEffort controls how eagerly Claude spends tokens. It affects all tokens: thinking, text responses, and function calls.\n\n| Effort | Use Case |\n|--------|----------|\n| `high` | Best performance, deep reasoning (default) |\n| `medium` | Balance of cost/latency vs. performance |\n| `low` | Simple, high-volume queries; significant token savings |\n\n## Implementation\n\nRequires beta flag `effort-2025-11-24` in API calls.\n\n**Python SDK:**\n```python\nresponse = client.messages.create(\n model=\"claude-opus-4-5-20251101\",\n max_tokens=1024,\n betas=[\"effort-2025-11-24\"],\n output_config={\n \"effort\": \"high\" # or \"medium\" or \"low\"\n },\n messages=[...]\n)\n```\n\n**TypeScript SDK:**\n```typescript\nconst response = await client.messages.create({\n model: \"claude-opus-4-5-20251101\",\n max_tokens: 1024,\n betas: [\"effort-2025-11-24\"],\n output_config: {\n effort: \"high\" // or \"medium\" or \"low\"\n },\n messages: [...]\n});\n```\n\n**Raw API:**\n```json\n{\n \"model\": \"claude-opus-4-5-20251101\",\n \"max_tokens\": 1024,\n \"anthropic-beta\": \"effort-2025-11-24\",\n \"output_config\": {\n \"effort\": \"high\"\n },\n \"messages\": [...]\n}\n```\n\n## Effort vs. Thinking Budget\n\nEffort is independent of thinking budget:\n\n- High effort + no thinking = more tokens, but no thinking tokens\n- High effort + 32k thinking = more tokens, but thinking capped at 32k\n\n## Recommendations\n\n1. First determine effort level, then set thinking budget\n2. Best performance: high effort + high thinking budget\n3. Cost/latency optimization: medium effort\n4. Simple high-volume queries: low effort\n","isInternal":false,"tokens":486,"sizeBytes":1728},{"name":"prompt-snippets.md","path":"plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/prompt-snippets.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/references/prompt-snippets.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Prompt Snippets for Opus 4.5\n\nOnly apply these snippets if the user explicitly requests them or reports a specific issue. By default, the migration should only update model strings.\n\n## 1. Tool Overtriggering\n\n**Problem**: Prompts designed to reduce undertriggering on previous models may cause Opus 4.5 to overtrigger.\n\n**When to add**: User reports tools being called too frequently or unnecessarily.\n\n**Solution**: Replace aggressive language with normal phrasing.\n\n| Before | After |\n|--------|-------|\n| `CRITICAL: You MUST use this tool when...` | `Use this tool when...` |\n| `ALWAYS call the search function before...` | `Call the search function before...` |\n| `You are REQUIRED to...` | `You should...` |\n| `NEVER skip this step` | `Don't skip this step` |\n\n## 2. Over-Engineering Prevention\n\n**Problem**: Opus 4.5 may create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**When to add**: User reports unwanted files, excessive abstraction, or unrequested features.\n\n**Snippet to add to system prompt**:\n\n```\n- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.\n- Don't add features, refactor code, or make \"improvements\" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.\n- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.\n- Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.\n```\n\n## 3. Code Exploration\n\n**Problem**: Opus 4.5 may propose solutions without reading code or make assumptions about unread files.\n\n**When to add**: User reports the model proposing fixes without inspecting relevant code.\n\n**Snippet to add to system prompt**:\n\n```\nALWAYS read and understand relevant files before proposing code edits. Do not speculate about code you have not inspected. If the user references a specific file/path, you MUST open and inspect it before explaining or proposing fixes. Be rigorous and persistent in searching code for key facts. Thoroughly review the style, conventions, and abstractions of the codebase before implementing new features or abstractions.\n```\n\n## 4. Frontend Design Quality\n\n**Problem**: Default frontend outputs may look generic (\"AI slop\" aesthetic).\n\n**When to add**: User requests improved frontend design quality or reports generic-looking outputs.\n\n**Snippet to add to system prompt**:\n\n```xml\n\nYou tend to converge toward generic, \"on distribution\" outputs. In frontend design, this creates what users call the \"AI slop\" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight.\n\nFocus on:\n- Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.\n- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.\n- Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.\n- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.\n\nAvoid generic AI-generated aesthetics:\n- Overused font families (Inter, Roboto, Arial, system fonts)\n- Clichéd color schemes (particularly purple gradients on white backgrounds)\n- Predictable layouts and component patterns\n- Cookie-cutter design that lacks context-specific character\n\nInterpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!\n\n```\n\n## 5. Thinking Sensitivity\n\n**Problem**: When extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants.\n\nExtended thinking is not enabled by default. It is only enabled if the API request contains a `thinking` parameter:\n```json\n\"thinking\": {\n \"type\": \"enabled\",\n \"budget_tokens\": 10000\n}\n```\n\n**When to apply**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in their request).\n\n**Solution**: Replace \"think\" with alternative words.\n\n| Before | After |\n|--------|-------|\n| `think about` | `consider` |\n| `think through` | `evaluate` |\n| `I think` | `I believe` |\n| `think carefully` | `consider carefully` |\n| `thinking` | `reasoning` / `considering` |\n\n## Usage Guidelines\n\n1. **Integrate thoughtfully** - Don't just append snippets; weave them into the existing prompt structure\n2. **Use XML tags** - Wrap additions in descriptive tags (e.g., ``, ``) that match or complement existing prompt structure\n3. **Match prompt style** - If the prompt is concise, trim the snippet; if verbose, keep full detail\n4. **Place logically** - Put coding snippets near other coding instructions, tool guidance near tool definitions, etc.\n5. **Preserve existing content** - Insert snippets without removing functional content\n6. **Summarize changes** - After migration, list all model string updates and prompt modifications made\n","isInternal":false,"tokens":1306,"sizeBytes":6139},{"name":"SKILL.md","path":"plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/claude-opus-4-5-migration/skills/claude-opus-4-5-migration/SKILL.md","title":"claude-opus-4-5-migration","category":"anthropic-skill","format":"markdown","content":"---\nname: claude-opus-4-5-migration\ndescription: Migrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5. Use when the user wants to update their codebase, prompts, or API calls to use Opus 4.5. Handles model string updates and prompt adjustments for known Opus 4.5 behavioral differences. Does NOT migrate Haiku 4.5.\n---\n\n# Opus 4.5 Migration Guide\n\nOne-shot migration from Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5.\n\n## Migration Workflow\n\n1. Search codebase for model strings and API calls\n2. Update model strings to Opus 4.5 (see platform-specific strings below)\n3. Remove unsupported beta headers\n4. Add effort parameter set to `\"high\"` (see `references/effort.md`)\n5. Summarize all changes made\n6. Tell the user: \"If you encounter any issues with Opus 4.5, let me know and I can help adjust your prompts.\"\n\n## Model String Updates\n\nIdentify which platform the codebase uses, then replace model strings accordingly.\n\n### Unsupported Beta Headers\n\nRemove the `context-1m-2025-08-07` beta header if present—it is not yet supported with Opus 4.5. Leave a comment noting this:\n\n```python\n# Note: 1M context beta (context-1m-2025-08-07) not yet supported with Opus 4.5\n```\n\n### Target Model Strings (Opus 4.5)\n\n| Platform | Opus 4.5 Model String |\n|----------|----------------------|\n| Anthropic API (1P) | `claude-opus-4-5-20251101` |\n| AWS Bedrock | `anthropic.claude-opus-4-5-20251101-v1:0` |\n| Google Vertex AI | `claude-opus-4-5@20251101` |\n| Azure AI Foundry | `claude-opus-4-5-20251101` |\n\n### Source Model Strings to Replace\n\n| Source Model | Anthropic API (1P) | AWS Bedrock | Google Vertex AI |\n|--------------|-------------------|-------------|------------------|\n| Sonnet 4.0 | `claude-sonnet-4-20250514` | `anthropic.claude-sonnet-4-20250514-v1:0` | `claude-sonnet-4@20250514` |\n| Sonnet 4.5 | `claude-sonnet-4-5-20250929` | `anthropic.claude-sonnet-4-5-20250929-v1:0` | `claude-sonnet-4-5@20250929` |\n| Opus 4.1 | `claude-opus-4-1-20250422` | `anthropic.claude-opus-4-1-20250422-v1:0` | `claude-opus-4-1@20250422` |\n\n**Do NOT migrate**: Any Haiku models (e.g., `claude-haiku-4-5-20251001`).\n\n## Prompt Adjustments\n\nOpus 4.5 has known behavioral differences from previous models. **Only apply these fixes if the user explicitly requests them or reports a specific issue.** By default, just update model strings.\n\n**Integration guidelines**: When adding snippets, don't just append them to prompts. Integrate them thoughtfully:\n- Use XML tags (e.g., ``, ``) to organize additions\n- Match the style and structure of the existing prompt\n- Place snippets in logical locations (e.g., coding guidelines near other coding instructions)\n- If the prompt already uses XML tags, add new content within appropriate existing tags or create consistent new ones\n\n### 1. Tool Overtriggering\n\nOpus 4.5 is more responsive to system prompts. Aggressive language that prevented undertriggering on previous models may now cause overtriggering.\n\n**Apply if**: User reports tools being called too frequently or unnecessarily.\n\n**Find and soften**:\n- `CRITICAL:` → remove or soften\n- `You MUST...` → `You should...`\n- `ALWAYS do X` → `Do X`\n- `NEVER skip...` → `Don't skip...`\n- `REQUIRED` → remove or soften\n\nOnly apply to tool-triggering instructions. Leave other uses of emphasis alone.\n\n### 2. Over-Engineering Prevention\n\nOpus 4.5 tends to create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**Apply if**: User reports unwanted files, excessive abstraction, or unrequested features. Add the snippet from `references/prompt-snippets.md`.\n\n### 3. Code Exploration\n\nOpus 4.5 can be overly conservative about exploring code, proposing solutions without reading files.\n\n**Apply if**: User reports the model proposing fixes without inspecting relevant code. Add the snippet from `references/prompt-snippets.md`.\n\n### 4. Frontend Design\n\n**Apply if**: User requests improved frontend design quality or reports generic-looking outputs.\n\nAdd the frontend aesthetics snippet from `references/prompt-snippets.md`.\n\n### 5. Thinking Sensitivity\n\nWhen extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants. Extended thinking is enabled only if the API request contains a `thinking` parameter.\n\n**Apply if**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in request).\n\nReplace \"think\" with alternatives like \"consider,\" \"believe,\" or \"evaluate.\"\n\n## Reference\n\nSee `references/prompt-snippets.md` for the full text of each snippet to add.\n\nSee `references/effort.md` for configuring the effort parameter (only if user requests it).\n","frontmatter":{"name":"claude-opus-4-5-migration","description":"Migrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5. Use when the user wants to update their codebase, prompts, or API calls to use Opus 4.5. Handles model string updates and prompt adjustments for known Opus 4.5 behavioral differences. Does NOT migrate Haiku 4.5."},"isInternal":false,"tokens":1285,"sizeBytes":4746},{"name":"SKILL.md","path":"plugins/frontend-design/skills/frontend-design/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/frontend-design/skills/frontend-design/SKILL.md","title":"frontend-design","category":"anthropic-skill","format":"markdown","content":"---\nname: frontend-design\ndescription: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.\nlicense: Complete terms in LICENSE.txt\n---\n\n# Frontend Design\n\nApproach this as the design lead at a design studio known for giving every client a distinct visual identity that is not mistaken for anyone else's. This client has already rejected proposals that felt cliché or templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take aesthetic risk if justified.\n\n## Ground your designs in the subject matter\n\nIf the brief does not identify what the product or subject matter is, identify it yourself before designing, and confirm with the client. You can come up with one concrete subject, the design's audience, and the design's primary job, as a proposal. If there's any information in your memory about the client's preferences or context about what they're building, use that as a hint. The subject's industry, subject matter, materials, and vernacular are where distinctive visual choices come from — a design for a toy for girls aged 8–11 will be very aesthetically different from a dashboard for financial analysts. Build with the brief's real content and subject matter throughout.\n\n## Design principles\n\nFor web designs, the hero is the first thing viewers will see. Open with the most characteristic thing in the subject's world, in the form that is most appropriate: a headline, an image, an animation, a live demo, an interactive moment, or other treatments. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the default treatment, so only use it if that's truly the best option.\n\nTypography carries the personality of the page. You don't need a different typeface for display or headline text and body content: use one family or two, and if two, make them clearly distinct.\n\nChoose your typefaces deliberately, not the default families you would reach for on any other project, and set a clear type scale following the default guidance of The Elements of Typographic Style with intentional weights, widths, and spacing. When type is used as a headline or visual element, use the type treatment itself as an active part of the design, not a neutral delivery vehicle for the content.\n\nDefault to line lengths of less than 80 characters. Serif typefaces can have slightly longer line lengths; give serif body text slightly more line-height than a sans-serif.\n\nAvoid these default typographic treatments; they are the commonest tells of a generated page:\n- Accenting just a single word or phrase in a headline, like putting one word in italic/bold or a different color.\n- Using all caps for labels.\n- Adding unnecessary typographic labels above content.\n\nVisual structure is information. Structural devices like outlines, borders, numbering, eyebrows, dividers, labels, etc., encode useful information about the content rather than decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence — like a stepped process or a timeline. Before adding numbered markers, check the content really is a sequence.\n\nUse non-user-triggered motion sparingly and deliberately, only to draw attention. A single orchestrated moment — one page-load sequence or one reveal — lands better than scattered effects; fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as AI-generated. Motion that answers a person's action (opening, expanding, confirming) is welcome when it shows what changed.\n\nConsider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy and placeholder content. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.\n\n## Process: plan, review against the brief, build, critique\n\nFor calibration, AI-generated design right now clusters around some traits:\n1. a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta or warm-clay accent (often near #D97757 — Anthropic's own Claude-interaction accent, so on a user's brief it reads as a tell);\n2. a near-black background with a single bright acid-green or vermilion accent;\n3. a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns;\n4. the SaaS-card kit: content chopped into identical rounded cards, one border-radius on everything regardless of hierarchy, the same soft grey shadow (rgba(0,0,0,.1)) under each, and gradient washes as decoration;\n5. template chrome that appears whatever the subject: a tracked-out ALL-CAPS eyebrow label above every heading; meta strings joined with middle dots ('A · B · C'); labels built as 'WORD — fragment' with a spaced em dash; tinted near-black (#0B0B0B, #111) standing in for black; a monospace face for small data labels; a '→' appended to link and button text.\n\nAll traits are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. As with a hired human designer, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.\n\nWork in two passes. First, brainstorm a short design plan based on the client's design brief: create a compact token system with color, type, layout, and principles.\n- Color: describe the core base palette as 4–6 named hex values.\n- Type: the typefaces and their roles.\n- Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Include alignment guidance; should the content be left aligned, center aligned, justified?\n- Principles: the high-level guidance for what makes this page unique.\n\nThen review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan.\n\nWhen writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and an element-based selector like .cta). This can happen often with padding/margin between sections.\n\n## Restraint and self-critique\n\nSpend your boldness in one place. Let one element be the memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected, visually accessible, harmonious color palettes. Critique your own work as you build, taking screenshots to review if your environment supports it — a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creatives have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.\n\n## More on writing in design\n\nWords appear in a design for one reason: to make it easier to understand and use. They are design content, not decoration. Bring the same intentionality and minimalism to copywriting that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.\n\nWrite from the end user's perspective. Name things by what users will understand in simple language, not by how the system is built. A user manages notifications, not webhook config. Describe what something is or does in plain terms rather than selling it. Being specific and legible to new users is always better than being clever.\n\nUse active voice as default. A CTA says exactly what happens when it is used: \"Save changes,\" not \"Submit.\" An action keeps the same name through the whole flow, so the button that says \"Publish\" produces a toast that says \"Published.\" The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.\n\nTreat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.\n\nKeep the tone conversational: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each written element do exactly one job.\n","frontmatter":{"name":"frontend-design","description":"Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.","license":"Complete terms in LICENSE.txt"},"isInternal":false,"tokens":1924,"sizeBytes":9390},{"name":"SKILL.md","path":"plugins/hookify/skills/writing-rules/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/hookify/skills/writing-rules/SKILL.md","title":"Writing Hookify Rules","category":"anthropic-skill","format":"markdown","content":"---\nname: Writing Hookify Rules\ndescription: This skill should be used when the user asks to \"create a hookify rule\", \"write a hook rule\", \"configure hookify\", \"add a hookify rule\", or needs guidance on hookify rule syntax and patterns.\nversion: 0.1.0\n---\n\n# Writing Hookify Rules\n\n## Overview\n\nHookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to show when those patterns match. Rules are stored in `.claude/hookify.{rule-name}.local.md` files.\n\n## Rule File Format\n\n### Basic Structure\n\n```markdown\n---\nname: rule-identifier\nenabled: true\nevent: bash|file|stop|prompt|all\npattern: regex-pattern-here\n---\n\nMessage to show Claude when this rule triggers.\nCan include markdown formatting, warnings, suggestions, etc.\n```\n\n### Frontmatter Fields\n\n**name** (required): Unique identifier for the rule\n- Use kebab-case: `warn-dangerous-rm`, `block-console-log`\n- Be descriptive and action-oriented\n- Start with verb: warn, prevent, block, require, check\n\n**enabled** (required): Boolean to activate/deactivate\n- `true`: Rule is active\n- `false`: Rule is disabled (won't trigger)\n- Can toggle without deleting rule\n\n**event** (required): Which hook event to trigger on\n- `bash`: Bash tool commands\n- `file`: Edit, Write, MultiEdit tools\n- `stop`: When agent wants to stop\n- `prompt`: When user submits a prompt\n- `all`: All events\n\n**action** (optional): What to do when rule matches\n- `warn`: Show message but allow operation (default)\n- `block`: Prevent operation (PreToolUse) or stop session (Stop events)\n- If omitted, defaults to `warn`\n\n**pattern** (simple format): Regex pattern to match\n- Used for simple single-condition rules\n- Matches against command (bash) or new_text (file)\n- Python regex syntax\n\n**Example:**\n```yaml\nevent: bash\npattern: rm\\s+-rf\n```\n\n### Advanced Format (Multiple Conditions)\n\nFor complex rules with multiple conditions:\n\n```markdown\n---\nname: warn-env-file-edits\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.env$\n - field: new_text\n operator: contains\n pattern: API_KEY\n---\n\nYou're adding an API key to a .env file. Ensure this file is in .gitignore!\n```\n\n**Condition fields:**\n- `field`: Which field to check\n - For bash: `command`\n - For file: `file_path`, `new_text`, `old_text`, `content`\n- `operator`: How to match\n - `regex_match`: Regex pattern matching\n - `contains`: Substring check\n - `equals`: Exact match\n - `not_contains`: Substring must NOT be present\n - `starts_with`: Prefix check\n - `ends_with`: Suffix check\n- `pattern`: Pattern or string to match\n\n**All conditions must match for rule to trigger.**\n\n## Message Body\n\nThe markdown content after frontmatter is shown to Claude when the rule triggers.\n\n**Good messages:**\n- Explain what was detected\n- Explain why it's problematic\n- Suggest alternatives or best practices\n- Use formatting for clarity (bold, lists, etc.)\n\n**Example:**\n```markdown\n⚠️ **Console.log detected!**\n\nYou're adding console.log to production code.\n\n**Why this matters:**\n- Debug logs shouldn't ship to production\n- Console.log can expose sensitive data\n- Impacts browser performance\n\n**Alternatives:**\n- Use a proper logging library\n- Remove before committing\n- Use conditional debug builds\n```\n\n## Event Type Guide\n\n### bash Events\n\nMatch Bash command patterns:\n\n```markdown\n---\nevent: bash\npattern: sudo\\s+|rm\\s+-rf|chmod\\s+777\n---\n\nDangerous command detected!\n```\n\n**Common patterns:**\n- Dangerous commands: `rm\\s+-rf`, `dd\\s+if=`, `mkfs`\n- Privilege escalation: `sudo\\s+`, `su\\s+`\n- Permission issues: `chmod\\s+777`, `chown\\s+root`\n\n### file Events\n\nMatch Edit/Write/MultiEdit operations:\n\n```markdown\n---\nevent: file\npattern: console\\.log\\(|eval\\(|innerHTML\\s*=\n---\n\nPotentially problematic code pattern detected!\n```\n\n**Match on different fields:**\n```markdown\n---\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.tsx?$\n - field: new_text\n operator: regex_match\n pattern: console\\.log\\(\n---\n\nConsole.log in TypeScript file!\n```\n\n**Common patterns:**\n- Debug code: `console\\.log\\(`, `debugger`, `print\\(`\n- Security risks: `eval\\(`, `innerHTML\\s*=`, `dangerouslySetInnerHTML`\n- Sensitive files: `\\.env$`, `credentials`, `\\.pem$`\n- Generated files: `node_modules/`, `dist/`, `build/`\n\n### stop Events\n\nMatch when agent wants to stop (completion checks):\n\n```markdown\n---\nevent: stop\npattern: .*\n---\n\nBefore stopping, verify:\n- [ ] Tests were run\n- [ ] Build succeeded\n- [ ] Documentation updated\n```\n\n**Use for:**\n- Reminders about required steps\n- Completion checklists\n- Process enforcement\n\n### prompt Events\n\nMatch user prompt content (advanced):\n\n```markdown\n---\nevent: prompt\nconditions:\n - field: user_prompt\n operator: contains\n pattern: deploy to production\n---\n\nProduction deployment checklist:\n- [ ] Tests passing?\n- [ ] Reviewed by team?\n- [ ] Monitoring ready?\n```\n\n## Pattern Writing Tips\n\n### Regex Basics\n\n**Literal characters:** Most characters match themselves\n- `rm` matches \"rm\"\n- `console.log` matches \"console.log\"\n\n**Special characters need escaping:**\n- `.` (any char) → `\\.` (literal dot)\n- `(` `)` → `\\(` `\\)` (literal parens)\n- `[` `]` → `\\[` `\\]` (literal brackets)\n\n**Common metacharacters:**\n- `\\s` - whitespace (space, tab, newline)\n- `\\d` - digit (0-9)\n- `\\w` - word character (a-z, A-Z, 0-9, _)\n- `.` - any character\n- `+` - one or more\n- `*` - zero or more\n- `?` - zero or one\n- `|` - OR\n\n**Examples:**\n```\nrm\\s+-rf Matches: rm -rf, rm -rf\nconsole\\.log\\( Matches: console.log(\n(eval|exec)\\( Matches: eval( or exec(\nchmod\\s+777 Matches: chmod 777, chmod 777\nAPI_KEY\\s*= Matches: API_KEY=, API_KEY =\n```\n\n### Testing Patterns\n\nTest regex patterns before using:\n\n```bash\npython3 -c \"import re; print(re.search(r'your_pattern', 'test text'))\"\n```\n\nOr use online regex testers (regex101.com with Python flavor).\n\n### Common Pitfalls\n\n**Too broad:**\n```yaml\npattern: log # Matches \"log\", \"login\", \"dialog\", \"catalog\"\n```\nBetter: `console\\.log\\(|logger\\.`\n\n**Too specific:**\n```yaml\npattern: rm -rf /tmp # Only matches exact path\n```\nBetter: `rm\\s+-rf`\n\n**Escaping issues:**\n- YAML quoted strings: `\"pattern\"` requires double backslashes `\\\\s`\n- YAML unquoted: `pattern: \\s` works as-is\n- **Recommendation**: Use unquoted patterns in YAML\n\n## File Organization\n\n**Location:** All rules in `.claude/` directory\n**Naming:** `.claude/hookify.{descriptive-name}.local.md`\n**Gitignore:** Add `.claude/*.local.md` to `.gitignore`\n\n**Good names:**\n- `hookify.dangerous-rm.local.md`\n- `hookify.console-log.local.md`\n- `hookify.require-tests.local.md`\n- `hookify.sensitive-files.local.md`\n\n**Bad names:**\n- `hookify.rule1.local.md` (not descriptive)\n- `hookify.md` (missing .local)\n- `danger.local.md` (missing hookify prefix)\n\n## Workflow\n\n### Creating a Rule\n\n1. Identify unwanted behavior\n2. Determine which tool is involved (Bash, Edit, etc.)\n3. Choose event type (bash, file, stop, etc.)\n4. Write regex pattern\n5. Create `.claude/hookify.{name}.local.md` file in project root\n6. Test immediately - rules are read dynamically on next tool use\n\n### Refining a Rule\n\n1. Edit the `.local.md` file\n2. Adjust pattern or message\n3. Test immediately - changes take effect on next tool use\n\n### Disabling a Rule\n\n**Temporary:** Set `enabled: false` in frontmatter\n**Permanent:** Delete the `.local.md` file\n\n## Examples\n\nSee `${CLAUDE_PLUGIN_ROOT}/examples/` for complete examples:\n- `dangerous-rm.local.md` - Block dangerous rm commands\n- `console-log-warning.local.md` - Warn about console.log\n- `sensitive-files-warning.local.md` - Warn about editing .env files\n\n## Quick Reference\n\n**Minimum viable rule:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: bash\npattern: dangerous_command\n---\n\nWarning message here\n```\n\n**Rule with conditions:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.ts$\n - field: new_text\n operator: contains\n pattern: any\n---\n\nWarning message\n```\n\n**Event types:**\n- `bash` - Bash commands\n- `file` - File edits\n- `stop` - Completion checks\n- `prompt` - User input\n- `all` - All events\n\n**Field options:**\n- Bash: `command`\n- File: `file_path`, `new_text`, `old_text`, `content`\n- Prompt: `user_prompt`\n\n**Operators:**\n- `regex_match`, `contains`, `equals`, `not_contains`, `starts_with`, `ends_with`\n","frontmatter":{"name":"Writing Hookify Rules","description":"This skill should be used when the user asks to \"create a hookify rule\", \"write a hook rule\", \"configure hookify\", \"add a hookify rule\", or needs guidance on hookify rule syntax and patterns.","version":"0.1.0"},"isInternal":false,"tokens":2252,"sizeBytes":8423},{"name":"agent-creation-prompt.md","path":"plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# AI-Assisted Agent Generation Template\n\nUse this template to generate agents using Claude with the agent creation system prompt.\n\n## Usage Pattern\n\n### Step 1: Describe Your Agent Need\n\nThink about:\n- What task should the agent handle?\n- When should it be triggered?\n- Should it be proactive or reactive?\n- What are the key responsibilities?\n\n### Step 2: Use the Generation Prompt\n\nSend this to Claude (with the agent-creation-system-prompt loaded):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nReturn ONLY the JSON object, no other text.\n```\n\n**Replace [YOUR DESCRIPTION] with your agent requirements.**\n\n### Step 3: Claude Returns JSON\n\nClaude will return:\n\n```json\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are... **Your Core Responsibilities:**...\"\n}\n```\n\n### Step 4: Convert to Agent File\n\nCreate `agents/[identifier].md`:\n\n```markdown\n---\nname: [identifier from JSON]\ndescription: [whenToUse from JSON]\nmodel: inherit\ncolor: [choose: blue/cyan/green/yellow/magenta/red]\ntools: [\"Read\", \"Write\", \"Grep\"] # Optional: restrict tools\n---\n\n[systemPrompt from JSON]\n```\n\n## Example 1: Code Review Agent\n\n**Your request:**\n```\nI need an agent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be called after code is written and provide specific feedback.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"code-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\\n\\n\\nContext: User just implemented a new feature\\nuser: \\\"I've added the authentication feature\\\"\\nassistant: \\\"Great! Let me review the code quality.\\\"\\n\\nCode was written, trigger code-quality-reviewer agent for review.\\n\\nassistant: \\\"I'll use the code-quality-reviewer agent to analyze the changes.\\\"\\n\\n\\n\\nContext: User explicitly requests review\\nuser: \\\"Can you review my code for issues?\\\"\\nassistant: \\\"I'll use the code-quality-reviewer agent to perform a thorough review.\\\"\\n\\nExplicit review request triggers the agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer specializing in identifying issues in software implementations.\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues (readability, maintainability, performance)\\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\\n3. Check adherence to project best practices and coding standards\\n4. Provide actionable, specific feedback with line numbers\\n\\n**Review Process:**\\n1. Read the code changes using available tools\\n2. Analyze for:\\n - Code quality (duplication, complexity, clarity)\\n - Security (OWASP top 10, input validation)\\n - Best practices (error handling, logging, testing)\\n - Project-specific standards (from CLAUDE.md)\\n3. Identify issues with severity (critical/major/minor)\\n4. Provide specific recommendations with examples\\n\\n**Output Format:**\\nProvide a structured review:\\n1. Summary (2-3 sentences)\\n2. Critical Issues (must fix)\\n3. Major Issues (should fix)\\n4. Minor Issues (nice to fix)\\n5. Positive observations\\n6. Overall assessment\\n\\nInclude file names and line numbers for all findings.\"\n}\n```\n\n**You create:**\n\nFile: `agents/code-quality-reviewer.md`\n\n```markdown\n---\nname: code-quality-reviewer\ndescription: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode was written, trigger code-quality-reviewer agent for review.\n\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n - Code quality (duplication, complexity, clarity)\n - Security (OWASP top 10, input validation)\n - Best practices (error handling, logging, testing)\n - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings.\n```\n\n## Example 2: Test Generation Agent\n\n**Your request:**\n```\nCreate an agent that generates unit tests for code. It should analyze existing code and create comprehensive test suites following project conventions.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"test-generator\",\n \"whenToUse\": \"Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\\n\\n\\nContext: User wrote new functions without tests\\nuser: \\\"I've implemented the user authentication functions\\\"\\nassistant: \\\"Great! Let me generate tests for these functions.\\\"\\n\\nNew code without tests, proactively trigger test-generator.\\n\\nassistant: \\\"I'll use the test-generator agent to create comprehensive tests.\\\"\\n\",\n \"systemPrompt\": \"You are an expert test engineer specializing in creating comprehensive unit tests...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code to understand behavior\\n2. Generate test cases covering happy paths and edge cases\\n3. Follow project testing conventions\\n4. Ensure high code coverage\\n\\n**Test Generation Process:**\\n1. Read target code\\n2. Identify testable units (functions, classes, methods)\\n3. Design test cases (inputs, expected outputs, edge cases)\\n4. Generate tests following project patterns\\n5. Add assertions and error cases\\n\\n**Output Format:**\\nGenerate complete test files with:\\n- Test suite structure\\n- Setup/teardown if needed\\n- Descriptive test names\\n- Comprehensive assertions\"\n}\n```\n\n**You create:** `agents/test-generator.md` with the structure above.\n\n## Example 3: Documentation Agent\n\n**Your request:**\n```\nBuild an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs.\n```\n\n**Result:** Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation.\n\n## Tips for Effective Agent Generation\n\n### Be Specific in Your Request\n\n**Vague:**\n```\n\"I need an agent that helps with code\"\n```\n\n**Specific:**\n```\n\"I need an agent that reviews pull requests for type safety issues in TypeScript, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage\"\n```\n\n### Include Triggering Preferences\n\nTell Claude when the agent should activate:\n\n```\n\"Create an agent that generates tests. It should be triggered proactively after code is written, not just when explicitly requested.\"\n```\n\n### Mention Project Context\n\n```\n\"Create a code review agent. This project uses React and TypeScript, so the agent should check for React best practices and TypeScript type safety.\"\n```\n\n### Define Output Expectations\n\n```\n\"Create an agent that analyzes performance. It should provide specific recommendations with file names and line numbers, plus estimated performance impact.\"\n```\n\n## Validation After Generation\n\nAlways validate generated agents:\n\n```bash\n# Validate structure\n./scripts/validate-agent.sh agents/your-agent.md\n\n# Check triggering works\n# Test with scenarios from examples\n```\n\n## Iterating on Generated Agents\n\nIf generated agent needs improvement:\n\n1. Identify what's missing or wrong\n2. Manually edit the agent file\n3. Focus on:\n - Better examples in description\n - More specific system prompt\n - Clearer process steps\n - Better output format definition\n4. Re-validate\n5. Test again\n\n## Advantages of AI-Assisted Generation\n\n- **Comprehensive**: Claude includes edge cases and quality checks\n- **Consistent**: Follows proven patterns\n- **Fast**: Seconds vs manual writing\n- **Examples**: Auto-generates triggering examples\n- **Complete**: Provides full system prompt structure\n\n## When to Edit Manually\n\nEdit generated agents when:\n- Need very specific project patterns\n- Require custom tool combinations\n- Want unique persona or style\n- Integrating with existing agents\n- Need precise triggering conditions\n\nStart with generation, then refine manually for best results.\n","isInternal":false,"tokens":2078,"sizeBytes":9390},{"name":"complete-agent-examples.md","path":"plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# Complete Agent Examples\n\nFull, production-ready agent examples for common use cases. Use these as templates for your own agents.\n\n## Example 1: Code Review Agent\n\n**File:** `agents/code-reviewer.md`\n\n```markdown\n---\nname: code-reviewer\ndescription: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the payment processing feature\"\nassistant: \"Great! Let me review the implementation.\"\n\nCode written for payment processing (security-critical). Proactively trigger\ncode-reviewer agent to check for security issues and best practices.\n\nassistant: \"I'll use the code-reviewer agent to analyze the payment code.\"\n\n\n\nContext: User explicitly requests code review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a comprehensive review.\"\n\nExplicit code review request triggers the agent.\n\n\n\n\nContext: Before committing code\nuser: \"I'm ready to commit these changes\"\nassistant: \"Let me review them first.\"\n\nBefore commit, proactively review code quality.\n\nassistant: \"I'll use the code-reviewer agent to validate the changes.\"\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, complexity)\n2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.)\n3. Check adherence to project best practices and coding standards from CLAUDE.md\n4. Provide specific, actionable feedback with file and line number references\n5. Recognize and commend good practices\n\n**Code Review Process:**\n1. **Gather Context**: Use Glob to find recently modified files (git diff, git status)\n2. **Read Code**: Use Read tool to examine changed files\n3. **Analyze Quality**:\n - Check for code duplication (DRY principle)\n - Assess complexity and readability\n - Verify error handling\n - Check for proper logging\n4. **Security Analysis**:\n - Scan for injection vulnerabilities (SQL, command, XSS)\n - Check authentication and authorization\n - Verify input validation and sanitization\n - Look for hardcoded secrets or credentials\n5. **Best Practices**:\n - Follow project-specific standards from CLAUDE.md\n - Check naming conventions\n - Verify test coverage\n - Assess documentation\n6. **Categorize Issues**: Group by severity (critical/major/minor)\n7. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every issue includes file path and line number (e.g., `src/auth.ts:42`)\n- Issues categorized by severity with clear criteria\n- Recommendations are specific and actionable (not vague)\n- Include code examples in recommendations when helpful\n- Balance criticism with recognition of good practices\n\n**Output Format:**\n## Code Review Summary\n[2-3 sentence overview of changes and overall quality]\n\n## Critical Issues (Must Fix)\n- `src/file.ts:42` - [Issue description] - [Why critical] - [How to fix]\n\n## Major Issues (Should Fix)\n- `src/file.ts:15` - [Issue description] - [Impact] - [Recommendation]\n\n## Minor Issues (Consider Fixing)\n- `src/file.ts:88` - [Issue description] - [Suggestion]\n\n## Positive Observations\n- [Good practice 1]\n- [Good practice 2]\n\n## Overall Assessment\n[Final verdict and recommendations]\n\n**Edge Cases:**\n- No issues found: Provide positive validation, mention what was checked\n- Too many issues (>20): Group by type, prioritize top 10 critical/major\n- Unclear code intent: Note ambiguity and request clarification\n- Missing context (no CLAUDE.md): Apply general best practices\n- Large changeset: Focus on most impactful files first\n```\n\n## Example 2: Test Generator Agent\n\n**File:** `agents/test-generator.md`\n\n```markdown\n---\nname: test-generator\ndescription: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples:\n\n\nContext: User implemented functions without tests\nuser: \"I've added the data validation functions\"\nassistant: \"Let me generate tests for these.\"\n\nNew code without tests. Proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly requests tests\nuser: \"Generate unit tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: green\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n---\n\nYou are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.\n\n**Your Core Responsibilities:**\n1. Generate high-quality unit tests with excellent coverage\n2. Follow project testing conventions and patterns\n3. Include happy path, edge cases, and error scenarios\n4. Ensure tests are maintainable and clear\n\n**Test Generation Process:**\n1. **Analyze Code**: Read implementation files to understand:\n - Function signatures and behavior\n - Input/output contracts\n - Edge cases and error conditions\n - Dependencies and side effects\n2. **Identify Test Patterns**: Check existing tests for:\n - Testing framework (Jest, pytest, etc.)\n - File organization (test/ directory, *.test.ts, etc.)\n - Naming conventions\n - Setup/teardown patterns\n3. **Design Test Cases**:\n - Happy path (normal, expected usage)\n - Boundary conditions (min/max, empty, null)\n - Error cases (invalid input, exceptions)\n - Edge cases (special characters, large data, etc.)\n4. **Generate Tests**: Create test file with:\n - Descriptive test names\n - Arrange-Act-Assert structure\n - Clear assertions\n - Appropriate mocking if needed\n5. **Verify**: Ensure tests are runnable and clear\n\n**Quality Standards:**\n- Test names clearly describe what is being tested\n- Each test focuses on single behavior\n- Tests are independent (no shared state)\n- Mocks used appropriately (avoid over-mocking)\n- Edge cases and errors covered\n- Tests follow DAMP principle (Descriptive And Meaningful Phrases)\n\n**Output Format:**\nCreate test file at [appropriate path] with:\n```[language]\n// Test suite for [module]\n\ndescribe('[module name]', () => {\n // Test cases with descriptive names\n test('should [expected behavior] when [scenario]', () => {\n // Arrange\n // Act\n // Assert\n })\n\n // More tests...\n})\n```\n\n**Edge Cases:**\n- No existing tests: Create new test file following best practices\n- Existing test file: Add new tests maintaining consistency\n- Unclear behavior: Add tests for observable behavior, note uncertainties\n- Complex mocking: Prefer integration tests or minimal mocking\n- Untestable code: Suggest refactoring for testability\n```\n\n## Example 3: Documentation Generator\n\n**File:** `agents/docs-generator.md`\n\n```markdown\n---\nname: docs-generator\ndescription: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:\n\n\nContext: User implemented new public API\nuser: \"I've added the user management API endpoints\"\nassistant: \"Let me document these endpoints.\"\n\nNew public API needs documentation. Proactively trigger docs-generator.\n\nassistant: \"I'll use the docs-generator agent to create API documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Generate docs for this module\"\nassistant: \"I'll use the docs-generator agent to create comprehensive documentation.\"\n\nExplicit documentation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: cyan\ntools: [\"Read\", \"Write\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.\n\n**Your Core Responsibilities:**\n1. Generate accurate, clear documentation from code\n2. Follow project documentation standards\n3. Include examples and usage patterns\n4. Ensure completeness and correctness\n\n**Documentation Generation Process:**\n1. **Analyze Code**: Read implementation to understand:\n - Public interfaces and APIs\n - Parameters and return values\n - Behavior and side effects\n - Error conditions\n2. **Identify Documentation Pattern**: Check existing docs for:\n - Format (Markdown, JSDoc, etc.)\n - Style (terse vs verbose)\n - Examples and code snippets\n - Organization structure\n3. **Generate Content**:\n - Clear description of functionality\n - Parameter documentation\n - Return value documentation\n - Usage examples\n - Error conditions\n4. **Format**: Follow project conventions\n5. **Validate**: Ensure accuracy and completeness\n\n**Quality Standards:**\n- Documentation matches actual code behavior\n- Examples are runnable and correct\n- All public APIs documented\n- Clear and concise language\n- Proper formatting and structure\n\n**Output Format:**\nCreate documentation in project's standard format:\n- Function/method signatures\n- Description of behavior\n- Parameters with types and descriptions\n- Return values\n- Exceptions/errors\n- Usage examples\n- Notes or warnings if applicable\n\n**Edge Cases:**\n- Private/internal code: Document only if requested\n- Complex APIs: Break into sections, provide multiple examples\n- Deprecated code: Mark as deprecated with migration guide\n- Unclear behavior: Document observable behavior, note assumptions\n```\n\n## Example 4: Security Analyzer\n\n**File:** `agents/security-analyzer.md`\n\n```markdown\n---\nname: security-analyzer\ndescription: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples:\n\n\nContext: User implemented authentication logic\nuser: \"I've added JWT token validation\"\nassistant: \"Let me check the security.\"\n\nAuthentication code is security-critical. Proactively trigger security-analyzer.\n\nassistant: \"I'll use the security-analyzer agent to review for security vulnerabilities.\"\n\n\n\nContext: User requests security check\nuser: \"Check my code for security issues\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nExplicit security review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: red\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Identify security vulnerabilities (OWASP Top 10 and beyond)\n2. Analyze authentication and authorization logic\n3. Check input validation and sanitization\n4. Verify secure data handling and storage\n5. Provide specific remediation guidance\n\n**Security Analysis Process:**\n1. **Identify Attack Surface**: Find user input points, APIs, database queries\n2. **Check Common Vulnerabilities**:\n - Injection (SQL, command, XSS, etc.)\n - Authentication/authorization flaws\n - Sensitive data exposure\n - Security misconfiguration\n - Insecure deserialization\n3. **Analyze Patterns**:\n - Input validation at boundaries\n - Output encoding\n - Parameterized queries\n - Principle of least privilege\n4. **Assess Risk**: Categorize by severity and exploitability\n5. **Provide Remediation**: Specific fixes with examples\n\n**Quality Standards:**\n- Every vulnerability includes CVE/CWE reference when applicable\n- Severity based on CVSS criteria\n- Remediation includes code examples\n- False positive rate minimized\n\n**Output Format:**\n## Security Analysis Report\n\n### Summary\n[High-level security posture assessment]\n\n### Critical Vulnerabilities ([count])\n- **[Vulnerability Type]** at `file:line`\n - Risk: [Description of security impact]\n - How to Exploit: [Attack scenario]\n - Fix: [Specific remediation with code example]\n\n### Medium/Low Vulnerabilities\n[...]\n\n### Security Best Practices Recommendations\n[...]\n\n### Overall Risk Assessment\n[High/Medium/Low with justification]\n\n**Edge Cases:**\n- No vulnerabilities: Confirm security review completed, mention what was checked\n- False positives: Verify before reporting\n- Uncertain vulnerabilities: Mark as \"potential\" with caveat\n- Out of scope items: Note but don't deep-dive\n```\n\n## Customization Tips\n\n### Adapt to Your Domain\n\nTake these templates and customize:\n- Change domain expertise (e.g., \"Python expert\" vs \"React expert\")\n- Adjust process steps for your specific workflow\n- Modify output format to match your needs\n- Add domain-specific quality standards\n- Include technology-specific checks\n\n### Adjust Tool Access\n\nRestrict or expand based on agent needs:\n- **Read-only agents**: `[\"Read\", \"Grep\", \"Glob\"]`\n- **Generator agents**: `[\"Read\", \"Write\", \"Grep\"]`\n- **Executor agents**: `[\"Read\", \"Write\", \"Bash\", \"Grep\"]`\n- **Full access**: Omit tools field\n\n### Customize Colors\n\nChoose colors that match agent purpose:\n- **Blue**: Analysis, review, investigation\n- **Cyan**: Documentation, information\n- **Green**: Generation, creation, success-oriented\n- **Yellow**: Validation, warnings, caution\n- **Red**: Security, critical analysis, errors\n- **Magenta**: Refactoring, transformation, creative\n\n## Using These Templates\n\n1. Copy template that matches your use case\n2. Replace placeholders with your specifics\n3. Customize process steps for your domain\n4. Adjust examples to your triggering scenarios\n5. Validate with `scripts/validate-agent.sh`\n6. Test triggering with real scenarios\n7. Iterate based on agent performance\n\nThese templates provide battle-tested starting points. Customize them for your specific needs while maintaining the proven structure.\n","isInternal":false,"tokens":3041,"sizeBytes":14117},{"name":"agent-creation-system-prompt.md","path":"plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Agent Creation System Prompt\n\nThis is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.\n\n## The Prompt\n\n```\nYou are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.\n\n**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.\n\nWhen a user describes what they want an agent to do, you will:\n\n1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.\n\n2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.\n\n3. **Architect Comprehensive Instructions**: Develop a system prompt that:\n - Establishes clear behavioral boundaries and operational parameters\n - Provides specific methodologies and best practices for task execution\n - Anticipates edge cases and provides guidance for handling them\n - Incorporates any specific requirements or preferences mentioned by the user\n - Defines output format expectations when relevant\n - Aligns with project-specific coding standards and patterns from CLAUDE.md\n\n4. **Optimize for Performance**: Include:\n - Decision-making frameworks appropriate to the domain\n - Quality control mechanisms and self-verification steps\n - Efficient workflow patterns\n - Clear escalation or fallback strategies\n\n5. **Create Identifier**: Design a concise, descriptive identifier that:\n - Uses lowercase letters, numbers, and hyphens only\n - Is typically 2-4 words joined by hyphens\n - Clearly indicates the agent's primary function\n - Is memorable and easy to type\n - Avoids generic terms like \"helper\" or \"assistant\"\n\n6. **Example agent descriptions**:\n - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.\n - Examples should be of the form:\n \n Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.\n user: \"Please write a function that checks if a number is prime\"\n assistant: \"Here is the relevant function: \"\n \n \n Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.\n \n assistant: \"Now let me use the code-reviewer agent to review the code\"\n \n - If the user mentioned or implied that the agent should be used proactively, you should include examples of this.\n - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.\n\nYour output must be a valid JSON object with exactly these fields:\n{\n \"identifier\": \"A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')\",\n \"whenToUse\": \"A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.\",\n \"systemPrompt\": \"The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness\"\n}\n\nKey principles for your system prompts:\n- Be specific rather than generic - avoid vague instructions\n- Include concrete examples when they would clarify behavior\n- Balance comprehensiveness with clarity - every instruction should add value\n- Ensure the agent has enough context to handle variations of the core task\n- Make the agent proactive in seeking clarification when needed\n- Build in quality assurance and self-correction mechanisms\n\nRemember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.\n```\n\n## Usage Pattern\n\nUse this prompt to generate agent configurations:\n\n```markdown\n**User input:** \"I need an agent that reviews pull requests for code quality issues\"\n\n**You send to Claude with the system prompt above:**\nCreate an agent configuration based on this request: \"I need an agent that reviews pull requests for code quality issues\"\n\n**Claude returns JSON:**\n{\n \"identifier\": \"pr-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\\n\\n\\nContext: User has created a PR and wants quality review\\nuser: \\\"Can you review PR #123 for code quality?\\\"\\nassistant: \\\"I'll use the pr-quality-reviewer agent to analyze the PR.\\\"\\n\\nPR review request triggers the pr-quality-reviewer agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues\\n2. Check adherence to best practices\\n...\"\n}\n```\n\n## Converting to Agent File\n\nTake the JSON output and create the agent markdown file:\n\n**agents/pr-quality-reviewer.md:**\n```markdown\n---\nname: pr-quality-reviewer\ndescription: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n\nPR review request triggers the pr-quality-reviewer agent.\n\n\n\nmodel: inherit\ncolor: blue\n---\n\nYou are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n...\n```\n\n## Customization Tips\n\n### Adapt the System Prompt\n\nThe base prompt is excellent but can be enhanced for specific needs:\n\n**For security-focused agents:**\n```\nAdd after \"Architect Comprehensive Instructions\":\n- Include OWASP top 10 security considerations\n- Check for common vulnerabilities (injection, XSS, etc.)\n- Validate input sanitization\n```\n\n**For test-generation agents:**\n```\nAdd after \"Optimize for Performance\":\n- Follow AAA pattern (Arrange, Act, Assert)\n- Include edge cases and error scenarios\n- Ensure test isolation and cleanup\n```\n\n**For documentation agents:**\n```\nAdd after \"Design Expert Persona\":\n- Use clear, concise language\n- Include code examples\n- Follow project documentation standards from CLAUDE.md\n```\n\n## Best Practices from Internal Implementation\n\n### 1. Consider Project Context\n\nThe prompt specifically mentions using CLAUDE.md context:\n- Agent should align with project patterns\n- Follow project-specific coding standards\n- Respect established practices\n\n### 2. Proactive Agent Design\n\nInclude examples showing proactive usage:\n```\n\nContext: After writing code, agent should review proactively\nuser: \"Please write a function...\"\nassistant: \"[Writes function]\"\n\nCode written, now use review agent proactively.\n\nassistant: \"Now let me review this code with the code-reviewer agent\"\n\n```\n\n### 3. Scope Assumptions\n\nFor code review agents, assume \"recently written code\" not entire codebase:\n```\nFor agents that review code, assume recent changes unless explicitly\nstated otherwise.\n```\n\n### 4. Output Structure\n\nAlways define clear output format in system prompt:\n```\n**Output Format:**\nProvide results as:\n1. Summary (2-3 sentences)\n2. Detailed findings (bullet points)\n3. Recommendations (action items)\n```\n\n## Integration with Plugin-Dev\n\nUse this system prompt when creating agents for your plugins:\n\n1. Take user request for agent functionality\n2. Feed to Claude with this system prompt\n3. Get JSON output (identifier, whenToUse, systemPrompt)\n4. Convert to agent markdown file with frontmatter\n5. Validate with agent validation rules\n6. Test triggering conditions\n7. Add to plugin's `agents/` directory\n\nThis provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.\n","isInternal":false,"tokens":1838,"sizeBytes":8879},{"name":"system-prompt-design.md","path":"plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# System Prompt Design Patterns\n\nComplete guide to writing effective agent system prompts that enable autonomous, high-quality operation.\n\n## Core Structure\n\nEvery agent system prompt should follow this proven structure:\n\n```markdown\nYou are [specific role] specializing in [specific domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility - the main task]\n2. [Secondary responsibility - supporting task]\n3. [Additional responsibilities as needed]\n\n**[Task Name] Process:**\n1. [First concrete step]\n2. [Second concrete step]\n3. [Continue with clear steps]\n[...]\n\n**Quality Standards:**\n- [Standard 1 with specifics]\n- [Standard 2 with specifics]\n- [Standard 3 with specifics]\n\n**Output Format:**\nProvide results structured as:\n- [Component 1]\n- [Component 2]\n- [Include specific formatting requirements]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [Specific handling approach]\n- [Edge case 2]: [Specific handling approach]\n```\n\n## Pattern 1: Analysis Agents\n\nFor agents that analyze code, PRs, or documentation:\n\n```markdown\nYou are an expert [domain] analyzer specializing in [specific analysis type].\n\n**Your Core Responsibilities:**\n1. Thoroughly analyze [what] for [specific issues]\n2. Identify [patterns/problems/opportunities]\n3. Provide actionable recommendations\n\n**Analysis Process:**\n1. **Gather Context**: Read [what] using available tools\n2. **Initial Scan**: Identify obvious [issues/patterns]\n3. **Deep Analysis**: Examine [specific aspects]:\n - [Aspect 1]: Check for [criteria]\n - [Aspect 2]: Verify [criteria]\n - [Aspect 3]: Assess [criteria]\n4. **Synthesize Findings**: Group related issues\n5. **Prioritize**: Rank by [severity/impact/urgency]\n6. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every finding includes file:line reference\n- Issues categorized by severity (critical/major/minor)\n- Recommendations are specific and actionable\n- Positive observations included for balance\n\n**Output Format:**\n## Summary\n[2-3 sentence overview]\n\n## Critical Issues\n- [file:line] - [Issue description] - [Recommendation]\n\n## Major Issues\n[...]\n\n## Minor Issues\n[...]\n\n## Recommendations\n[...]\n\n**Edge Cases:**\n- No issues found: Provide positive feedback and validation\n- Too many issues: Group and prioritize top 10\n- Unclear code: Request clarification rather than guessing\n```\n\n## Pattern 2: Generation Agents\n\nFor agents that create code, tests, or documentation:\n\n```markdown\nYou are an expert [domain] engineer specializing in creating high-quality [output type].\n\n**Your Core Responsibilities:**\n1. Generate [what] that meets [quality standards]\n2. Follow [specific conventions/patterns]\n3. Ensure [correctness/completeness/clarity]\n\n**Generation Process:**\n1. **Understand Requirements**: Analyze what needs to be created\n2. **Gather Context**: Read existing [code/docs/tests] for patterns\n3. **Design Structure**: Plan [architecture/organization/flow]\n4. **Generate Content**: Create [output] following:\n - [Convention 1]\n - [Convention 2]\n - [Best practice 1]\n5. **Validate**: Verify [correctness/completeness]\n6. **Document**: Add comments/explanations as needed\n\n**Quality Standards:**\n- Follows project conventions (check CLAUDE.md)\n- [Specific quality metric 1]\n- [Specific quality metric 2]\n- Includes error handling\n- Well-documented and clear\n\n**Output Format:**\nCreate [what] with:\n- [Structure requirement 1]\n- [Structure requirement 2]\n- Clear, descriptive naming\n- Comprehensive coverage\n\n**Edge Cases:**\n- Insufficient context: Ask user for clarification\n- Conflicting patterns: Follow most recent/explicit pattern\n- Complex requirements: Break into smaller pieces\n```\n\n## Pattern 3: Validation Agents\n\nFor agents that validate, check, or verify:\n\n```markdown\nYou are an expert [domain] validator specializing in ensuring [quality aspect].\n\n**Your Core Responsibilities:**\n1. Validate [what] against [criteria]\n2. Identify violations and issues\n3. Provide clear pass/fail determination\n\n**Validation Process:**\n1. **Load Criteria**: Understand validation requirements\n2. **Scan Target**: Read [what] needs validation\n3. **Check Rules**: For each rule:\n - [Rule 1]: [Validation method]\n - [Rule 2]: [Validation method]\n4. **Collect Violations**: Document each failure with details\n5. **Assess Severity**: Categorize issues\n6. **Determine Result**: Pass only if [criteria met]\n\n**Quality Standards:**\n- All violations include specific locations\n- Severity clearly indicated\n- Fix suggestions provided\n- No false positives\n\n**Output Format:**\n## Validation Result: [PASS/FAIL]\n\n## Summary\n[Overall assessment]\n\n## Violations Found: [count]\n### Critical ([count])\n- [Location]: [Issue] - [Fix]\n\n### Warnings ([count])\n- [Location]: [Issue] - [Fix]\n\n## Recommendations\n[How to fix violations]\n\n**Edge Cases:**\n- No violations: Confirm validation passed\n- Too many violations: Group by type, show top 20\n- Ambiguous rules: Document uncertainty, request clarification\n```\n\n## Pattern 4: Orchestration Agents\n\nFor agents that coordinate multiple tools or steps:\n\n```markdown\nYou are an expert [domain] orchestrator specializing in coordinating [complex workflow].\n\n**Your Core Responsibilities:**\n1. Coordinate [multi-step process]\n2. Manage [resources/tools/dependencies]\n3. Ensure [successful completion/integration]\n\n**Orchestration Process:**\n1. **Plan**: Understand full workflow and dependencies\n2. **Prepare**: Set up prerequisites\n3. **Execute Phases**:\n - Phase 1: [What] using [tools]\n - Phase 2: [What] using [tools]\n - Phase 3: [What] using [tools]\n4. **Monitor**: Track progress and handle failures\n5. **Verify**: Confirm successful completion\n6. **Report**: Provide comprehensive summary\n\n**Quality Standards:**\n- Each phase completes successfully\n- Errors handled gracefully\n- Progress reported to user\n- Final state verified\n\n**Output Format:**\n## Workflow Execution Report\n\n### Completed Phases\n- [Phase]: [Result]\n\n### Results\n- [Output 1]\n- [Output 2]\n\n### Next Steps\n[If applicable]\n\n**Edge Cases:**\n- Phase failure: Attempt retry, then report and stop\n- Missing dependencies: Request from user\n- Timeout: Report partial completion\n```\n\n## Writing Style Guidelines\n\n### Tone and Voice\n\n**Use second person (addressing the agent):**\n```\n✅ You are responsible for...\n✅ You will analyze...\n✅ Your process should...\n\n❌ The agent is responsible for...\n❌ This agent will analyze...\n❌ I will analyze...\n```\n\n### Clarity and Specificity\n\n**Be specific, not vague:**\n```\n✅ Check for SQL injection by examining all database queries for parameterization\n❌ Look for security issues\n\n✅ Provide file:line references for each finding\n❌ Show where issues are\n\n✅ Categorize as critical (security), major (bugs), or minor (style)\n❌ Rate the severity of issues\n```\n\n### Actionable Instructions\n\n**Give concrete steps:**\n```\n✅ Read the file using the Read tool, then search for patterns using Grep\n❌ Analyze the code\n\n✅ Generate test file at test/path/to/file.test.ts\n❌ Create tests\n```\n\n## Common Pitfalls\n\n### ❌ Vague Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Help the user with their code\n2. Provide assistance\n3. Be helpful\n```\n\n**Why bad:** Not specific enough to guide behavior.\n\n### ✅ Specific Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Analyze TypeScript code for type safety issues\n2. Identify missing type annotations and improper 'any' usage\n3. Recommend specific type improvements with examples\n```\n\n### ❌ Missing Process Steps\n\n```markdown\nAnalyze the code and provide feedback.\n```\n\n**Why bad:** Agent doesn't know HOW to analyze.\n\n### ✅ Clear Process\n\n```markdown\n**Analysis Process:**\n1. Read code files using Read tool\n2. Scan for type annotations on all functions\n3. Check for 'any' type usage\n4. Verify generic type parameters\n5. List findings with file:line references\n```\n\n### ❌ Undefined Output\n\n```markdown\nProvide a report.\n```\n\n**Why bad:** Agent doesn't know what format to use.\n\n### ✅ Defined Output Format\n\n```markdown\n**Output Format:**\n## Type Safety Report\n\n### Summary\n[Overview of findings]\n\n### Issues Found\n- `file.ts:42` - Missing return type on `processData`\n- `utils.ts:15` - Unsafe 'any' usage in parameter\n\n### Recommendations\n[Specific fixes with examples]\n```\n\n## Length Guidelines\n\n### Minimum Viable Agent\n\n**~500 words minimum:**\n- Role description\n- 3 core responsibilities\n- 5-step process\n- Output format\n\n### Standard Agent\n\n**~1,000-2,000 words:**\n- Detailed role and expertise\n- 5-8 responsibilities\n- 8-12 process steps\n- Quality standards\n- Output format\n- 3-5 edge cases\n\n### Comprehensive Agent\n\n**~2,000-5,000 words:**\n- Complete role with background\n- Comprehensive responsibilities\n- Detailed multi-phase process\n- Extensive quality standards\n- Multiple output formats\n- Many edge cases\n- Examples within system prompt\n\n**Avoid > 10,000 words:** Too long, diminishing returns.\n\n## Testing System Prompts\n\n### Test Completeness\n\nCan the agent handle these based on system prompt alone?\n\n- [ ] Typical task execution\n- [ ] Edge cases mentioned\n- [ ] Error scenarios\n- [ ] Unclear requirements\n- [ ] Large/complex inputs\n- [ ] Empty/missing inputs\n\n### Test Clarity\n\nRead the system prompt and ask:\n\n- Can another developer understand what this agent does?\n- Are process steps clear and actionable?\n- Is output format unambiguous?\n- Are quality standards measurable?\n\n### Iterate Based on Results\n\nAfter testing agent:\n1. Identify where it struggled\n2. Add missing guidance to system prompt\n3. Clarify ambiguous instructions\n4. Add process steps for edge cases\n5. Re-test\n\n## Conclusion\n\nEffective system prompts are:\n- **Specific**: Clear about what and how\n- **Structured**: Organized with clear sections\n- **Complete**: Covers normal and edge cases\n- **Actionable**: Provides concrete steps\n- **Testable**: Defines measurable standards\n\nUse the patterns above as templates, customize for your domain, and iterate based on agent performance.\n","isInternal":false,"tokens":2326,"sizeBytes":9998},{"name":"triggering-examples.md","path":"plugins/plugin-dev/skills/agent-development/references/triggering-examples.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/agent-development/references/triggering-examples.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Agent Triggering Examples: Best Practices\n\nComplete guide to writing effective `` blocks in agent descriptions for reliable triggering.\n\n## Example Block Format\n\nThe standard format for triggering examples:\n\n```markdown\n\nContext: [Describe the situation - what led to this interaction]\nuser: \"[Exact user message or request]\"\nassistant: \"[How Claude should respond before triggering]\"\n\n[Explanation of why this agent should be triggered in this scenario]\n\nassistant: \"[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']\"\n\n```\n\n## Anatomy of a Good Example\n\n### Context\n\n**Purpose:** Set the scene - what happened before the user's message\n\n**Good contexts:**\n```\nContext: User just implemented a new authentication feature\nContext: User has created a PR and wants it reviewed\nContext: User is debugging a test failure\nContext: After writing several functions without documentation\n```\n\n**Bad contexts:**\n```\nContext: User needs help (too vague)\nContext: Normal usage (not specific)\n```\n\n### User Message\n\n**Purpose:** Show the exact phrasing that should trigger the agent\n\n**Good user messages:**\n```\nuser: \"I've added the OAuth flow, can you check it?\"\nuser: \"Review PR #123\"\nuser: \"Why is this test failing?\"\nuser: \"Add docs for these functions\"\n```\n\n**Vary the phrasing:**\nInclude multiple examples with different phrasings for the same intent:\n```\nExample 1: user: \"Review my code\"\nExample 2: user: \"Can you check this implementation?\"\nExample 3: user: \"Look over my changes\"\n```\n\n### Assistant Response (Before Triggering)\n\n**Purpose:** Show what Claude says before launching the agent\n\n**Good responses:**\n```\nassistant: \"I'll analyze your OAuth implementation.\"\nassistant: \"Let me review that PR for you.\"\nassistant: \"I'll investigate the test failure.\"\n```\n\n**Proactive example:**\n```\nassistant: \"Great! Now let me review the code quality.\"\n\nCode was just written, proactively trigger review agent.\n\n```\n\n### Commentary\n\n**Purpose:** Explain the reasoning - WHY this agent should trigger\n\n**Good commentary:**\n```\n\nUser explicitly requested code review, trigger the code-reviewer agent.\n\n\n\nAfter code implementation, proactively use review agent to check quality.\n\n\n\nPR analysis request matches pr-analyzer agent's expertise.\n\n```\n\n**Include decision logic:**\n```\n\nUser wrote tests (Test tool used). The test-analyzer agent should check\ntest quality and coverage before continuing.\n\n```\n\n### Assistant Response (Triggering)\n\n**Purpose:** Show how Claude invokes the agent\n\n**Standard pattern:**\n```\nassistant: \"I'll use the [agent-name] agent to [what it will do].\"\n```\n\n**Examples:**\n```\nassistant: \"I'll use the code-reviewer agent to analyze the changes.\"\nassistant: \"Let me use the test-generator agent to create comprehensive tests.\"\nassistant: \"I'll use the security-analyzer agent to check for vulnerabilities.\"\n```\n\n## Example Types\n\n### Type 1: Explicit Request\n\nUser directly asks for what the agent does:\n\n```markdown\n\nContext: User explicitly requests security analysis\nuser: \"Check my code for security vulnerabilities\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nDirect security analysis request triggers the security-analyzer agent.\n\n\n```\n\n### Type 2: Proactive Triggering\n\nAgent triggers after relevant work without explicit request:\n\n```markdown\n\nContext: User just implemented database queries\nuser: \"I've added the user search functionality\"\nassistant: \"Great! Let me review it for security.\"\n\nDatabase code written. Proactively trigger security-analyzer to check\nfor SQL injection and other database security issues.\n\nassistant: \"I'll use the security-analyzer agent to check the database code.\"\n\n```\n\n### Type 3: Implicit Request\n\nUser implies need without stating it directly:\n\n```markdown\n\nContext: User mentions code is hard to understand\nuser: \"This code is confusing and hard to follow\"\nassistant: \"I can help improve the code clarity.\"\n\nUser indicates complexity issues. Trigger code-simplifier agent to refactor\nfor better readability.\n\nassistant: \"I'll use the code-simplifier agent to suggest improvements.\"\n\n```\n\n### Type 4: Tool Usage Pattern\n\nAgent triggers based on prior tool usage:\n\n```markdown\n\nContext: User made multiple edits to test files\nuser: \"I've updated all the tests\"\nassistant: \"Great! Let me verify test quality.\"\n\nMultiple Edit tools used on test files. Proactively trigger test-quality-analyzer\nto ensure tests follow best practices.\n\nassistant: \"I'll use the test-quality-analyzer agent to review the tests.\"\n\n```\n\n## Multiple Examples Strategy\n\n### Cover Different Phrasings\n\n```markdown\n\nuser: \"Review my code\"\n[...]\n\n\n\nuser: \"Can you check my implementation?\"\n[...]\n\n\n\nuser: \"Look over these changes\"\n[...]\n\n```\n\n### Cover Proactive and Reactive\n\n```markdown\n\nContext: User explicitly requests review\nuser: \"Review my code for issues\"\n[...]\n\n\n\nContext: After user writes code\nuser: \"I've implemented the feature\"\nassistant: \"Great! Now let me review it.\"\n\nCode written, proactively review.\n\n[...]\n\n```\n\n### Cover Edge Cases\n\n```markdown\n\nContext: Typical usage\nuser: \"Check my PR\"\n[...]\n\n\n\nContext: Large PR that needs thorough analysis\nuser: \"This is a big PR, can you do a deep review?\"\n[...]\n\nLarge PR mentioned, use thorough analysis mode.\n\n\n```\n\n## Common Mistakes\n\n### ❌ Missing Context\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent.\"\n\n```\n\n**Why bad:** No context about what led to this request.\n\n### ✅ With Context\n\n```markdown\n\nContext: User just finished implementing authentication\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to analyze the auth implementation.\"\n\nAuth code written, review for security and best practices.\n\n\n```\n\n### ❌ No Commentary\n\n```markdown\n\nContext: User requests review\nuser: \"Check my changes\"\nassistant: \"I'll use the reviewer agent.\"\n\n```\n\n**Why bad:** Doesn't explain WHY agent triggers.\n\n### ✅ With Commentary\n\n```markdown\n\nContext: User requests review after making changes\nuser: \"Check my changes\"\nassistant: \"I'll use the code-reviewer agent to analyze the modifications.\"\n\nCode review request triggers agent to check quality, security, and adherence to standards.\n\n\n```\n\n### ❌ Agent Responds Directly\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I found the following issues: [lists issues]\"\n\n```\n\n**Why bad:** Shows agent's output, not triggering.\n\n### ✅ Shows Triggering\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to perform the review.\"\n\nReview request triggers the agent.\n\n\n```\n\n## How Many Examples?\n\n### Minimum: 2 Examples\n\nCover at least:\n1. Explicit request\n2. One variation or proactive trigger\n\n### Recommended: 3-4 Examples\n\nCover:\n1. Explicit request (direct ask)\n2. Implicit request (user implies need)\n3. Proactive trigger (after relevant work)\n4. Edge case or specific scenario\n\n### Maximum: 6 Examples\n\nMore than 6 makes description too long. Focus on most important scenarios.\n\n## Template Library\n\n### Code Review Agent\n\n```markdown\n\nContext: User just implemented a new feature\nuser: \"I've added the user registration feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode written, proactively trigger code-reviewer agent.\n\nassistant: \"I'll use the code-reviewer agent to analyze the implementation.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my changes for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n```\n\n### Test Generation Agent\n\n```markdown\n\nContext: User implemented functions without tests\nuser: \"I've added the data processing functions\"\nassistant: \"Great! Let me generate tests for these.\"\n\nNew code without tests, proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly asks for tests\nuser: \"Generate tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n```\n\n### Documentation Agent\n\n```markdown\n\nContext: User added new API endpoints\nuser: \"I've implemented the REST API endpoints\"\nassistant: \"I'll document these endpoints.\"\n\nNew API code, proactively generate documentation.\n\nassistant: \"I'll use the api-docs-writer agent to create comprehensive documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Write docs for this API\"\nassistant: \"I'll use the api-docs-writer agent to generate clear documentation.\"\n\nDocumentation request triggers the agent.\n\n\n```\n\n### Validation Agent\n\n```markdown\n\nContext: User ready to commit changes\nuser: \"I'm ready to commit this code\"\nassistant: \"Let me validate it first.\"\n\nBefore commit, proactively validate with validation-agent.\n\nassistant: \"I'll use the code-validator agent to check for issues.\"\n\n\n\nContext: User asks for validation\nuser: \"Validate my implementation\"\nassistant: \"I'll use the code-validator agent to verify correctness.\"\n\nExplicit validation request triggers the agent.\n\n\n```\n\n## Debugging Triggering Issues\n\n### Agent Not Triggering\n\n**Check:**\n1. Examples include relevant keywords from user message\n2. Context matches actual usage scenarios\n3. Commentary explains triggering logic clearly\n4. Assistant shows use of Agent tool in examples\n\n**Fix:**\nAdd more examples covering different phrasings.\n\n### Agent Triggers Too Often\n\n**Check:**\n1. Examples are too broad or generic\n2. Triggering conditions overlap with other agents\n3. Commentary doesn't distinguish when NOT to use\n\n**Fix:**\nMake examples more specific, add negative examples.\n\n### Agent Triggers in Wrong Scenarios\n\n**Check:**\n1. Examples don't match actual intended use\n2. Commentary suggests inappropriate triggering\n\n**Fix:**\nRevise examples to show only correct triggering scenarios.\n\n## Best Practices Summary\n\n✅ **DO:**\n- Include 2-4 concrete, specific examples\n- Show both explicit and proactive triggering\n- Provide clear context for each example\n- Explain reasoning in commentary\n- Vary user message phrasing\n- Show Claude using Agent tool\n\n❌ **DON'T:**\n- Use generic, vague examples\n- Omit context or commentary\n- Show only one type of triggering\n- Skip the agent invocation step\n- Make examples too similar\n- Forget to explain why agent triggers\n\n## Conclusion\n\nWell-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.\n","isInternal":false,"tokens":2621,"sizeBytes":11613},{"name":"SKILL.md","path":"plugins/plugin-dev/skills/agent-development/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/agent-development/SKILL.md","title":"Agent Development","category":"anthropic-skill","format":"markdown","content":"---\nname: Agent Development\ndescription: This skill should be used when the user asks to \"create an agent\", \"add an agent\", \"write a subagent\", \"agent frontmatter\", \"when to use description\", \"agent examples\", \"agent tools\", \"agent colors\", \"autonomous agent\", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.\nversion: 0.1.0\n---\n\n# Agent Development for Claude Code Plugins\n\n## Overview\n\nAgents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.\n\n**Key concepts:**\n- Agents are FOR autonomous work, commands are FOR user-initiated actions\n- Markdown file format with YAML frontmatter\n- Triggering via description field with examples\n- System prompt defines agent behavior\n- Model and color customization\n\n## Agent File Structure\n\n### Complete Format\n\n```markdown\n---\nname: agent-identifier\ndescription: Use this agent when [triggering conditions]. Examples:\n\n\nContext: [Situation description]\nuser: \"[User request]\"\nassistant: \"[How assistant should respond and use this agent]\"\n\n[Why this agent should be triggered]\n\n\n\n\n[Additional example...]\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Write\", \"Grep\"]\n---\n\nYou are [agent role description]...\n\n**Your Core Responsibilities:**\n1. [Responsibility 1]\n2. [Responsibility 2]\n\n**Analysis Process:**\n[Step-by-step workflow]\n\n**Output Format:**\n[What to return]\n```\n\n## Frontmatter Fields\n\n### name (required)\n\nAgent identifier used for namespacing and invocation.\n\n**Format:** lowercase, numbers, hyphens only\n**Length:** 3-50 characters\n**Pattern:** Must start and end with alphanumeric\n\n**Good examples:**\n- `code-reviewer`\n- `test-generator`\n- `api-docs-writer`\n- `security-analyzer`\n\n**Bad examples:**\n- `helper` (too generic)\n- `-agent-` (starts/ends with hyphen)\n- `my_agent` (underscores not allowed)\n- `ag` (too short, < 3 chars)\n\n### description (required)\n\nDefines when Claude should trigger this agent. **This is the most critical field.**\n\n**Must include:**\n1. Triggering conditions (\"Use this agent when...\")\n2. Multiple `` blocks showing usage\n3. Context, user request, and assistant response in each example\n4. `` explaining why agent triggers\n\n**Format:**\n```\nUse this agent when [conditions]. Examples:\n\n\nContext: [Scenario description]\nuser: \"[What user says]\"\nassistant: \"[How Claude should respond]\"\n\n[Why this agent is appropriate]\n\n\n\n[More examples...]\n```\n\n**Best practices:**\n- Include 2-4 concrete examples\n- Show proactive and reactive triggering\n- Cover different phrasings of same intent\n- Explain reasoning in commentary\n- Be specific about when NOT to use the agent\n\n### model (required)\n\nWhich model the agent should use.\n\n**Options:**\n- `inherit` - Use same model as parent (recommended)\n- `sonnet` - Claude Sonnet (balanced)\n- `opus` - Claude Opus (most capable, expensive)\n- `haiku` - Claude Haiku (fast, cheap)\n\n**Recommendation:** Use `inherit` unless agent needs specific model capabilities.\n\n### color (required)\n\nVisual identifier for agent in UI.\n\n**Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`\n\n**Guidelines:**\n- Choose distinct colors for different agents in same plugin\n- Use consistent colors for similar agent types\n- Blue/cyan: Analysis, review\n- Green: Success-oriented tasks\n- Yellow: Caution, validation\n- Red: Critical, security\n- Magenta: Creative, generation\n\n### tools (optional)\n\nRestrict agent to specific tools.\n\n**Format:** Array of tool names\n\n```yaml\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n```\n\n**Default:** If omitted, agent has access to all tools\n\n**Best practice:** Limit tools to minimum needed (principle of least privilege)\n\n**Common tool sets:**\n- Read-only analysis: `[\"Read\", \"Grep\", \"Glob\"]`\n- Code generation: `[\"Read\", \"Write\", \"Grep\"]`\n- Testing: `[\"Read\", \"Bash\", \"Grep\"]`\n- Full access: Omit field or use `[\"*\"]`\n\n## System Prompt Design\n\nThe markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.\n\n### Structure\n\n**Standard template:**\n```markdown\nYou are [role] specializing in [domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility]\n2. [Secondary responsibility]\n3. [Additional responsibilities...]\n\n**Analysis Process:**\n1. [Step one]\n2. [Step two]\n3. [Step three]\n[...]\n\n**Quality Standards:**\n- [Standard 1]\n- [Standard 2]\n\n**Output Format:**\nProvide results in this format:\n- [What to include]\n- [How to structure]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [How to handle]\n- [Edge case 2]: [How to handle]\n```\n\n### Best Practices\n\n✅ **DO:**\n- Write in second person (\"You are...\", \"You will...\")\n- Be specific about responsibilities\n- Provide step-by-step process\n- Define output format\n- Include quality standards\n- Address edge cases\n- Keep under 10,000 characters\n\n❌ **DON'T:**\n- Write in first person (\"I am...\", \"I will...\")\n- Be vague or generic\n- Omit process steps\n- Leave output format undefined\n- Skip quality guidance\n- Ignore error cases\n\n## Creating Agents\n\n### Method 1: AI-Assisted Generation\n\nUse this prompt pattern (extracted from Claude Code):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nRequirements:\n1. Extract core intent and responsibilities\n2. Design expert persona for the domain\n3. Create comprehensive system prompt with:\n - Clear behavioral boundaries\n - Specific methodologies\n - Edge case handling\n - Output format\n4. Create identifier (lowercase, hyphens, 3-50 chars)\n5. Write description with triggering conditions\n6. Include 2-3 blocks showing when to use\n\nReturn JSON with:\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are...\"\n}\n```\n\nThen convert to agent file format with frontmatter.\n\nSee `examples/agent-creation-prompt.md` for complete template.\n\n### Method 2: Manual Creation\n\n1. Choose agent identifier (3-50 chars, lowercase, hyphens)\n2. Write description with examples\n3. Select model (usually `inherit`)\n4. Choose color for visual identification\n5. Define tools (if restricting access)\n6. Write system prompt with structure above\n7. Save as `agents/agent-name.md`\n\n## Validation Rules\n\n### Identifier Validation\n\n```\n✅ Valid: code-reviewer, test-gen, api-analyzer-v2\n❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)\n```\n\n**Rules:**\n- 3-50 characters\n- Lowercase letters, numbers, hyphens only\n- Must start and end with alphanumeric\n- No underscores, spaces, or special characters\n\n### Description Validation\n\n**Length:** 10-5,000 characters\n**Must include:** Triggering conditions and examples\n**Best:** 200-1,000 characters with 2-4 examples\n\n### System Prompt Validation\n\n**Length:** 20-10,000 characters\n**Best:** 500-3,000 characters\n**Structure:** Clear responsibilities, process, output format\n\n## Agent Organization\n\n### Plugin Agents Directory\n\n```\nplugin-name/\n└── agents/\n ├── analyzer.md\n ├── reviewer.md\n └── generator.md\n```\n\nAll `.md` files in `agents/` are auto-discovered.\n\n### Namespacing\n\nAgents are namespaced automatically:\n- Single plugin: `agent-name`\n- With subdirectories: `plugin:subdir:agent-name`\n\n## Testing Agents\n\n### Test Triggering\n\nCreate test scenarios to verify agent triggers correctly:\n\n1. Write agent with specific triggering examples\n2. Use similar phrasing to examples in test\n3. Check Claude loads the agent\n4. Verify agent provides expected functionality\n\n### Test System Prompt\n\nEnsure system prompt is complete:\n\n1. Give agent typical task\n2. Check it follows process steps\n3. Verify output format is correct\n4. Test edge cases mentioned in prompt\n5. Confirm quality standards are met\n\n## Quick Reference\n\n### Minimal Agent\n\n```markdown\n---\nname: simple-agent\ndescription: Use this agent when... Examples: ...\nmodel: inherit\ncolor: blue\n---\n\nYou are an agent that [does X].\n\nProcess:\n1. [Step 1]\n2. [Step 2]\n\nOutput: [What to provide]\n```\n\n### Frontmatter Fields Summary\n\n| Field | Required | Format | Example |\n|-------|----------|--------|---------|\n| name | Yes | lowercase-hyphens | code-reviewer |\n| description | Yes | Text + examples | Use when... ... |\n| model | Yes | inherit/sonnet/opus/haiku | inherit |\n| color | Yes | Color name | blue |\n| tools | No | Array of tool names | [\"Read\", \"Grep\"] |\n\n### Best Practices\n\n**DO:**\n- ✅ Include 2-4 concrete examples in description\n- ✅ Write specific triggering conditions\n- ✅ Use `inherit` for model unless specific need\n- ✅ Choose appropriate tools (least privilege)\n- ✅ Write clear, structured system prompts\n- ✅ Test agent triggering thoroughly\n\n**DON'T:**\n- ❌ Use generic descriptions without examples\n- ❌ Omit triggering conditions\n- ❌ Give all agents same color\n- ❌ Grant unnecessary tool access\n- ❌ Write vague system prompts\n- ❌ Skip testing\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed guidance, consult:\n\n- **`references/system-prompt-design.md`** - Complete system prompt patterns\n- **`references/triggering-examples.md`** - Example formats and best practices\n- **`references/agent-creation-system-prompt.md`** - The exact prompt from Claude Code\n\n### Example Files\n\nWorking examples in `examples/`:\n\n- **`agent-creation-prompt.md`** - AI-assisted agent generation template\n- **`complete-agent-examples.md`** - Full agent examples for different use cases\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-agent.sh`** - Validate agent file structure\n- **`test-agent-trigger.sh`** - Test if agent triggers correctly\n\n## Implementation Workflow\n\nTo create an agent for a plugin:\n\n1. Define agent purpose and triggering conditions\n2. Choose creation method (AI-assisted or manual)\n3. Create `agents/agent-name.md` file\n4. Write frontmatter with all required fields\n5. Write system prompt following best practices\n6. Include 2-4 triggering examples in description\n7. Validate with `scripts/validate-agent.sh`\n8. Test triggering with real scenarios\n9. Document agent in plugin README\n\nFocus on clear triggering conditions and comprehensive system prompts for autonomous operation.\n","frontmatter":{"name":"Agent Development","description":"This skill should be used when the user asks to \"create an agent\", \"add an agent\", \"write a subagent\", \"agent frontmatter\", \"when to use description\", \"agent examples\", \"agent tools\", \"agent colors\", \"autonomous agent\", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.","version":"0.1.0"},"isInternal":false,"tokens":2490,"sizeBytes":10430},{"name":"plugin-commands.md","path":"plugins/plugin-dev/skills/command-development/examples/plugin-commands.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# Plugin Command Examples\n\nPractical examples of commands designed for Claude Code plugins, demonstrating plugin-specific patterns and features.\n\n## Table of Contents\n\n1. [Simple Plugin Command](#1-simple-plugin-command)\n2. [Script-Based Analysis](#2-script-based-analysis)\n3. [Template-Based Generation](#3-template-based-generation)\n4. [Multi-Script Workflow](#4-multi-script-workflow)\n5. [Configuration-Driven Deployment](#5-configuration-driven-deployment)\n6. [Agent Integration](#6-agent-integration)\n7. [Skill Integration](#7-skill-integration)\n8. [Multi-Component Workflow](#8-multi-component-workflow)\n9. [Validated Input Command](#9-validated-input-command)\n10. [Environment-Aware Command](#10-environment-aware-command)\n\n---\n\n## 1. Simple Plugin Command\n\n**Use case:** Basic command that uses plugin script\n\n**File:** `commands/analyze.md`\n\n```markdown\n---\ndescription: Analyze code quality using plugin tools\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nAnalyze @$1 using plugin's quality checker:\n\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/quality-check.js $1`\n\nReview the analysis output and provide:\n1. Summary of findings\n2. Priority issues to address\n3. Suggested improvements\n4. Code quality score interpretation\n```\n\n**Key features:**\n- Uses `${CLAUDE_PLUGIN_ROOT}` for portable path\n- Combines file reference with script execution\n- Simple single-purpose command\n\n---\n\n## 2. Script-Based Analysis\n\n**Use case:** Run comprehensive analysis using multiple plugin scripts\n\n**File:** `commands/full-audit.md`\n\n```markdown\n---\ndescription: Complete code audit using plugin suite\nargument-hint: [directory]\nallowed-tools: Bash(*)\nmodel: sonnet\n---\n\nRunning complete audit on $1:\n\n**Security scan:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh $1`\n\n**Performance analysis:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-analyze.sh $1`\n\n**Best practices check:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/best-practices.sh $1`\n\nAnalyze all results and create comprehensive report including:\n- Critical issues requiring immediate attention\n- Performance optimization opportunities\n- Security vulnerabilities and fixes\n- Overall health score and recommendations\n```\n\n**Key features:**\n- Multiple script executions\n- Organized output sections\n- Comprehensive workflow\n- Clear reporting structure\n\n---\n\n## 3. Template-Based Generation\n\n**Use case:** Generate documentation following plugin template\n\n**File:** `commands/gen-api-docs.md`\n\n```markdown\n---\ndescription: Generate API documentation from template\nargument-hint: [api-file]\n---\n\nTemplate structure: @${CLAUDE_PLUGIN_ROOT}/templates/api-documentation.md\n\nAPI implementation: @$1\n\nGenerate complete API documentation following the template format above.\n\nEnsure documentation includes:\n- Endpoint descriptions with HTTP methods\n- Request/response schemas\n- Authentication requirements\n- Error codes and handling\n- Usage examples with curl commands\n- Rate limiting information\n\nFormat output as markdown suitable for README or docs site.\n```\n\n**Key features:**\n- Uses plugin template\n- Combines template with source file\n- Standardized output format\n- Clear documentation structure\n\n---\n\n## 4. Multi-Script Workflow\n\n**Use case:** Orchestrate build, test, and deploy workflow\n\n**File:** `commands/release.md`\n\n```markdown\n---\ndescription: Execute complete release workflow\nargument-hint: [version]\nallowed-tools: Bash(*), Read\n---\n\nExecuting release workflow for version $1:\n\n**Step 1 - Pre-release validation:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-release-check.sh $1`\n\n**Step 2 - Build artifacts:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build-release.sh $1`\n\n**Step 3 - Run test suite:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh`\n\n**Step 4 - Package release:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh $1`\n\nReview all step outputs and report:\n1. Any failures or warnings\n2. Build artifacts location\n3. Test results summary\n4. Next steps for deployment\n5. Rollback plan if needed\n```\n\n**Key features:**\n- Multi-step workflow\n- Sequential script execution\n- Clear step numbering\n- Comprehensive reporting\n\n---\n\n## 5. Configuration-Driven Deployment\n\n**Use case:** Deploy using environment-specific plugin configuration\n\n**File:** `commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nDeployment configuration for $1: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nCurrent git state: !`git rev-parse --short HEAD`\n\nBuild info: !`cat package.json | grep -E '(name|version)'`\n\nExecute deployment to $1 environment using configuration above.\n\nDeployment checklist:\n1. Validate configuration settings\n2. Build application for $1\n3. Run pre-deployment tests\n4. Deploy to target environment\n5. Run smoke tests\n6. Verify deployment success\n7. Update deployment log\n\nReport deployment status and any issues encountered.\n```\n\n**Key features:**\n- Environment-specific configuration\n- Dynamic config file loading\n- Pre-deployment validation\n- Structured checklist\n\n---\n\n## 6. Agent Integration\n\n**Use case:** Command that launches plugin agent for complex task\n\n**File:** `commands/deep-review.md`\n\n```markdown\n---\ndescription: Deep code review using plugin agent\nargument-hint: [file-or-directory]\n---\n\nInitiate comprehensive code review of @$1 using the code-reviewer agent.\n\nThe agent will perform:\n1. **Static analysis** - Check for code smells and anti-patterns\n2. **Security audit** - Identify potential vulnerabilities\n3. **Performance review** - Find optimization opportunities\n4. **Best practices** - Ensure code follows standards\n5. **Documentation check** - Verify adequate documentation\n\nThe agent has access to:\n- Plugin's linting rules: ${CLAUDE_PLUGIN_ROOT}/config/lint-rules.json\n- Security checklist: ${CLAUDE_PLUGIN_ROOT}/checklists/security.md\n- Performance guidelines: ${CLAUDE_PLUGIN_ROOT}/docs/performance.md\n\nNote: This uses the Task tool to launch the plugin's code-reviewer agent for thorough analysis.\n```\n\n**Key features:**\n- Delegates to plugin agent\n- Documents agent capabilities\n- References plugin resources\n- Clear scope definition\n\n---\n\n## 7. Skill Integration\n\n**Use case:** Command that leverages plugin skill for specialized knowledge\n\n**File:** `commands/document-api.md`\n\n```markdown\n---\ndescription: Document API following plugin standards\nargument-hint: [api-file]\n---\n\nAPI source code: @$1\n\nGenerate API documentation following the plugin's API documentation standards.\n\nUse the api-documentation-standards skill to ensure:\n- **OpenAPI compliance** - Follow OpenAPI 3.0 specification\n- **Consistent formatting** - Use plugin's documentation style\n- **Complete coverage** - Document all endpoints and schemas\n- **Example quality** - Provide realistic usage examples\n- **Error documentation** - Cover all error scenarios\n\nThe skill provides:\n- Standard documentation templates\n- API documentation best practices\n- Common patterns for this codebase\n- Quality validation criteria\n\nGenerate production-ready API documentation.\n```\n\n**Key features:**\n- Invokes plugin skill by name\n- Documents skill purpose\n- Clear expectations\n- Leverages skill knowledge\n\n---\n\n## 8. Multi-Component Workflow\n\n**Use case:** Complex workflow using agents, skills, and scripts\n\n**File:** `commands/complete-review.md`\n\n```markdown\n---\ndescription: Comprehensive review using all plugin components\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget file: @$1\n\nExecute comprehensive review workflow:\n\n**Phase 1: Automated Analysis**\nRun plugin analyzer: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\n**Phase 2: Deep Review (Agent)**\nLaunch the code-quality-reviewer agent for detailed analysis.\nAgent will examine:\n- Code structure and organization\n- Error handling patterns\n- Testing coverage\n- Documentation quality\n\n**Phase 3: Standards Check (Skill)**\nUse the coding-standards skill to validate:\n- Naming conventions\n- Code formatting\n- Best practices adherence\n- Framework-specific patterns\n\n**Phase 4: Report Generation**\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nCompile all findings into comprehensive report following template.\n\n**Phase 5: Recommendations**\nGenerate prioritized action items:\n1. Critical issues (must fix)\n2. Important improvements (should fix)\n3. Nice-to-have enhancements (could fix)\n\nInclude specific file locations and suggested changes for each item.\n```\n\n**Key features:**\n- Multi-phase workflow\n- Combines scripts, agents, skills\n- Template-based reporting\n- Prioritized outputs\n\n---\n\n## 9. Validated Input Command\n\n**Use case:** Command with input validation and error handling\n\n**File:** `commands/build-env.md`\n\n```markdown\n---\ndescription: Build for specific environment with validation\nargument-hint: [environment]\nallowed-tools: Bash(*)\n---\n\nValidate environment argument: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" && echo \"VALID\" || echo \"INVALID\"`\n\nCheck build script exists: !`test -x ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh && echo \"EXISTS\" || echo \"MISSING\"`\n\nVerify configuration available: !`test -f ${CLAUDE_PLUGIN_ROOT}/config/$1.json && echo \"FOUND\" || echo \"NOT_FOUND\"`\n\nIf all validations pass:\n\n**Configuration:** @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\n**Execute build:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh $1 2>&1`\n\n**Validation results:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-build.sh $1 2>&1`\n\nReport build status and any issues.\n\nIf validations fail:\n- Explain which validation failed\n- Provide expected values/locations\n- Suggest corrective actions\n- Document troubleshooting steps\n```\n\n**Key features:**\n- Input validation\n- Resource existence checks\n- Error handling\n- Helpful error messages\n- Graceful failure handling\n\n---\n\n## 10. Environment-Aware Command\n\n**Use case:** Command that adapts behavior based on environment\n\n**File:** `commands/run-checks.md`\n\n```markdown\n---\ndescription: Run environment-appropriate checks\nargument-hint: [environment]\nallowed-tools: Bash(*), Read\n---\n\nEnvironment: $1\n\nLoad environment configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-checks.json\n\nDetermine check level: !`echo \"$1\" | grep -E \"^prod$\" && echo \"FULL\" || echo \"BASIC\"`\n\n**For production environment:**\n- Full test suite: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-full.sh`\n- Security scan: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh`\n- Performance audit: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-check.sh`\n- Compliance check: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/compliance.sh`\n\n**For non-production environments:**\n- Basic tests: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-basic.sh`\n- Quick lint: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh`\n\nAnalyze results based on environment requirements:\n\n**Production:** All checks must pass with zero critical issues\n**Staging:** No critical issues, warnings acceptable\n**Development:** Focus on blocking issues only\n\nReport status and recommend proceed/block decision.\n```\n\n**Key features:**\n- Environment-aware logic\n- Conditional execution\n- Different validation levels\n- Appropriate reporting per environment\n\n---\n\n## Common Patterns Summary\n\n### Pattern: Plugin Script Execution\n```markdown\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/script-name.js $1`\n```\nUse for: Running plugin-provided Node.js scripts\n\n### Pattern: Plugin Configuration Loading\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/config/config-name.json\n```\nUse for: Loading plugin configuration files\n\n### Pattern: Plugin Template Usage\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/templates/template-name.md\n```\nUse for: Using plugin templates for generation\n\n### Pattern: Agent Invocation\n```markdown\nLaunch the [agent-name] agent for [task description].\n```\nUse for: Delegating complex tasks to plugin agents\n\n### Pattern: Skill Reference\n```markdown\nUse the [skill-name] skill to ensure [requirements].\n```\nUse for: Leveraging plugin skills for specialized knowledge\n\n### Pattern: Input Validation\n```markdown\nValidate input: !`echo \"$1\" | grep -E \"^pattern$\" && echo \"OK\" || echo \"ERROR\"`\n```\nUse for: Validating command arguments\n\n### Pattern: Resource Validation\n```markdown\nCheck exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/path/file && echo \"YES\" || echo \"NO\"`\n```\nUse for: Verifying required plugin files exist\n\n---\n\n## Development Tips\n\n### Testing Plugin Commands\n\n1. **Test with plugin installed:**\n ```bash\n cd /path/to/plugin\n claude /command-name args\n ```\n\n2. **Verify ${CLAUDE_PLUGIN_ROOT} expansion:**\n ```bash\n # Add debug output to command\n !`echo \"Plugin root: ${CLAUDE_PLUGIN_ROOT}\"`\n ```\n\n3. **Test across different working directories:**\n ```bash\n cd /tmp && claude /command-name\n cd /other/project && claude /command-name\n ```\n\n4. **Validate resource availability:**\n ```bash\n # Check all plugin resources exist\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/scripts/`\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/config/`\n ```\n\n### Common Mistakes to Avoid\n\n1. **Using relative paths instead of ${CLAUDE_PLUGIN_ROOT}:**\n ```markdown\n # Wrong\n !`node ./scripts/analyze.js`\n\n # Correct\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n ```\n\n2. **Forgetting to allow required tools:**\n ```markdown\n # Missing allowed-tools\n !`bash script.sh` # Will fail without Bash permission\n\n # Correct\n ---\n allowed-tools: Bash(*)\n ---\n !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n ```\n\n3. **Not validating inputs:**\n ```markdown\n # Risky - no validation\n Deploy to $1 environment\n\n # Better - with validation\n Validate: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n Deploy to $1 environment (if valid)\n ```\n\n4. **Hardcoding plugin paths:**\n ```markdown\n # Wrong - breaks on different installations\n @/home/user/.claude/plugins/my-plugin/config.json\n\n # Correct - works everywhere\n @${CLAUDE_PLUGIN_ROOT}/config.json\n ```\n\n---\n\nFor detailed plugin-specific features, see `references/plugin-features-reference.md`.\nFor general command development, see main `SKILL.md`.\n","isInternal":false,"tokens":3255,"sizeBytes":13989},{"name":"simple-commands.md","path":"plugins/plugin-dev/skills/command-development/examples/simple-commands.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/examples/simple-commands.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# Simple Command Examples\n\nBasic slash command patterns for common use cases.\n\n**Important:** All examples below are written as instructions FOR Claude (agent consumption), not messages TO users. Commands tell Claude what to do, not tell users what will happen.\n\n## Example 1: Code Review Command\n\n**File:** `.claude/commands/review.md`\n\n```markdown\n---\ndescription: Review code for quality and issues\nallowed-tools: Read, Bash(git:*)\n---\n\nReview the code in this repository for:\n\n1. **Code Quality:**\n - Readability and maintainability\n - Consistent style and formatting\n - Appropriate abstraction levels\n\n2. **Potential Issues:**\n - Logic errors or bugs\n - Edge cases not handled\n - Performance concerns\n\n3. **Best Practices:**\n - Design patterns used correctly\n - Error handling present\n - Documentation adequate\n\nProvide specific feedback with file and line references.\n```\n\n**Usage:**\n```\n> /review\n```\n\n---\n\n## Example 2: Security Review Command\n\n**File:** `.claude/commands/security-review.md`\n\n```markdown\n---\ndescription: Review code for security vulnerabilities\nallowed-tools: Read, Grep\nmodel: sonnet\n---\n\nPerform comprehensive security review checking for:\n\n**Common Vulnerabilities:**\n- SQL injection risks\n- Cross-site scripting (XSS)\n- Authentication/authorization issues\n- Insecure data handling\n- Hardcoded secrets or credentials\n\n**Security Best Practices:**\n- Input validation present\n- Output encoding correct\n- Secure defaults used\n- Error messages safe\n- Logging appropriate (no sensitive data)\n\nFor each issue found:\n- File and line number\n- Severity (Critical/High/Medium/Low)\n- Description of vulnerability\n- Recommended fix\n\nPrioritize issues by severity.\n```\n\n**Usage:**\n```\n> /security-review\n```\n\n---\n\n## Example 3: Test Command with File Argument\n\n**File:** `.claude/commands/test-file.md`\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*), Bash(jest:*)\n---\n\nRun tests for $1:\n\nTest execution: !`npm test $1`\n\nAnalyze results:\n- Tests passed/failed\n- Code coverage\n- Performance issues\n- Flaky tests\n\nIf failures found, suggest fixes based on error messages.\n```\n\n**Usage:**\n```\n> /test-file src/utils/helpers.test.ts\n```\n\n---\n\n## Example 4: Documentation Generator\n\n**File:** `.claude/commands/document.md`\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1\n\nInclude:\n\n**Overview:**\n- Purpose and responsibility\n- Main functionality\n- Dependencies\n\n**API Documentation:**\n- Function/method signatures\n- Parameter descriptions with types\n- Return values with types\n- Exceptions/errors thrown\n\n**Usage Examples:**\n- Basic usage\n- Common patterns\n- Edge cases\n\n**Implementation Notes:**\n- Algorithm complexity\n- Performance considerations\n- Known limitations\n\nFormat as Markdown suitable for project documentation.\n```\n\n**Usage:**\n```\n> /document src/api/users.ts\n```\n\n---\n\n## Example 5: Git Status Summary\n\n**File:** `.claude/commands/git-status.md`\n\n```markdown\n---\ndescription: Summarize Git repository status\nallowed-tools: Bash(git:*)\n---\n\nRepository Status Summary:\n\n**Current Branch:** !`git branch --show-current`\n\n**Status:** !`git status --short`\n\n**Recent Commits:** !`git log --oneline -5`\n\n**Remote Status:** !`git fetch && git status -sb`\n\nProvide:\n- Summary of changes\n- Suggested next actions\n- Any warnings or issues\n```\n\n**Usage:**\n```\n> /git-status\n```\n\n---\n\n## Example 6: Deployment Command\n\n**File:** `.claude/commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy to specified environment\nargument-hint: [environment] [version]\nallowed-tools: Bash(kubectl:*), Read\n---\n\nDeploy to $1 environment using version $2\n\n**Pre-deployment Checks:**\n1. Verify $1 configuration exists\n2. Check version $2 is valid\n3. Verify cluster accessibility: !`kubectl cluster-info`\n\n**Deployment Steps:**\n1. Update deployment manifest with version $2\n2. Apply configuration to $1\n3. Monitor rollout status\n4. Verify pod health\n5. Run smoke tests\n\n**Rollback Plan:**\nDocument current version for rollback if issues occur.\n\nProceed with deployment? (yes/no)\n```\n\n**Usage:**\n```\n> /deploy staging v1.2.3\n```\n\n---\n\n## Example 7: Comparison Command\n\n**File:** `.claude/commands/compare-files.md`\n\n```markdown\n---\ndescription: Compare two files\nargument-hint: [file1] [file2]\n---\n\nCompare @$1 with @$2\n\n**Analysis:**\n\n1. **Differences:**\n - Lines added\n - Lines removed\n - Lines modified\n\n2. **Functional Changes:**\n - Breaking changes\n - New features\n - Bug fixes\n - Refactoring\n\n3. **Impact:**\n - Affected components\n - Required updates elsewhere\n - Migration requirements\n\n4. **Recommendations:**\n - Code review focus areas\n - Testing requirements\n - Documentation updates needed\n\nPresent as structured comparison report.\n```\n\n**Usage:**\n```\n> /compare-files src/old-api.ts src/new-api.ts\n```\n\n---\n\n## Example 8: Quick Fix Command\n\n**File:** `.claude/commands/quick-fix.md`\n\n```markdown\n---\ndescription: Quick fix for common issues\nargument-hint: [issue-description]\nmodel: haiku\n---\n\nQuickly fix: $ARGUMENTS\n\n**Approach:**\n1. Identify the issue\n2. Find relevant code\n3. Propose fix\n4. Explain solution\n\nFocus on:\n- Simple, direct solution\n- Minimal changes\n- Following existing patterns\n- No breaking changes\n\nProvide code changes with file paths and line numbers.\n```\n\n**Usage:**\n```\n> /quick-fix button not responding to clicks\n> /quick-fix typo in error message\n```\n\n---\n\n## Example 9: Research Command\n\n**File:** `.claude/commands/research.md`\n\n```markdown\n---\ndescription: Research best practices for topic\nargument-hint: [topic]\nmodel: sonnet\n---\n\nResearch best practices for: $ARGUMENTS\n\n**Coverage:**\n\n1. **Current State:**\n - How we currently handle this\n - Existing implementations\n\n2. **Industry Standards:**\n - Common patterns\n - Recommended approaches\n - Tools and libraries\n\n3. **Comparison:**\n - Our approach vs standards\n - Gaps or improvements needed\n - Migration considerations\n\n4. **Recommendations:**\n - Concrete action items\n - Priority and effort estimates\n - Resources for implementation\n\nProvide actionable guidance based on research.\n```\n\n**Usage:**\n```\n> /research error handling in async operations\n> /research API authentication patterns\n```\n\n---\n\n## Example 10: Explain Code Command\n\n**File:** `.claude/commands/explain.md`\n\n```markdown\n---\ndescription: Explain how code works\nargument-hint: [file-or-function]\n---\n\nExplain @$1 in detail\n\n**Explanation Structure:**\n\n1. **Overview:**\n - What it does\n - Why it exists\n - How it fits in system\n\n2. **Step-by-Step:**\n - Line-by-line walkthrough\n - Key algorithms or logic\n - Important details\n\n3. **Inputs and Outputs:**\n - Parameters and types\n - Return values\n - Side effects\n\n4. **Edge Cases:**\n - Error handling\n - Special cases\n - Limitations\n\n5. **Usage Examples:**\n - How to call it\n - Common patterns\n - Integration points\n\nExplain at level appropriate for junior engineer.\n```\n\n**Usage:**\n```\n> /explain src/utils/cache.ts\n> /explain AuthService.login\n```\n\n---\n\n## Key Patterns\n\n### Pattern 1: Read-Only Analysis\n\n```markdown\n---\nallowed-tools: Read, Grep\n---\n\nAnalyze but don't modify...\n```\n\n**Use for:** Code review, documentation, analysis\n\n### Pattern 2: Git Operations\n\n```markdown\n---\nallowed-tools: Bash(git:*)\n---\n\n!`git status`\nAnalyze and suggest...\n```\n\n**Use for:** Repository status, commit analysis\n\n### Pattern 3: Single Argument\n\n```markdown\n---\nargument-hint: [target]\n---\n\nProcess $1...\n```\n\n**Use for:** File operations, targeted actions\n\n### Pattern 4: Multiple Arguments\n\n```markdown\n---\nargument-hint: [source] [target] [options]\n---\n\nProcess $1 to $2 with $3...\n```\n\n**Use for:** Workflows, deployments, comparisons\n\n### Pattern 5: Fast Execution\n\n```markdown\n---\nmodel: haiku\n---\n\nQuick simple task...\n```\n\n**Use for:** Simple, repetitive commands\n\n### Pattern 6: File Comparison\n\n```markdown\nCompare @$1 with @$2...\n```\n\n**Use for:** Diff analysis, migration planning\n\n### Pattern 7: Context Gathering\n\n```markdown\n---\nallowed-tools: Bash(git:*), Read\n---\n\nContext: !`git status`\nFiles: @file1 @file2\n\nAnalyze...\n```\n\n**Use for:** Informed decision making\n\n## Tips for Writing Simple Commands\n\n1. **Start basic:** Single responsibility, clear purpose\n2. **Add complexity gradually:** Start without frontmatter\n3. **Test incrementally:** Verify each feature works\n4. **Use descriptive names:** Command name should indicate purpose\n5. **Document arguments:** Always use argument-hint\n6. **Provide examples:** Show usage in comments\n7. **Handle errors:** Consider missing arguments or files\n","isInternal":false,"tokens":2096,"sizeBytes":8675},{"name":"advanced-workflows.md","path":"plugins/plugin-dev/skills/command-development/references/advanced-workflows.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/references/advanced-workflows.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Advanced Workflow Patterns\n\nMulti-step command sequences and composition patterns for complex workflows.\n\n## Overview\n\nAdvanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks.\n\n## Multi-Step Command Patterns\n\n### Sequential Workflow Command\n\nCommands that guide users through multi-step processes:\n\n```markdown\n---\ndescription: Complete PR review workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read, Grep\n---\n\n# PR Review Workflow for #$1\n\n## Step 1: Fetch PR Details\n!`gh pr view $1 --json title,body,author,files`\n\n## Step 2: Review Files\nFiles changed: !`gh pr diff $1 --name-only`\n\nFor each file:\n- Check code quality\n- Verify tests exist\n- Review documentation\n\n## Step 3: Run Checks\nTest status: !`gh pr checks $1`\n\nVerify:\n- All tests passing\n- No merge conflicts\n- CI/CD successful\n\n## Step 4: Provide Feedback\n\nSummarize:\n- Issues found (critical/minor)\n- Suggestions for improvement\n- Approval recommendation\n\nWould you like to:\n1. Approve PR\n2. Request changes\n3. Leave comments only\n\nReply with your choice and I'll help complete the action.\n```\n\n**Key features:**\n- Numbered steps for clarity\n- Bash execution for context\n- Decision points for user input\n- Next action suggestions\n\n### State-Carrying Workflow\n\nCommands that maintain state between invocations:\n\n```markdown\n---\ndescription: Initialize deployment workflow\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment\n\nCreating deployment tracking file...\n\nCurrent branch: !`git branch --show-current`\nLatest commit: !`git log -1 --format=%H`\n\nDeployment state saved to `.claude/deployment-state.local.md`:\n\n\\`\\`\\`markdown\n---\ninitialized: true\nbranch: $(git branch --show-current)\ncommit: $(git log -1 --format=%H)\ntimestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)\nstatus: initialized\n---\n\n# Deployment Tracking\n\nBranch: $(git branch --show-current)\nStarted: $(date)\n\nNext steps:\n1. Run tests: /deploy-test\n2. Build: /deploy-build\n3. Deploy: /deploy-execute\n\\`\\`\\`\n\nState saved. Run `/deploy-test` to continue.\n```\n\n**Next command** (`/deploy-test`):\n```markdown\n---\ndescription: Run deployment tests\nallowed-tools: Read, Bash(npm:*)\n---\n\nReading deployment state from `.claude/deployment-state.local.md`...\n\nRunning tests: !`npm test`\n\nUpdating state to 'tested'...\n\nTests complete. Run `/deploy-build` to continue.\n```\n\n**Pattern benefits:**\n- Persistent state across commands\n- Clear workflow progression\n- Safety checkpoints\n- Resume capability\n\n### Conditional Workflow Branching\n\nCommands that adapt based on conditions:\n\n```markdown\n---\ndescription: Smart deployment workflow\nargument-hint: [environment]\nallowed-tools: Bash(git:*), Bash(npm:*), Read\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\nBranch: !`git branch --show-current`\nStatus: !`git status --short`\n\n**Checking conditions:**\n\n1. Branch status:\n - If main/master: Require approval\n - If feature branch: Warning about target\n - If hotfix: Fast-track process\n\n2. Tests:\n !`npm test`\n - If tests fail: STOP - fix tests first\n - If tests pass: Continue\n\n3. Environment:\n - If $1 = 'production': Extra validation\n - If $1 = 'staging': Standard process\n - If $1 = 'dev': Minimal checks\n\n**Workflow decision:**\nBased on above, proceeding with: [determined workflow]\n\n[Conditional steps based on environment and status]\n\nReady to deploy? (yes/no)\n```\n\n## Command Composition Patterns\n\n### Command Chaining\n\nCommands designed to work together:\n\n```markdown\n---\ndescription: Prepare for code review\n---\n\n# Prepare Code Review\n\nRunning preparation sequence:\n\n1. Format code: /format-code\n2. Run linter: /lint-code\n3. Run tests: /test-all\n4. Generate coverage: /coverage-report\n5. Create review summary: /review-summary\n\nThis is a meta-command. After completing each step above,\nI'll compile results and prepare comprehensive review materials.\n\nStarting sequence...\n```\n\n**Individual commands** are simple:\n- `/format-code` - Just formats\n- `/lint-code` - Just lints\n- `/test-all` - Just tests\n\n**Composition command** orchestrates them.\n\n### Pipeline Pattern\n\nCommands that process output from previous commands:\n\n```markdown\n---\ndescription: Analyze test failures\n---\n\n# Analyze Test Failures\n\n## Step 1: Get test results\n(Run /test-all first if not done)\n\nReading test output...\n\n## Step 2: Categorize failures\n- Flaky tests (random failures)\n- Consistent failures\n- New failures vs existing\n\n## Step 3: Prioritize\nRank by:\n- Impact (critical path vs edge case)\n- Frequency (always fails vs sometimes)\n- Effort (quick fix vs major work)\n\n## Step 4: Generate fix plan\nFor each failure:\n- Root cause hypothesis\n- Suggested fix approach\n- Estimated effort\n\nWould you like me to:\n1. Fix highest priority failure\n2. Generate detailed fix plans for all\n3. Create GitHub issues for each\n```\n\n### Parallel Execution Pattern\n\nCommands that coordinate multiple simultaneous operations:\n\n```markdown\n---\ndescription: Run comprehensive validation\nallowed-tools: Bash(*), Read\n---\n\n# Comprehensive Validation\n\nRunning validations in parallel...\n\nStarting:\n- Code quality checks\n- Security scanning\n- Dependency audit\n- Performance profiling\n\nThis will take 2-3 minutes. I'll monitor all processes\nand report when complete.\n\n[Poll each process and report progress]\n\nAll validations complete. Summary:\n- Quality: PASS (0 issues)\n- Security: WARN (2 minor issues)\n- Dependencies: PASS\n- Performance: PASS (baseline met)\n\nDetails:\n[Collated results from all checks]\n```\n\n## Workflow State Management\n\n### Using .local.md Files\n\nStore workflow state in plugin-specific files:\n\n```markdown\n.claude/plugin-name-workflow.local.md:\n\n---\nworkflow: deployment\nstage: testing\nstarted: 2025-01-15T10:30:00Z\nenvironment: staging\nbranch: feature/new-api\ncommit: abc123def\ntests_passed: false\nbuild_complete: false\n---\n\n# Deployment Workflow State\n\nCurrent stage: Testing\nStarted: 2025-01-15 10:30 UTC\n\nCompleted steps:\n- ✅ Validation\n- ✅ Branch check\n- ⏳ Testing (in progress)\n\nPending steps:\n- Build\n- Deploy\n- Smoke tests\n```\n\n**Reading state in commands:**\n\n```markdown\n---\ndescription: Continue deployment workflow\nallowed-tools: Read, Write\n---\n\nReading workflow state from .claude/plugin-name-workflow.local.md...\n\nCurrent stage: @.claude/plugin-name-workflow.local.md\n\n[Parse YAML frontmatter to determine next step]\n\nNext action based on state: [determined action]\n```\n\n### Workflow Recovery\n\nHandle interrupted workflows:\n\n```markdown\n---\ndescription: Resume deployment workflow\nallowed-tools: Read\n---\n\n# Resume Deployment\n\nChecking for interrupted workflow...\n\nState file: @.claude/plugin-name-workflow.local.md\n\n**Workflow found:**\n- Started: [timestamp]\n- Environment: [env]\n- Last completed: [step]\n\n**Recovery options:**\n1. Resume from last step\n2. Restart from beginning\n3. Abort and clean up\n\nWhich would you like? (1/2/3)\n```\n\n## Workflow Coordination Patterns\n\n### Cross-Command Communication\n\nCommands that signal each other:\n\n```markdown\n---\ndescription: Mark feature complete\nallowed-tools: Write\n---\n\n# Mark Feature Complete\n\nWriting completion marker...\n\nCreating: .claude/feature-complete.flag\n\nThis signals other commands that feature is ready for:\n- Integration testing (/integration-test will auto-detect)\n- Documentation generation (/docs-generate will include)\n- Release notes (/release-notes will add)\n\nFeature marked complete.\n```\n\n**Other commands check for flag:**\n\n```markdown\n---\ndescription: Generate release notes\nallowed-tools: Read, Bash(git:*)\n---\n\nChecking for completed features...\n\nif [ -f .claude/feature-complete.flag ]; then\n Feature ready for release notes\nfi\n\n[Include in release notes]\n```\n\n### Workflow Locking\n\nPrevent concurrent workflow execution:\n\n```markdown\n---\ndescription: Start deployment\nallowed-tools: Read, Write, Bash\n---\n\n# Start Deployment\n\nChecking for active deployments...\n\nif [ -f .claude/deployment.lock ]; then\n ERROR: Deployment already in progress\n Started: [timestamp from lock file]\n\n Cannot start concurrent deployment.\n Wait for completion or run /deployment-abort\n\n Exit.\nfi\n\nCreating deployment lock...\n\nDeployment started. Lock created.\n[Proceed with deployment]\n```\n\n**Lock cleanup:**\n\n```markdown\n---\ndescription: Complete deployment\nallowed-tools: Write, Bash\n---\n\nDeployment complete.\n\nRemoving deployment lock...\nrm .claude/deployment.lock\n\nReady for next deployment.\n```\n\n## Advanced Argument Handling\n\n### Optional Arguments with Defaults\n\n```markdown\n---\ndescription: Deploy with optional version\nargument-hint: [environment] [version]\n---\n\nEnvironment: ${1:-staging}\nVersion: ${2:-latest}\n\nDeploying ${2:-latest} to ${1:-staging}...\n\nNote: Using defaults for missing arguments:\n- Environment defaults to 'staging'\n- Version defaults to 'latest'\n```\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy to validated environment\nargument-hint: [environment]\n---\n\nEnvironment: $1\n\nValidating environment...\n\nvalid_envs=\"dev staging production\"\nif ! echo \"$valid_envs\" | grep -w \"$1\" > /dev/null; then\n ERROR: Invalid environment '$1'\n Valid options: dev, staging, production\n Exit.\nfi\n\nEnvironment validated. Proceeding...\n```\n\n### Argument Transformation\n\n```markdown\n---\ndescription: Deploy with shorthand\nargument-hint: [env-shorthand]\n---\n\nInput: $1\n\nExpanding shorthand:\n- d/dev → development\n- s/stg → staging\n- p/prod → production\n\ncase \"$1\" in\n d|dev) ENV=\"development\";;\n s|stg) ENV=\"staging\";;\n p|prod) ENV=\"production\";;\n *) ENV=\"$1\";;\nesac\n\nDeploying to: $ENV\n```\n\n## Error Handling in Workflows\n\n### Graceful Failure\n\n```markdown\n---\ndescription: Resilient deployment workflow\n---\n\n# Deployment Workflow\n\nRunning steps with error handling...\n\n## Step 1: Tests\n!`npm test`\n\nif [ $? -ne 0 ]; then\n ERROR: Tests failed\n\n Options:\n 1. Fix tests and retry\n 2. Skip tests (NOT recommended)\n 3. Abort deployment\n\n What would you like to do?\n\n [Wait for user input before continuing]\nfi\n\n## Step 2: Build\n[Continue only if Step 1 succeeded]\n```\n\n### Rollback on Failure\n\n```markdown\n---\ndescription: Deployment with rollback\n---\n\n# Deploy with Rollback\n\nSaving current state for rollback...\nPrevious version: !`current-version.sh`\n\nDeploying new version...\n\n!`deploy.sh`\n\nif [ $? -ne 0 ]; then\n DEPLOYMENT FAILED\n\n Initiating automatic rollback...\n !`rollback.sh`\n\n Rolled back to previous version.\n Check logs for failure details.\nfi\n\nDeployment complete.\n```\n\n### Checkpoint Recovery\n\n```markdown\n---\ndescription: Workflow with checkpoints\n---\n\n# Multi-Stage Deployment\n\n## Checkpoint 1: Validation\n!`validate.sh`\necho \"checkpoint:validation\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 2: Build\n!`build.sh`\necho \"checkpoint:build\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 3: Deploy\n!`deploy.sh`\necho \"checkpoint:deploy\" >> .claude/deployment-checkpoints.log\n\nIf any step fails, resume with:\n/deployment-resume [last-successful-checkpoint]\n```\n\n## Best Practices\n\n### Workflow Design\n\n1. **Clear progression**: Number steps, show current position\n2. **Explicit state**: Don't rely on implicit state\n3. **User control**: Provide decision points\n4. **Error recovery**: Handle failures gracefully\n5. **Progress indication**: Show what's done, what's pending\n\n### Command Composition\n\n1. **Single responsibility**: Each command does one thing well\n2. **Composable design**: Commands work together easily\n3. **Standard interfaces**: Consistent input/output formats\n4. **Loose coupling**: Commands don't depend on each other's internals\n\n### State Management\n\n1. **Persistent state**: Use .local.md files\n2. **Atomic updates**: Write complete state files atomically\n3. **State validation**: Check state file format/completeness\n4. **Cleanup**: Remove stale state files\n5. **Documentation**: Document state file formats\n\n### Error Handling\n\n1. **Fail fast**: Detect errors early\n2. **Clear messages**: Explain what went wrong\n3. **Recovery options**: Provide clear next steps\n4. **State preservation**: Keep state for recovery\n5. **Rollback capability**: Support undoing changes\n\n## Example: Complete Deployment Workflow\n\n### Initialize Command\n\n```markdown\n---\ndescription: Initialize deployment\nargument-hint: [environment]\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment to $1\n\nCreating workflow state...\n\n\\`\\`\\`yaml\n---\nworkflow: deployment\nenvironment: $1\nbranch: !`git branch --show-current`\ncommit: !`git rev-parse HEAD`\nstage: initialized\ntimestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`\n---\n\\`\\`\\`\n\nWritten to .claude/deployment-state.local.md\n\nNext: Run /deployment-validate\n```\n\n### Validation Command\n\n```markdown\n---\ndescription: Validate deployment\nallowed-tools: Read, Bash\n---\n\nReading state: @.claude/deployment-state.local.md\n\nRunning validation...\n- Branch check: PASS\n- Tests: PASS\n- Build: PASS\n\nUpdating state to 'validated'...\n\nNext: Run /deployment-execute\n```\n\n### Execution Command\n\n```markdown\n---\ndescription: Execute deployment\nallowed-tools: Read, Bash, Write\n---\n\nReading state: @.claude/deployment-state.local.md\n\nExecuting deployment to [environment]...\n\n!`deploy.sh [environment]`\n\nDeployment complete.\nUpdating state to 'completed'...\n\nCleanup: /deployment-cleanup\n```\n\n### Cleanup Command\n\n```markdown\n---\ndescription: Clean up deployment\nallowed-tools: Bash\n---\n\nRemoving deployment state...\nrm .claude/deployment-state.local.md\n\nDeployment workflow complete.\n```\n\nThis complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.\n","isInternal":false,"tokens":3183,"sizeBytes":13618},{"name":"documentation-patterns.md","path":"plugins/plugin-dev/skills/command-development/references/documentation-patterns.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/references/documentation-patterns.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Command Documentation Patterns\n\nStrategies for creating self-documenting, maintainable commands with excellent user experience.\n\n## Overview\n\nWell-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.\n\n## Self-Documenting Command Structure\n\n### Complete Command Template\n\n```markdown\n---\ndescription: Clear, actionable description under 60 chars\nargument-hint: [arg1] [arg2] [optional-arg]\nallowed-tools: Read, Bash(git:*)\nmodel: sonnet\n---\n\n\n\n# Command Implementation\n\n[Command prompt content here...]\n\n[Explain what will happen...]\n\n[Guide user through steps...]\n\n[Provide clear output...]\n```\n\n### Documentation Comment Sections\n\n**PURPOSE**: Why the command exists\n- Problem it solves\n- Use cases\n- When to use vs when not to use\n\n**USAGE**: Basic syntax\n- Command invocation pattern\n- Required vs optional arguments\n- Default values\n\n**ARGUMENTS**: Detailed argument documentation\n- Each argument described\n- Type information\n- Valid values/ranges\n- Defaults\n\n**EXAMPLES**: Concrete usage examples\n- Common use cases\n- Edge cases\n- Expected outputs\n\n**REQUIREMENTS**: Prerequisites\n- Dependencies\n- Permissions\n- Environmental setup\n\n**RELATED COMMANDS**: Connections\n- Similar commands\n- Complementary commands\n- Alternative approaches\n\n**TROUBLESHOOTING**: Common issues\n- Known problems\n- Solutions\n- Workarounds\n\n**CHANGELOG**: Version history\n- What changed when\n- Breaking changes highlighted\n- Migration guidance\n\n## In-Line Documentation Patterns\n\n### Commented Sections\n\n```markdown\n---\ndescription: Complex multi-step command\n---\n\n\n\n\nChecking prerequisites...\n- Git repository: !`git rev-parse --git-dir 2>/dev/null`\n- Branch exists: [validation logic]\n\n\n\n\nAnalyzing differences between $1 and $2...\n[Analysis logic...]\n\n\n\n\nBased on analysis, recommend:\n[Recommendations...]\n\n\n```\n\n### Inline Explanations\n\n```markdown\n---\ndescription: Deployment command with inline docs\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\n\nCurrent branch: !`git branch --show-current`\n\n\nif [ \"$1\" = \"production\" ] && [ \"$(git branch --show-current)\" != \"main\" ]; then\n ⚠️ WARNING: Not on main branch for production deploy\n This is unusual. Confirm this is intentional.\nfi\n\n\nRunning tests: !`npm test`\n\n✓ All checks passed\n\n## Deployment\n\n\n\nDeploying to $1 environment...\n[Deployment steps...]\n\n\nVerifying deployment health...\n[Health checks...]\n\nDeployment complete!\n\n## Next Steps\n\n\n1. Monitor logs: /logs $1\n2. Run smoke tests: /smoke-test $1\n3. Notify team: /notify-deployment $1\n```\n\n### Decision Point Documentation\n\n```markdown\n---\ndescription: Interactive deployment command\n---\n\n# Interactive Deployment\n\n## Configuration Review\n\nTarget: $1\nCurrent version: !`cat version.txt`\nNew version: $2\n\n\n\n\n\nReview the above configuration.\n\n**Continue with deployment?**\n- Reply \"yes\" to proceed\n- Reply \"no\" to cancel\n- Reply \"edit\" to modify configuration\n\n[Await user input before continuing...]\n\n\n\n\nProceeding with deployment...\n```\n\n## Help Text Patterns\n\n### Built-in Help Command\n\nCreate a help subcommand for complex commands:\n\n```markdown\n---\ndescription: Main command with help\nargument-hint: [subcommand] [args]\n---\n\n# Command Processor\n\nif [ \"$1\" = \"help\" ] || [ \"$1\" = \"--help\" ] || [ \"$1\" = \"-h\" ]; then\n **Command Help**\n\n USAGE:\n /command [subcommand] [args]\n\n SUBCOMMANDS:\n init [name] Initialize new configuration\n deploy [env] Deploy to environment\n status Show current status\n rollback Rollback last deployment\n help Show this help\n\n EXAMPLES:\n /command init my-project\n /command deploy staging\n /command status\n /command rollback\n\n For detailed help on a subcommand:\n /command [subcommand] --help\n\n Exit.\nfi\n\n[Regular command processing...]\n```\n\n### Contextual Help\n\nProvide help based on context:\n\n```markdown\n---\ndescription: Context-aware command\nargument-hint: [operation] [target]\n---\n\n# Context-Aware Operation\n\nif [ -z \"$1\" ]; then\n **No operation specified**\n\n Available operations:\n - analyze: Analyze target for issues\n - fix: Apply automatic fixes\n - report: Generate detailed report\n\n Usage: /command [operation] [target]\n\n Examples:\n /command analyze src/\n /command fix src/app.js\n /command report\n\n Run /command help for more details.\n\n Exit.\nfi\n\n[Command continues if operation provided...]\n```\n\n## Error Message Documentation\n\n### Helpful Error Messages\n\n```markdown\n---\ndescription: Command with good error messages\n---\n\n# Validation Command\n\nif [ -z \"$1\" ]; then\n ❌ ERROR: Missing required argument\n\n The 'file-path' argument is required.\n\n USAGE:\n /validate [file-path]\n\n EXAMPLE:\n /validate src/app.js\n\n Try again with a file path.\n\n Exit.\nfi\n\nif [ ! -f \"$1\" ]; then\n ❌ ERROR: File not found: $1\n\n The specified file does not exist or is not accessible.\n\n COMMON CAUSES:\n 1. Typo in file path\n 2. File was deleted or moved\n 3. Insufficient permissions\n\n SUGGESTIONS:\n - Check spelling: $1\n - Verify file exists: ls -la $(dirname \"$1\")\n - Check permissions: ls -l \"$1\"\n\n Exit.\nfi\n\n[Command continues if validation passes...]\n```\n\n### Error Recovery Guidance\n\n```markdown\n---\ndescription: Command with recovery guidance\n---\n\n# Operation Command\n\nRunning operation...\n\n!`risky-operation.sh`\n\nif [ $? -ne 0 ]; then\n ❌ OPERATION FAILED\n\n The operation encountered an error and could not complete.\n\n WHAT HAPPENED:\n The risky-operation.sh script returned a non-zero exit code.\n\n WHAT THIS MEANS:\n - Changes may be partially applied\n - System may be in inconsistent state\n - Manual intervention may be needed\n\n RECOVERY STEPS:\n 1. Check operation logs: cat /tmp/operation.log\n 2. Verify system state: /check-state\n 3. If needed, rollback: /rollback-operation\n 4. Fix underlying issue\n 5. Retry operation: /retry-operation\n\n NEED HELP?\n - Check troubleshooting guide: /help troubleshooting\n - Contact support with error code: ERR_OP_FAILED_001\n\n Exit.\nfi\n```\n\n## Usage Example Documentation\n\n### Embedded Examples\n\n```markdown\n---\ndescription: Command with embedded examples\n---\n\n# Feature Command\n\nThis command performs feature analysis with multiple options.\n\n## Basic Usage\n\n\\`\\`\\`\n/feature analyze src/\n\\`\\`\\`\n\nAnalyzes all files in src/ directory for feature usage.\n\n## Advanced Usage\n\n\\`\\`\\`\n/feature analyze src/ --detailed\n\\`\\`\\`\n\nProvides detailed analysis including:\n- Feature breakdown by file\n- Usage patterns\n- Optimization suggestions\n\n## Use Cases\n\n**Use Case 1: Quick overview**\n\\`\\`\\`\n/feature analyze .\n\\`\\`\\`\nGet high-level feature summary of entire project.\n\n**Use Case 2: Specific directory**\n\\`\\`\\`\n/feature analyze src/components\n\\`\\`\\`\nFocus analysis on components directory only.\n\n**Use Case 3: Comparison**\n\\`\\`\\`\n/feature analyze src/ --compare baseline.json\n\\`\\`\\`\nCompare current features against baseline.\n\n---\n\nNow processing your request...\n\n[Command implementation...]\n```\n\n### Example-Driven Documentation\n\n```markdown\n---\ndescription: Example-heavy command\n---\n\n# Transformation Command\n\n## What This Does\n\nTransforms data from one format to another.\n\n## Examples First\n\n### Example 1: JSON to YAML\n**Input:** `data.json`\n\\`\\`\\`json\n{\"name\": \"test\", \"value\": 42}\n\\`\\`\\`\n\n**Command:** `/transform data.json yaml`\n\n**Output:** `data.yaml`\n\\`\\`\\`yaml\nname: test\nvalue: 42\n\\`\\`\\`\n\n### Example 2: CSV to JSON\n**Input:** `data.csv`\n\\`\\`\\`csv\nname,value\ntest,42\n\\`\\`\\`\n\n**Command:** `/transform data.csv json`\n\n**Output:** `data.json`\n\\`\\`\\`json\n[{\"name\": \"test\", \"value\": \"42\"}]\n\\`\\`\\`\n\n### Example 3: With Options\n**Command:** `/transform data.json yaml --pretty --sort-keys`\n\n**Result:** Formatted YAML with sorted keys\n\n---\n\n## Your Transformation\n\nFile: $1\nFormat: $2\n\n[Perform transformation...]\n```\n\n## Maintenance Documentation\n\n### Version and Changelog\n\n```markdown\n\n```\n\n### Maintenance Notes\n\n```markdown\n\n```\n\n## README Documentation\n\nCommands should have companion README files:\n\n```markdown\n# Command Name\n\nBrief description of what the command does.\n\n## Installation\n\nThis command is part of the [plugin-name] plugin.\n\nInstall with:\n\\`\\`\\`\n/plugin install plugin-name\n\\`\\`\\`\n\n## Usage\n\nBasic usage:\n\\`\\`\\`\n/command-name [arg1] [arg2]\n\\`\\`\\`\n\n## Arguments\n\n- `arg1`: Description (required)\n- `arg2`: Description (optional, defaults to X)\n\n## Examples\n\n### Example 1: Basic Usage\n\\`\\`\\`\n/command-name value1 value2\n\\`\\`\\`\n\nDescription of what happens.\n\n### Example 2: Advanced Usage\n\\`\\`\\`\n/command-name value1 --option\n\\`\\`\\`\n\nDescription of advanced feature.\n\n## Configuration\n\nOptional configuration file: `.claude/command-name.local.md`\n\n\\`\\`\\`markdown\n---\ndefault_arg: value\nenable_feature: true\n---\n\\`\\`\\`\n\n## Requirements\n\n- Git 2.x or later\n- jq (for JSON processing)\n- Node.js 14+ (optional, for advanced features)\n\n## Troubleshooting\n\n### Issue: Command not found\n\n**Solution:** Ensure plugin is installed and enabled.\n\n### Issue: Permission denied\n\n**Solution:** Check file permissions and allowed-tools setting.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT License - See [LICENSE](LICENSE).\n\n## Support\n\n- Issues: https://github.com/user/plugin/issues\n- Docs: https://docs.example.com\n- Email: support@example.com\n```\n\n## Best Practices\n\n### Documentation Principles\n\n1. **Write for your future self**: Assume you'll forget details\n2. **Examples before explanations**: Show, then tell\n3. **Progressive disclosure**: Basic info first, details available\n4. **Keep it current**: Update docs when code changes\n5. **Test your docs**: Verify examples actually work\n\n### Documentation Locations\n\n1. **In command file**: Core usage, examples, inline explanations\n2. **README**: Installation, configuration, troubleshooting\n3. **Separate docs**: Detailed guides, tutorials, API reference\n4. **Comments**: Implementation details for maintainers\n\n### Documentation Style\n\n1. **Clear and concise**: No unnecessary words\n2. **Active voice**: \"Run the command\" not \"The command can be run\"\n3. **Consistent terminology**: Use same terms throughout\n4. **Formatted well**: Use headings, lists, code blocks\n5. **Accessible**: Assume reader is beginner\n\n### Documentation Maintenance\n\n1. **Version everything**: Track what changed when\n2. **Deprecate gracefully**: Warn before removing features\n3. **Migration guides**: Help users upgrade\n4. **Archive old docs**: Keep old versions accessible\n5. **Review regularly**: Ensure docs match reality\n\n## Documentation Checklist\n\nBefore releasing a command:\n\n- [ ] Description in frontmatter is clear\n- [ ] argument-hint documents all arguments\n- [ ] Usage examples in comments\n- [ ] Common use cases shown\n- [ ] Error messages are helpful\n- [ ] Requirements documented\n- [ ] Related commands listed\n- [ ] Changelog maintained\n- [ ] Version number updated\n- [ ] README created/updated\n- [ ] Examples actually work\n- [ ] Troubleshooting section complete\n\nWith good documentation, commands become self-service, reducing support burden and improving user experience.\n","isInternal":false,"tokens":3642,"sizeBytes":14971},{"name":"frontmatter-reference.md","path":"plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Command Frontmatter Reference\n\nComplete reference for YAML frontmatter fields in slash commands.\n\n## Frontmatter Overview\n\nYAML frontmatter is optional metadata at the start of command files:\n\n```markdown\n---\ndescription: Brief description\nallowed-tools: Read, Write\nmodel: sonnet\nargument-hint: [arg1] [arg2]\n---\n\nCommand prompt content here...\n```\n\nAll fields are optional. Commands work without any frontmatter.\n\n## Field Specifications\n\n### description\n\n**Type:** String\n**Required:** No\n**Default:** First line of command prompt\n**Max Length:** ~60 characters recommended for `/help` display\n\n**Purpose:** Describes what the command does, shown in `/help` output\n\n**Examples:**\n```yaml\ndescription: Review code for security issues\n```\n```yaml\ndescription: Deploy to staging environment\n```\n```yaml\ndescription: Generate API documentation\n```\n\n**Best practices:**\n- Keep under 60 characters for clean display\n- Start with verb (Review, Deploy, Generate)\n- Be specific about what command does\n- Avoid redundant \"command\" or \"slash command\"\n\n**Good:**\n- ✅ \"Review PR for code quality and security\"\n- ✅ \"Deploy application to specified environment\"\n- ✅ \"Generate comprehensive API documentation\"\n\n**Bad:**\n- ❌ \"This command reviews PRs\" (unnecessary \"This command\")\n- ❌ \"Review\" (too vague)\n- ❌ \"A command that reviews pull requests for code quality, security issues, and best practices\" (too long)\n\n### allowed-tools\n\n**Type:** String or Array of strings\n**Required:** No\n**Default:** Inherits from conversation permissions\n\n**Purpose:** Restrict or specify which tools command can use\n\n**Formats:**\n\n**Single tool:**\n```yaml\nallowed-tools: Read\n```\n\n**Multiple tools (comma-separated):**\n```yaml\nallowed-tools: Read, Write, Edit\n```\n\n**Multiple tools (array):**\n```yaml\nallowed-tools:\n - Read\n - Write\n - Bash(git:*)\n```\n\n**Tool Patterns:**\n\n**Specific tools:**\n```yaml\nallowed-tools: Read, Grep, Edit\n```\n\n**Bash with command filter:**\n```yaml\nallowed-tools: Bash(git:*) # Only git commands\nallowed-tools: Bash(npm:*) # Only npm commands\nallowed-tools: Bash(docker:*) # Only docker commands\n```\n\n**All tools (not recommended):**\n```yaml\nallowed-tools: \"*\"\n```\n\n**When to use:**\n\n1. **Security:** Restrict command to safe operations\n ```yaml\n allowed-tools: Read, Grep # Read-only command\n ```\n\n2. **Clarity:** Document required tools\n ```yaml\n allowed-tools: Bash(git:*), Read\n ```\n\n3. **Bash execution:** Enable bash command output\n ```yaml\n allowed-tools: Bash(git status:*), Bash(git diff:*)\n ```\n\n**Best practices:**\n- Be as restrictive as possible\n- Use command filters for Bash (e.g., `git:*` not `*`)\n- Only specify when different from conversation permissions\n- Document why specific tools are needed\n\n### model\n\n**Type:** String\n**Required:** No\n**Default:** Inherits from conversation\n**Values:** `sonnet`, `opus`, `haiku`\n\n**Purpose:** Specify which Claude model executes the command\n\n**Examples:**\n```yaml\nmodel: haiku # Fast, efficient for simple tasks\n```\n```yaml\nmodel: sonnet # Balanced performance (default)\n```\n```yaml\nmodel: opus # Maximum capability for complex tasks\n```\n\n**When to use:**\n\n**Use `haiku` for:**\n- Simple, formulaic commands\n- Fast execution needed\n- Low complexity tasks\n- Frequent invocations\n\n```yaml\n---\ndescription: Format code file\nmodel: haiku\n---\n```\n\n**Use `sonnet` for:**\n- Standard commands (default)\n- Balanced speed/quality\n- Most common use cases\n\n```yaml\n---\ndescription: Review code changes\nmodel: sonnet\n---\n```\n\n**Use `opus` for:**\n- Complex analysis\n- Architectural decisions\n- Deep code understanding\n- Critical tasks\n\n```yaml\n---\ndescription: Analyze system architecture\nmodel: opus\n---\n```\n\n**Best practices:**\n- Omit unless specific need\n- Use `haiku` for speed when possible\n- Reserve `opus` for genuinely complex tasks\n- Test with different models to find right balance\n\n### argument-hint\n\n**Type:** String\n**Required:** No\n**Default:** None\n\n**Purpose:** Document expected arguments for users and autocomplete\n\n**Format:**\n```yaml\nargument-hint: [arg1] [arg2] [optional-arg]\n```\n\n**Examples:**\n\n**Single argument:**\n```yaml\nargument-hint: [pr-number]\n```\n\n**Multiple required arguments:**\n```yaml\nargument-hint: [environment] [version]\n```\n\n**Optional arguments:**\n```yaml\nargument-hint: [file-path] [options]\n```\n\n**Descriptive names:**\n```yaml\nargument-hint: [source-branch] [target-branch] [commit-message]\n```\n\n**Best practices:**\n- Use square brackets `[]` for each argument\n- Use descriptive names (not `arg1`, `arg2`)\n- Indicate optional vs required in description\n- Match order to positional arguments in command\n- Keep concise but clear\n\n**Examples by pattern:**\n\n**Simple command:**\n```yaml\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$1...\n```\n\n**Multi-argument:**\n```yaml\n---\ndescription: Deploy to environment\nargument-hint: [app-name] [environment] [version]\n---\n\nDeploy $1 to $2 using version $3...\n```\n\n**With options:**\n```yaml\n---\ndescription: Run tests with options\nargument-hint: [test-pattern] [options]\n---\n\nRun tests matching $1 with options: $2\n```\n\n### disable-model-invocation\n\n**Type:** Boolean\n**Required:** No\n**Default:** false\n\n**Purpose:** Prevent SlashCommand tool from programmatically invoking command\n\n**Examples:**\n```yaml\ndisable-model-invocation: true\n```\n\n**When to use:**\n\n1. **Manual-only commands:** Commands requiring user judgment\n ```yaml\n ---\n description: Approve deployment to production\n disable-model-invocation: true\n ---\n ```\n\n2. **Destructive operations:** Commands with irreversible effects\n ```yaml\n ---\n description: Delete all test data\n disable-model-invocation: true\n ---\n ```\n\n3. **Interactive workflows:** Commands needing user input\n ```yaml\n ---\n description: Walk through setup wizard\n disable-model-invocation: true\n ---\n ```\n\n**Default behavior (false):**\n- Command available to SlashCommand tool\n- Claude can invoke programmatically\n- Still available for manual invocation\n\n**When true:**\n- Command only invokable by user typing `/command`\n- Not available to SlashCommand tool\n- Safer for sensitive operations\n\n**Best practices:**\n- Use sparingly (limits Claude's autonomy)\n- Document why in command comments\n- Consider if command should exist if always manual\n\n## Complete Examples\n\n### Minimal Command\n\nNo frontmatter needed:\n\n```markdown\nReview this code for common issues and suggest improvements.\n```\n\n### Simple Command\n\nJust description:\n\n```markdown\n---\ndescription: Review code for issues\n---\n\nReview this code for common issues and suggest improvements.\n```\n\n### Standard Command\n\nDescription and tools:\n\n```markdown\n---\ndescription: Review Git changes\nallowed-tools: Bash(git:*), Read\n---\n\nCurrent changes: !`git diff --name-only`\n\nReview each changed file for:\n- Code quality\n- Potential bugs\n- Best practices\n```\n\n### Complex Command\n\nAll common fields:\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [app-name] [environment] [version]\nallowed-tools: Bash(kubectl:*), Bash(helm:*), Read\nmodel: sonnet\n---\n\nDeploy $1 to $2 environment using version $3\n\nPre-deployment checks:\n- Verify $2 configuration\n- Check cluster status: !`kubectl cluster-info`\n- Validate version $3 exists\n\nProceed with deployment following deployment runbook.\n```\n\n### Manual-Only Command\n\nRestricted invocation:\n\n```markdown\n---\ndescription: Approve production deployment\nargument-hint: [deployment-id]\ndisable-model-invocation: true\nallowed-tools: Bash(gh:*)\n---\n\n\n\nReview deployment $1 for production approval:\n\nDeployment details: !`gh api /deployments/$1`\n\nVerify:\n- All tests passed\n- Security scan clean\n- Stakeholder approval\n- Rollback plan ready\n\nType \"APPROVED\" to confirm deployment.\n```\n\n## Validation\n\n### Common Errors\n\n**Invalid YAML syntax:**\n```yaml\n---\ndescription: Missing quote\nallowed-tools: Read, Write\nmodel: sonnet\n--- # ❌ Missing closing quote above\n```\n\n**Fix:** Validate YAML syntax\n\n**Incorrect tool specification:**\n```yaml\nallowed-tools: Bash # ❌ Missing command filter\n```\n\n**Fix:** Use `Bash(git:*)` format\n\n**Invalid model name:**\n```yaml\nmodel: gpt4 # ❌ Not a valid Claude model\n```\n\n**Fix:** Use `sonnet`, `opus`, or `haiku`\n\n### Validation Checklist\n\nBefore committing command:\n- [ ] YAML syntax valid (no errors)\n- [ ] Description under 60 characters\n- [ ] allowed-tools uses proper format\n- [ ] model is valid value if specified\n- [ ] argument-hint matches positional arguments\n- [ ] disable-model-invocation used appropriately\n\n## Best Practices Summary\n\n1. **Start minimal:** Add frontmatter only when needed\n2. **Document arguments:** Always use argument-hint with arguments\n3. **Restrict tools:** Use most restrictive allowed-tools that works\n4. **Choose right model:** Use haiku for speed, opus for complexity\n5. **Manual-only sparingly:** Only use disable-model-invocation when necessary\n6. **Clear descriptions:** Make commands discoverable in `/help`\n7. **Test thoroughly:** Verify frontmatter works as expected\n","isInternal":false,"tokens":2210,"sizeBytes":9162},{"name":"interactive-commands.md","path":"plugins/plugin-dev/skills/command-development/references/interactive-commands.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/references/interactive-commands.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Interactive Command Patterns\n\nComprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.\n\n## Overview\n\nSome commands need user input that doesn't work well with simple arguments. For example:\n- Choosing between multiple complex options with trade-offs\n- Selecting multiple items from a list\n- Making decisions that require explanation\n- Gathering preferences or configuration interactively\n\nFor these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments.\n\n## When to Use AskUserQuestion\n\n### Use AskUserQuestion When:\n\n1. **Multiple choice decisions** with explanations needed\n2. **Complex options** that require context to choose\n3. **Multi-select scenarios** (choosing multiple items)\n4. **Preference gathering** for configuration\n5. **Interactive workflows** that adapt based on answers\n\n### Use Command Arguments When:\n\n1. **Simple values** (file paths, numbers, names)\n2. **Known inputs** user already has\n3. **Scriptable workflows** that should be automatable\n4. **Fast invocations** where prompting would slow down\n\n## AskUserQuestion Basics\n\n### Tool Parameters\n\n```typescript\n{\n questions: [\n {\n question: \"Which authentication method should we use?\",\n header: \"Auth method\", // Short label (max 12 chars)\n multiSelect: false, // true for multiple selection\n options: [\n {\n label: \"OAuth 2.0\",\n description: \"Industry standard, supports multiple providers\"\n },\n {\n label: \"JWT\",\n description: \"Stateless, good for APIs\"\n },\n {\n label: \"Session\",\n description: \"Traditional, server-side state\"\n }\n ]\n }\n ]\n}\n```\n\n**Key points:**\n- Users can always choose \"Other\" to provide custom input (automatic)\n- `multiSelect: true` allows selecting multiple options\n- Options should be 2-4 choices (not more)\n- Can ask 1-4 questions per tool call\n\n## Command Pattern for User Interaction\n\n### Basic Interactive Command\n\n```markdown\n---\ndescription: Interactive setup command\nallowed-tools: AskUserQuestion, Write\n---\n\n# Interactive Plugin Setup\n\nThis command will guide you through configuring the plugin with a series of questions.\n\n## Step 1: Gather Configuration\n\nUse the AskUserQuestion tool to ask:\n\n**Question 1 - Deployment target:**\n- header: \"Deploy to\"\n- question: \"Which deployment platform will you use?\"\n- options:\n - AWS (Amazon Web Services with ECS/EKS)\n - GCP (Google Cloud with GKE)\n - Azure (Microsoft Azure with AKS)\n - Local (Docker on local machine)\n\n**Question 2 - Environment strategy:**\n- header: \"Environments\"\n- question: \"How many environments do you need?\"\n- options:\n - Single (Just production)\n - Standard (Dev, Staging, Production)\n - Complete (Dev, QA, Staging, Production)\n\n**Question 3 - Features to enable:**\n- header: \"Features\"\n- question: \"Which features do you want to enable?\"\n- multiSelect: true\n- options:\n - Auto-scaling (Automatic resource scaling)\n - Monitoring (Health checks and metrics)\n - CI/CD (Automated deployment pipeline)\n - Backups (Automated database backups)\n\n## Step 2: Process Answers\n\nBased on the answers received from AskUserQuestion:\n\n1. Parse the deployment target choice\n2. Set up environment-specific configuration\n3. Enable selected features\n4. Generate configuration files\n\n## Step 3: Generate Configuration\n\nCreate `.claude/plugin-name.local.md` with:\n\n\\`\\`\\`yaml\n---\ndeployment_target: [answer from Q1]\nenvironments: [answer from Q2]\nfeatures:\n auto_scaling: [true if selected in Q3]\n monitoring: [true if selected in Q3]\n ci_cd: [true if selected in Q3]\n backups: [true if selected in Q3]\n---\n\n# Plugin Configuration\n\nGenerated: [timestamp]\nTarget: [deployment_target]\nEnvironments: [environments]\n\\`\\`\\`\n\n## Step 4: Confirm and Next Steps\n\nConfirm configuration created and guide user on next steps.\n```\n\n### Multi-Stage Interactive Workflow\n\n```markdown\n---\ndescription: Multi-stage interactive workflow\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Multi-Stage Deployment Setup\n\nThis command walks through deployment setup in stages, adapting based on your answers.\n\n## Stage 1: Basic Configuration\n\nUse AskUserQuestion to ask about deployment basics.\n\nBased on answers, determine which additional questions to ask.\n\n## Stage 2: Advanced Options (Conditional)\n\nIf user selected \"Advanced\" deployment in Stage 1:\n\nUse AskUserQuestion to ask about:\n- Load balancing strategy\n- Caching configuration\n- Security hardening options\n\nIf user selected \"Simple\" deployment:\n- Skip advanced questions\n- Use sensible defaults\n\n## Stage 3: Confirmation\n\nShow summary of all selections.\n\nUse AskUserQuestion for final confirmation:\n- header: \"Confirm\"\n- question: \"Does this configuration look correct?\"\n- options:\n - Yes (Proceed with setup)\n - No (Start over)\n - Modify (Let me adjust specific settings)\n\nIf \"Modify\", ask which specific setting to change.\n\n## Stage 4: Execute Setup\n\nBased on confirmed configuration, execute setup steps.\n```\n\n## Interactive Question Design\n\n### Question Structure\n\n**Good questions:**\n```markdown\nQuestion: \"Which database should we use for this project?\"\nHeader: \"Database\"\nOptions:\n - PostgreSQL (Relational, ACID compliant, best for complex queries)\n - MongoDB (Document store, flexible schema, best for rapid iteration)\n - Redis (In-memory, fast, best for caching and sessions)\n```\n\n**Poor questions:**\n```markdown\nQuestion: \"Database?\" // Too vague\nHeader: \"DB\" // Unclear abbreviation\nOptions:\n - Option 1 // Not descriptive\n - Option 2\n```\n\n### Option Design Best Practices\n\n**Clear labels:**\n- Use 1-5 words\n- Specific and descriptive\n- No jargon without context\n\n**Helpful descriptions:**\n- Explain what the option means\n- Mention key benefits or trade-offs\n- Help user make informed decision\n- Keep to 1-2 sentences\n\n**Appropriate number:**\n- 2-4 options per question\n- Don't overwhelm with too many choices\n- Group related options\n- \"Other\" automatically provided\n\n### Multi-Select Questions\n\n**When to use multiSelect:**\n\n```markdown\nUse AskUserQuestion for enabling features:\n\nQuestion: \"Which features do you want to enable?\"\nHeader: \"Features\"\nmultiSelect: true // Allow selecting multiple\nOptions:\n - Logging (Detailed operation logs)\n - Metrics (Performance monitoring)\n - Alerts (Error notifications)\n - Backups (Automatic backups)\n```\n\nUser can select any combination: none, some, or all.\n\n**When NOT to use multiSelect:**\n\n```markdown\nQuestion: \"Which authentication method?\"\nmultiSelect: false // Only one auth method makes sense\n```\n\nMutually exclusive choices should not use multiSelect.\n\n## Command Patterns with AskUserQuestion\n\n### Pattern 1: Simple Yes/No Decision\n\n```markdown\n---\ndescription: Command with confirmation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Destructive Operation\n\nThis operation will delete all cached data.\n\nUse AskUserQuestion to confirm:\n\nQuestion: \"This will delete all cached data. Are you sure?\"\nHeader: \"Confirm\"\nOptions:\n - Yes (Proceed with deletion)\n - No (Cancel operation)\n\nIf user selects \"Yes\":\n Execute deletion\n Report completion\n\nIf user selects \"No\":\n Cancel operation\n Exit without changes\n```\n\n### Pattern 2: Multiple Configuration Questions\n\n```markdown\n---\ndescription: Multi-question configuration\nallowed-tools: AskUserQuestion, Write\n---\n\n# Project Configuration Setup\n\nGather configuration through multiple questions.\n\nUse AskUserQuestion with multiple questions in one call:\n\n**Question 1:**\n- question: \"Which programming language?\"\n- header: \"Language\"\n- options: Python, TypeScript, Go, Rust\n\n**Question 2:**\n- question: \"Which test framework?\"\n- header: \"Testing\"\n- options: Jest, PyTest, Go Test, Cargo Test\n (Adapt based on language from Q1)\n\n**Question 3:**\n- question: \"Which CI/CD platform?\"\n- header: \"CI/CD\"\n- options: GitHub Actions, GitLab CI, CircleCI\n\n**Question 4:**\n- question: \"Which features do you need?\"\n- header: \"Features\"\n- multiSelect: true\n- options: Linting, Type checking, Code coverage, Security scanning\n\nProcess all answers together to generate cohesive configuration.\n```\n\n### Pattern 3: Conditional Question Flow\n\n```markdown\n---\ndescription: Conditional interactive workflow\nallowed-tools: AskUserQuestion, Read, Write\n---\n\n# Adaptive Configuration\n\n## Question 1: Deployment Complexity\n\nUse AskUserQuestion:\n\nQuestion: \"How complex is your deployment?\"\nHeader: \"Complexity\"\nOptions:\n - Simple (Single server, straightforward)\n - Standard (Multiple servers, load balancing)\n - Complex (Microservices, orchestration)\n\n## Conditional Questions Based on Answer\n\nIf answer is \"Simple\":\n - No additional questions\n - Use minimal configuration\n\nIf answer is \"Standard\":\n - Ask about load balancing strategy\n - Ask about scaling policy\n\nIf answer is \"Complex\":\n - Ask about orchestration platform (Kubernetes, Docker Swarm)\n - Ask about service mesh (Istio, Linkerd, None)\n - Ask about monitoring (Prometheus, Datadog, CloudWatch)\n - Ask about logging aggregation\n\n## Process Conditional Answers\n\nGenerate configuration appropriate for selected complexity level.\n```\n\n### Pattern 4: Iterative Collection\n\n```markdown\n---\ndescription: Collect multiple items iteratively\nallowed-tools: AskUserQuestion, Write\n---\n\n# Collect Team Members\n\nWe'll collect team member information for the project.\n\n## Question: How many team members?\n\nUse AskUserQuestion:\n\nQuestion: \"How many team members should we set up?\"\nHeader: \"Team size\"\nOptions:\n - 2 people\n - 3 people\n - 4 people\n - 6 people\n\n## Iterate Through Team Members\n\nFor each team member (1 to N based on answer):\n\nUse AskUserQuestion for member details:\n\nQuestion: \"What role for team member [number]?\"\nHeader: \"Role\"\nOptions:\n - Frontend Developer\n - Backend Developer\n - DevOps Engineer\n - QA Engineer\n - Designer\n\nStore each member's information.\n\n## Generate Team Configuration\n\nAfter collecting all N members, create team configuration file with all members and their roles.\n```\n\n### Pattern 5: Dependency Selection\n\n```markdown\n---\ndescription: Select dependencies with multi-select\nallowed-tools: AskUserQuestion\n---\n\n# Configure Project Dependencies\n\n## Question: Required Libraries\n\nUse AskUserQuestion with multiSelect:\n\nQuestion: \"Which libraries does your project need?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - React (UI framework)\n - Express (Web server)\n - TypeORM (Database ORM)\n - Jest (Testing framework)\n - Axios (HTTP client)\n\nUser can select any combination.\n\n## Process Selections\n\nFor each selected library:\n- Add to package.json dependencies\n- Generate sample configuration\n- Create usage examples\n- Update documentation\n```\n\n## Best Practices for Interactive Commands\n\n### Question Design\n\n1. **Clear and specific**: Question should be unambiguous\n2. **Concise header**: Max 12 characters for clean display\n3. **Helpful options**: Labels are clear, descriptions explain trade-offs\n4. **Appropriate count**: 2-4 options per question, 1-4 questions per call\n5. **Logical order**: Questions flow naturally\n\n### Error Handling\n\n```markdown\n# Handle AskUserQuestion Responses\n\nAfter calling AskUserQuestion, verify answers received:\n\nIf answers are empty or invalid:\n Something went wrong gathering responses.\n\n Please try again or provide configuration manually:\n [Show alternative approach]\n\n Exit.\n\nIf answers look correct:\n Process as expected\n```\n\n### Progressive Disclosure\n\n```markdown\n# Start Simple, Get Detailed as Needed\n\n## Question 1: Setup Type\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to set up?\"\nHeader: \"Setup type\"\nOptions:\n - Quick (Use recommended defaults)\n - Custom (Configure all options)\n - Guided (Step-by-step with explanations)\n\nIf \"Quick\":\n Apply defaults, minimal questions\n\nIf \"Custom\":\n Ask all available configuration questions\n\nIf \"Guided\":\n Ask questions with extra explanation\n Provide recommendations along the way\n```\n\n### Multi-Select Guidelines\n\n**Good multi-select use:**\n```markdown\nQuestion: \"Which features do you want to enable?\"\nmultiSelect: true\nOptions:\n - Logging\n - Metrics\n - Alerts\n - Backups\n\nReason: User might want any combination\n```\n\n**Bad multi-select use:**\n```markdown\nQuestion: \"Which database engine?\"\nmultiSelect: true // ❌ Should be single-select\n\nReason: Can only use one database engine\n```\n\n## Advanced Patterns\n\n### Validation Loop\n\n```markdown\n---\ndescription: Interactive with validation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Setup with Validation\n\n## Gather Configuration\n\nUse AskUserQuestion to collect settings.\n\n## Validate Configuration\n\nCheck if configuration is valid:\n- Required dependencies available?\n- Settings compatible with each other?\n- No conflicts detected?\n\nIf validation fails:\n Show validation errors\n\n Use AskUserQuestion to ask:\n\n Question: \"Configuration has issues. What would you like to do?\"\n Header: \"Next step\"\n Options:\n - Fix (Adjust settings to resolve issues)\n - Override (Proceed despite warnings)\n - Cancel (Abort setup)\n\n Based on answer, retry or proceed or exit.\n```\n\n### Build Configuration Incrementally\n\n```markdown\n---\ndescription: Incremental configuration builder\nallowed-tools: AskUserQuestion, Write, Read\n---\n\n# Incremental Setup\n\n## Phase 1: Core Settings\n\nUse AskUserQuestion for core settings.\n\nSave to `.claude/config-partial.yml`\n\n## Phase 2: Review Core Settings\n\nShow user the core settings:\n\nBased on these core settings, you need to configure:\n- [Setting A] (because you chose [X])\n- [Setting B] (because you chose [Y])\n\nReady to continue?\n\n## Phase 3: Detailed Settings\n\nUse AskUserQuestion for settings based on Phase 1 answers.\n\nMerge with core settings.\n\n## Phase 4: Final Review\n\nPresent complete configuration.\n\nUse AskUserQuestion for confirmation:\n\nQuestion: \"Is this configuration correct?\"\nOptions:\n - Yes (Save and apply)\n - No (Start over)\n - Modify (Edit specific settings)\n```\n\n### Dynamic Options Based on Context\n\n```markdown\n---\ndescription: Context-aware questions\nallowed-tools: AskUserQuestion, Bash, Read\n---\n\n# Context-Aware Setup\n\n## Detect Current State\n\nCheck existing configuration:\n- Current language: !`detect-language.sh`\n- Existing frameworks: !`detect-frameworks.sh`\n- Available tools: !`check-tools.sh`\n\n## Ask Context-Appropriate Questions\n\nBased on detected language, ask relevant questions.\n\nIf language is TypeScript:\n\n Use AskUserQuestion:\n\n Question: \"Which TypeScript features should we enable?\"\n Options:\n - Strict Mode (Maximum type safety)\n - Decorators (Experimental decorator support)\n - Path Mapping (Module path aliases)\n\nIf language is Python:\n\n Use AskUserQuestion:\n\n Question: \"Which Python tools should we configure?\"\n Options:\n - Type Hints (mypy for type checking)\n - Black (Code formatting)\n - Pylint (Linting and style)\n\nQuestions adapt to project context.\n```\n\n## Real-World Example: Multi-Agent Swarm Launch\n\n**From multi-agent-swarm plugin:**\n\n```markdown\n---\ndescription: Launch multi-agent swarm\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Launch Multi-Agent Swarm\n\n## Interactive Mode (No Task List Provided)\n\nIf user didn't provide task list file, help create one interactively.\n\n### Question 1: Agent Count\n\nUse AskUserQuestion:\n\nQuestion: \"How many agents should we launch?\"\nHeader: \"Agent count\"\nOptions:\n - 2 agents (Best for simple projects)\n - 3 agents (Good for medium projects)\n - 4 agents (Standard team size)\n - 6 agents (Large projects)\n - 8 agents (Complex multi-component projects)\n\n### Question 2: Task Definition Approach\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to define tasks?\"\nHeader: \"Task setup\"\nOptions:\n - File (I have a task list file ready)\n - Guided (Help me create tasks interactively)\n - Custom (Other approach)\n\nIf \"File\":\n Ask for file path\n Validate file exists and has correct format\n\nIf \"Guided\":\n Enter iterative task creation mode (see below)\n\n### Question 3: Coordination Mode\n\nUse AskUserQuestion:\n\nQuestion: \"How should agents coordinate?\"\nHeader: \"Coordination\"\nOptions:\n - Team Leader (One agent coordinates others)\n - Collaborative (Agents coordinate as peers)\n - Autonomous (Independent work, minimal coordination)\n\n### Iterative Task Creation (If \"Guided\" Selected)\n\nFor each agent (1 to N from Question 1):\n\n**Question A: Agent Name**\nQuestion: \"What should we call agent [number]?\"\nHeader: \"Agent name\"\nOptions:\n - auth-agent\n - api-agent\n - ui-agent\n - db-agent\n (Provide relevant suggestions based on common patterns)\n\n**Question B: Task Type**\nQuestion: \"What task for [agent-name]?\"\nHeader: \"Task type\"\nOptions:\n - Authentication (User auth, JWT, OAuth)\n - API Endpoints (REST/GraphQL APIs)\n - UI Components (Frontend components)\n - Database (Schema, migrations, queries)\n - Testing (Test suites and coverage)\n - Documentation (Docs, README, guides)\n\n**Question C: Dependencies**\nQuestion: \"What does [agent-name] depend on?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - [List of previously defined agents]\n - No dependencies\n\n**Question D: Base Branch**\nQuestion: \"Which base branch for PR?\"\nHeader: \"PR base\"\nOptions:\n - main\n - staging\n - develop\n\nStore all task information for each agent.\n\n### Generate Task List File\n\nAfter collecting all agent task details:\n\n1. Ask for project name\n2. Generate task list in proper format\n3. Save to `.daisy/swarm/tasks.md`\n4. Show user the file path\n5. Proceed with launch using generated task list\n```\n\n## Best Practices\n\n### Question Writing\n\n1. **Be specific**: \"Which database?\" not \"Choose option?\"\n2. **Explain trade-offs**: Describe pros/cons in option descriptions\n3. **Provide context**: Question text should stand alone\n4. **Guide decisions**: Help user make informed choice\n5. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences\n\n### Option Design\n\n1. **Meaningful labels**: Specific, clear names\n2. **Informative descriptions**: Explain what each option does\n3. **Show trade-offs**: Help user understand implications\n4. **Consistent detail**: All options equally explained\n5. **2-4 options**: Not too few, not too many\n\n### Flow Design\n\n1. **Logical order**: Questions flow naturally\n2. **Build on previous**: Later questions use earlier answers\n3. **Minimize questions**: Ask only what's needed\n4. **Group related**: Ask related questions together\n5. **Show progress**: Indicate where in flow\n\n### User Experience\n\n1. **Set expectations**: Tell user what to expect\n2. **Explain why**: Help user understand purpose\n3. **Provide defaults**: Suggest recommended options\n4. **Allow escape**: Let user cancel or restart\n5. **Confirm actions**: Summarize before executing\n\n## Common Patterns\n\n### Pattern: Feature Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which features do you need?\"\nHeader: \"Features\"\nmultiSelect: true\nOptions:\n - Authentication\n - Authorization\n - Rate Limiting\n - Caching\n```\n\n### Pattern: Environment Configuration\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which environment is this?\"\nHeader: \"Environment\"\nOptions:\n - Development (Local development)\n - Staging (Pre-production testing)\n - Production (Live environment)\n```\n\n### Pattern: Priority Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What's the priority for this task?\"\nHeader: \"Priority\"\nOptions:\n - Critical (Must be done immediately)\n - High (Important, do soon)\n - Medium (Standard priority)\n - Low (Nice to have)\n```\n\n### Pattern: Scope Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What scope should we analyze?\"\nHeader: \"Scope\"\nOptions:\n - Current file (Just this file)\n - Current directory (All files in directory)\n - Entire project (Full codebase scan)\n```\n\n## Combining Arguments and Questions\n\n### Use Both Appropriately\n\n**Arguments for known values:**\n```markdown\n---\nargument-hint: [project-name]\nallowed-tools: AskUserQuestion, Write\n---\n\nSetup for project: $1\n\nNow gather additional configuration...\n\nUse AskUserQuestion for options that require explanation.\n```\n\n**Questions for complex choices:**\n```markdown\nProject name from argument: $1\n\nNow use AskUserQuestion to choose:\n- Architecture pattern\n- Technology stack\n- Deployment strategy\n\nThese require explanation, so questions work better than arguments.\n```\n\n## Troubleshooting\n\n**Questions not appearing:**\n- Verify AskUserQuestion in allowed-tools\n- Check question format is correct\n- Ensure options array has 2-4 items\n\n**User can't make selection:**\n- Check option labels are clear\n- Verify descriptions are helpful\n- Consider if too many options\n- Ensure multiSelect setting is correct\n\n**Flow feels confusing:**\n- Reduce number of questions\n- Group related questions\n- Add explanation between stages\n- Show progress through workflow\n\nWith AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.\n","isInternal":false,"tokens":4751,"sizeBytes":20980},{"name":"marketplace-considerations.md","path":"plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Marketplace Considerations for Commands\n\nGuidelines for creating commands designed for distribution and marketplace success.\n\n## Overview\n\nCommands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.\n\n## Design for Distribution\n\n### Universal Compatibility\n\n**Cross-platform considerations:**\n\n```markdown\n---\ndescription: Cross-platform command\nallowed-tools: Bash(*)\n---\n\n# Platform-Aware Command\n\nDetecting platform...\n\ncase \"$(uname)\" in\n Darwin*) PLATFORM=\"macOS\" ;;\n Linux*) PLATFORM=\"Linux\" ;;\n MINGW*|MSYS*|CYGWIN*) PLATFORM=\"Windows\" ;;\n *) PLATFORM=\"Unknown\" ;;\nesac\n\nPlatform: $PLATFORM\n\n\nif [ \"$PLATFORM\" = \"Windows\" ]; then\n # Windows-specific handling\n PATH_SEP=\"\\\\\"\n NULL_DEVICE=\"NUL\"\nelse\n # Unix-like handling\n PATH_SEP=\"/\"\n NULL_DEVICE=\"/dev/null\"\nfi\n\n[Platform-appropriate implementation...]\n```\n\n**Avoid platform-specific commands:**\n\n```markdown\n\n!`pbcopy < file.txt`\n\n\nif command -v pbcopy > /dev/null; then\n pbcopy < file.txt\nelif command -v xclip > /dev/null; then\n xclip -selection clipboard < file.txt\nelif command -v clip.exe > /dev/null; then\n cat file.txt | clip.exe\nelse\n echo \"Clipboard not available on this platform\"\nfi\n```\n\n### Minimal Dependencies\n\n**Check for required tools:**\n\n```markdown\n---\ndescription: Dependency-aware command\nallowed-tools: Bash(*)\n---\n\n# Check Dependencies\n\nRequired tools:\n- git\n- jq\n- node\n\nChecking availability...\n\nMISSING_DEPS=\"\"\n\nfor tool in git jq node; do\n if ! command -v $tool > /dev/null; then\n MISSING_DEPS=\"$MISSING_DEPS $tool\"\n fi\ndone\n\nif [ -n \"$MISSING_DEPS\" ]; then\n ❌ ERROR: Missing required dependencies:$MISSING_DEPS\n\n INSTALLATION:\n - git: https://git-scm.com/downloads\n - jq: https://stedolan.github.io/jq/download/\n - node: https://nodejs.org/\n\n Install missing tools and try again.\n\n Exit.\nfi\n\n✓ All dependencies available\n\n[Continue with command...]\n```\n\n**Document optional dependencies:**\n\n```markdown\n\n```\n\n### Graceful Degradation\n\n**Handle missing features:**\n\n```markdown\n---\ndescription: Feature-aware command\n---\n\n# Feature Detection\n\nDetecting available features...\n\nFEATURES=\"\"\n\nif command -v gh > /dev/null; then\n FEATURES=\"$FEATURES github\"\nfi\n\nif command -v docker > /dev/null; then\n FEATURES=\"$FEATURES docker\"\nfi\n\nAvailable features: $FEATURES\n\nif echo \"$FEATURES\" | grep -q \"github\"; then\n # Full functionality with GitHub integration\n echo \"✓ GitHub integration available\"\nelse\n # Reduced functionality without GitHub\n echo \"⚠ Limited functionality: GitHub CLI not installed\"\n echo \" Install 'gh' for full features\"\nfi\n\n[Adapt behavior based on available features...]\n```\n\n## User Experience for Unknown Users\n\n### Clear Onboarding\n\n**First-run experience:**\n\n```markdown\n---\ndescription: Command with onboarding\nallowed-tools: Read, Write\n---\n\n# First Run Check\n\nif [ ! -f \".claude/command-initialized\" ]; then\n **Welcome to Command Name!**\n\n This appears to be your first time using this command.\n\n WHAT THIS COMMAND DOES:\n [Brief explanation of purpose and benefits]\n\n QUICK START:\n 1. Basic usage: /command [arg]\n 2. For help: /command help\n 3. Examples: /command examples\n\n SETUP:\n No additional setup required. You're ready to go!\n\n ✓ Initialization complete\n\n [Create initialization marker]\n\n Ready to proceed with your request...\nfi\n\n[Normal command execution...]\n```\n\n**Progressive feature discovery:**\n\n```markdown\n---\ndescription: Command with tips\n---\n\n# Command Execution\n\n[Main functionality...]\n\n---\n\n💡 TIP: Did you know?\n\nYou can speed up this command with the --fast flag:\n /command --fast [args]\n\nFor more tips: /command tips\n```\n\n### Comprehensive Error Handling\n\n**Anticipate user mistakes:**\n\n```markdown\n---\ndescription: Forgiving command\n---\n\n# User Input Handling\n\nArgument: \"$1\"\n\n\nif [ \"$1\" = \"hlep\" ] || [ \"$1\" = \"hepl\" ]; then\n Did you mean: help?\n\n Showing help instead...\n [Display help]\n\n Exit.\nfi\n\n\nif [ \"$1\" != \"valid-option1\" ] && [ \"$1\" != \"valid-option2\" ]; then\n ❌ Unknown option: $1\n\n Did you mean:\n - valid-option1 (most similar)\n - valid-option2\n\n For all options: /command help\n\n Exit.\nfi\n\n[Command continues...]\n```\n\n**Helpful diagnostics:**\n\n```markdown\n---\ndescription: Diagnostic command\n---\n\n# Operation Failed\n\nThe operation could not complete.\n\n**Diagnostic Information:**\n\nEnvironment:\n- Platform: $(uname)\n- Shell: $SHELL\n- Working directory: $(pwd)\n- Command: /command $@\n\nChecking common issues:\n- Git repository: $(git rev-parse --git-dir 2>&1)\n- Write permissions: $(test -w . && echo \"OK\" || echo \"DENIED\")\n- Required files: $(test -f config.yml && echo \"Found\" || echo \"Missing\")\n\nThis information helps debug the issue.\n\nFor support, include the above diagnostics.\n```\n\n## Distribution Best Practices\n\n### Namespace Awareness\n\n**Avoid name collisions:**\n\n```markdown\n---\ndescription: Namespaced command\n---\n\n\n\n# Plugin Name Command\n\n[Implementation...]\n```\n\n**Document naming rationale:**\n\n```markdown\n\n```\n\n### Configurability\n\n**User preferences:**\n\n```markdown\n---\ndescription: Configurable command\nallowed-tools: Read\n---\n\n# Load User Configuration\n\nDefault configuration:\n- verbose: false\n- color: true\n- max_results: 10\n\nChecking for user config: .claude/plugin-name.local.md\n\nif [ -f \".claude/plugin-name.local.md\" ]; then\n # Parse YAML frontmatter for settings\n VERBOSE=$(grep \"^verbose:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n COLOR=$(grep \"^color:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n MAX_RESULTS=$(grep \"^max_results:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n\n echo \"✓ Using user configuration\"\nelse\n echo \"Using default configuration\"\n echo \"Create .claude/plugin-name.local.md to customize\"\nfi\n\n[Use configuration in command...]\n```\n\n**Sensible defaults:**\n\n```markdown\n---\ndescription: Command with smart defaults\n---\n\n# Smart Defaults\n\nConfiguration:\n- Format: ${FORMAT:-json} # Defaults to json\n- Output: ${OUTPUT:-stdout} # Defaults to stdout\n- Verbose: ${VERBOSE:-false} # Defaults to false\n\nThese defaults work for 80% of use cases.\n\nOverride with arguments:\n /command --format yaml --output file.txt --verbose\n\nOr set in .claude/plugin-name.local.md:\n\\`\\`\\`yaml\n---\nformat: yaml\noutput: custom.txt\nverbose: true\n---\n\\`\\`\\`\n```\n\n### Version Compatibility\n\n**Version checking:**\n\n```markdown\n---\ndescription: Version-aware command\n---\n\n\n\n# Version Check\n\nCommand version: 2.1.0\nPlugin version: [detect from plugin.json]\n\nif [ \"$PLUGIN_VERSION\" < \"2.0.0\" ]; then\n ❌ ERROR: Incompatible plugin version\n\n This command requires plugin version >= 2.0.0\n Current version: $PLUGIN_VERSION\n\n Update plugin:\n /plugin update plugin-name\n\n Exit.\nfi\n\n✓ Version compatible\n\n[Command continues...]\n```\n\n**Deprecation warnings:**\n\n```markdown\n---\ndescription: Command with deprecation warnings\n---\n\n# Deprecation Check\n\nif [ \"$1\" = \"--old-flag\" ]; then\n ⚠️ DEPRECATION WARNING\n\n The --old-flag option is deprecated as of v2.0.0\n It will be removed in v3.0.0 (est. June 2025)\n\n Use instead: --new-flag\n\n Example:\n Old: /command --old-flag value\n New: /command --new-flag value\n\n See migration guide: /command migrate\n\n Continuing with deprecated behavior for now...\nfi\n\n[Handle both old and new flags during deprecation period...]\n```\n\n## Marketplace Presentation\n\n### Command Discovery\n\n**Descriptive naming:**\n\n```markdown\n---\ndescription: Review pull request with security and quality checks\n---\n\n\n```\n\n```markdown\n---\ndescription: Do the thing\n---\n\n\n```\n\n**Searchable keywords:**\n\n```markdown\n\n```\n\n### Showcase Examples\n\n**Compelling demonstrations:**\n\n```markdown\n---\ndescription: Advanced code analysis command\n---\n\n# Code Analysis Command\n\nThis command performs deep code analysis with actionable insights.\n\n## Demo: Quick Security Audit\n\nTry it now:\n\\`\\`\\`\n/analyze-code src/ --security\n\\`\\`\\`\n\n**What you'll get:**\n- Security vulnerability detection\n- Code quality metrics\n- Performance bottleneck identification\n- Actionable recommendations\n\n**Sample output:**\n\\`\\`\\`\nSecurity Analysis Results\n=========================\n\n🔴 Critical (2):\n - SQL injection risk in users.js:45\n - XSS vulnerability in display.js:23\n\n🟡 Warnings (5):\n - Unvalidated input in api.js:67\n ...\n\nRecommendations:\n1. Fix critical issues immediately\n2. Review warnings before next release\n3. Run /analyze-code --fix for auto-fixes\n\\`\\`\\`\n\n---\n\nReady to analyze your code...\n\n[Command implementation...]\n```\n\n### User Reviews and Feedback\n\n**Feedback mechanism:**\n\n```markdown\n---\ndescription: Command with feedback\n---\n\n# Command Complete\n\n[Command results...]\n\n---\n\n**How was your experience?**\n\nThis helps improve the command for everyone.\n\nRate this command:\n- 👍 Helpful\n- 👎 Not helpful\n- 🐛 Found a bug\n- 💡 Have a suggestion\n\nReply with an emoji or:\n- /command feedback\n\nYour feedback matters!\n```\n\n**Usage analytics preparation:**\n\n```markdown\n\n```\n\n## Quality Standards\n\n### Professional Polish\n\n**Consistent branding:**\n\n```markdown\n---\ndescription: Branded command\n---\n\n# ✨ Command Name\n\nPart of the [Plugin Name] suite\n\n[Command functionality...]\n\n---\n\n**Need Help?**\n- Documentation: https://docs.example.com\n- Support: support@example.com\n- Community: https://community.example.com\n\nPowered by Plugin Name v2.1.0\n```\n\n**Attention to detail:**\n\n```markdown\n\n\n✓ Use proper emoji/symbols consistently\n✓ Align output columns neatly\n✓ Format numbers with thousands separators\n✓ Use color/formatting appropriately\n✓ Provide progress indicators\n✓ Show estimated time remaining\n✓ Confirm successful operations\n```\n\n### Reliability\n\n**Idempotency:**\n\n```markdown\n---\ndescription: Idempotent command\n---\n\n# Safe Repeated Execution\n\nChecking if operation already completed...\n\nif [ -f \".claude/operation-completed.flag\" ]; then\n ℹ️ Operation already completed\n\n Completed at: $(cat .claude/operation-completed.flag)\n\n To re-run:\n 1. Remove flag: rm .claude/operation-completed.flag\n 2. Run command again\n\n Otherwise, no action needed.\n\n Exit.\nfi\n\nPerforming operation...\n\n[Safe, repeatable operation...]\n\nMarking complete...\necho \"$(date)\" > .claude/operation-completed.flag\n```\n\n**Atomic operations:**\n\n```markdown\n---\ndescription: Atomic command\n---\n\n# Atomic Operation\n\nThis operation is atomic - either fully succeeds or fully fails.\n\nCreating temporary workspace...\nTEMP_DIR=$(mktemp -d)\n\nPerforming changes in isolated environment...\n[Make changes in $TEMP_DIR]\n\nif [ $? -eq 0 ]; then\n ✓ Changes validated\n\n Applying changes atomically...\n mv $TEMP_DIR/* ./target/\n\n ✓ Operation complete\nelse\n ❌ Changes failed validation\n\n Rolling back...\n rm -rf $TEMP_DIR\n\n No changes applied. Safe to retry.\nfi\n```\n\n## Testing for Distribution\n\n### Pre-Release Checklist\n\n```markdown\n\n```\n\n### Beta Testing\n\n**Beta release approach:**\n\n```markdown\n---\ndescription: Beta command (v0.9.0)\n---\n\n# 🧪 Beta Command\n\n**This is a beta release**\n\nFeatures may change based on feedback.\n\nBETA STATUS:\n- Version: 0.9.0\n- Stability: Experimental\n- Support: Limited\n- Feedback: Encouraged\n\nKnown limitations:\n- Performance not optimized\n- Some edge cases not handled\n- Documentation incomplete\n\nHelp improve this command:\n- Report issues: /command report-issue\n- Suggest features: /command suggest\n- Join beta testers: /command join-beta\n\n---\n\n[Command implementation...]\n\n---\n\n**Thank you for beta testing!**\n\nYour feedback helps make this command better.\n```\n\n## Maintenance and Updates\n\n### Update Strategy\n\n**Versioned commands:**\n\n```markdown\n\n```\n\n**Update notifications:**\n\n```markdown\n---\ndescription: Update-aware command\n---\n\n# Check for Updates\n\nCurrent version: 2.1.0\nLatest version: [check if available]\n\nif [ \"$CURRENT_VERSION\" != \"$LATEST_VERSION\" ]; then\n 📢 UPDATE AVAILABLE\n\n New version: $LATEST_VERSION\n Current: $CURRENT_VERSION\n\n What's new:\n - Feature improvements\n - Bug fixes\n - Performance enhancements\n\n Update with:\n /plugin update plugin-name\n\n Release notes: https://releases.example.com/v$LATEST_VERSION\nfi\n\n[Command continues...]\n```\n\n## Best Practices Summary\n\n### Distribution Design\n\n1. **Universal**: Works across platforms and environments\n2. **Self-contained**: Minimal dependencies, clear requirements\n3. **Graceful**: Degrades gracefully when features unavailable\n4. **Forgiving**: Anticipates and handles user mistakes\n5. **Helpful**: Clear errors, good defaults, excellent docs\n\n### Marketplace Success\n\n1. **Discoverable**: Clear name, good description, searchable keywords\n2. **Professional**: Polished presentation, consistent branding\n3. **Reliable**: Tested thoroughly, handles edge cases\n4. **Maintainable**: Versioned, updated regularly, supported\n5. **User-focused**: Great UX, responsive to feedback\n\n### Quality Standards\n\n1. **Complete**: Fully documented, all features working\n2. **Tested**: Works in real environments, edge cases handled\n3. **Secure**: No vulnerabilities, safe operations\n4. **Performant**: Reasonable speed, resource-efficient\n5. **Ethical**: Privacy-respecting, user consent\n\nWith these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.\n","isInternal":false,"tokens":3988,"sizeBytes":16437},{"name":"plugin-features-reference.md","path":"plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Plugin-Specific Command Features Reference\n\nThis reference covers features and patterns specific to commands bundled in Claude Code plugins.\n\n## Table of Contents\n\n- [Plugin Command Discovery](#plugin-command-discovery)\n- [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable)\n- [Plugin Command Patterns](#plugin-command-patterns)\n- [Integration with Plugin Components](#integration-with-plugin-components)\n- [Validation Patterns](#validation-patterns)\n\n## Plugin Command Discovery\n\n### Auto-Discovery\n\nClaude Code automatically discovers commands in plugins using the following locations:\n\n```\nplugin-name/\n├── commands/ # Auto-discovered commands\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ └── bar.md # /bar (plugin:plugin-name)\n└── plugin.json # Plugin manifest\n```\n\n**Key points:**\n- Commands are discovered at plugin load time\n- No manual registration required\n- Commands appear in `/help` with \"(plugin:plugin-name)\" label\n- Subdirectories create namespaces\n\n### Namespaced Plugin Commands\n\nOrganize commands in subdirectories for logical grouping:\n\n```\nplugin-name/\n└── commands/\n ├── review/\n │ ├── security.md # /security (plugin:plugin-name:review)\n │ └── style.md # /style (plugin:plugin-name:review)\n └── deploy/\n ├── staging.md # /staging (plugin:plugin-name:deploy)\n └── prod.md # /prod (plugin:plugin-name:deploy)\n```\n\n**Namespace behavior:**\n- Subdirectory name becomes namespace\n- Shown as \"(plugin:plugin-name:namespace)\" in `/help`\n- Helps organize related commands\n- Use when plugin has 5+ commands\n\n### Command Naming Conventions\n\n**Plugin command names should:**\n1. Be descriptive and action-oriented\n2. Avoid conflicts with common command names\n3. Use hyphens for multi-word names\n4. Consider prefixing with plugin name for uniqueness\n\n**Examples:**\n```\nGood:\n- /mylyn-sync (plugin-specific prefix)\n- /analyze-performance (descriptive action)\n- /docker-compose-up (clear purpose)\n\nAvoid:\n- /test (conflicts with common name)\n- /run (too generic)\n- /do-stuff (not descriptive)\n```\n\n## CLAUDE_PLUGIN_ROOT Environment Variable\n\n### Purpose\n\n`${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory.\n\n**Why it matters:**\n- Enables portable paths within plugin\n- Allows referencing plugin files and scripts\n- Works across different installations\n- Essential for multi-file plugin operations\n\n### Basic Usage\n\nReference files within your plugin:\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*), Read\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n\nRead template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md\n```\n\n**Expands to:**\n```\nRun analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js`\n\nRead template: @/path/to/plugins/plugin-name/templates/report.md\n```\n\n### Common Patterns\n\n#### 1. Executing Plugin Scripts\n\n```markdown\n---\ndescription: Run custom linter from plugin\nallowed-tools: Bash(node:*)\n---\n\nLint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`\n\nReview the linting output and suggest fixes.\n```\n\n#### 2. Loading Configuration Files\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nallowed-tools: Read, Bash(*)\n---\n\nConfiguration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json\n\nDeploy application using the configuration above for $1 environment.\n```\n\n#### 3. Accessing Plugin Resources\n\n```markdown\n---\ndescription: Generate report from template\n---\n\nUse this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md\n\nGenerate a report for @$1 following the template format.\n```\n\n#### 4. Multi-Step Plugin Workflows\n\n```markdown\n---\ndescription: Complete plugin workflow\nallowed-tools: Bash(*), Read\n---\n\nStep 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`\nStep 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\nStep 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`\n\nReview results and report status.\n```\n\n### Best Practices\n\n1. **Always use for plugin-internal paths:**\n ```markdown\n # Good\n @${CLAUDE_PLUGIN_ROOT}/templates/foo.md\n\n # Bad\n @./templates/foo.md # Relative to current directory, not plugin\n ```\n\n2. **Validate file existence:**\n ```markdown\n ---\n description: Use plugin config if exists\n allowed-tools: Bash(test:*), Read\n ---\n\n !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"exists\" || echo \"missing\"`\n\n If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json\n Otherwise, use defaults...\n ```\n\n3. **Document plugin file structure:**\n ```markdown\n \n ```\n\n4. **Combine with arguments:**\n ```markdown\n Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2`\n ```\n\n### Troubleshooting\n\n**Variable not expanding:**\n- Ensure command is loaded from plugin\n- Check bash execution is allowed\n- Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}`\n\n**File not found errors:**\n- Verify file exists in plugin directory\n- Check file path is correct relative to plugin root\n- Ensure file permissions allow reading/execution\n\n**Path with spaces:**\n- Bash commands automatically handle spaces\n- File references work with spaces in paths\n- No special quoting needed\n\n## Plugin Command Patterns\n\n### Pattern 1: Configuration-Based Commands\n\nCommands that load plugin-specific configuration:\n\n```markdown\n---\ndescription: Deploy using plugin settings\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json\n\nDeploy to $1 environment using:\n1. Configuration settings above\n2. Current git branch: !`git branch --show-current`\n3. Application version: !`cat package.json | grep version`\n\nExecute deployment and monitor progress.\n```\n\n**When to use:** Commands that need consistent settings across invocations\n\n### Pattern 2: Template-Based Generation\n\nCommands that use plugin templates:\n\n```markdown\n---\ndescription: Generate documentation from template\nargument-hint: [component-name]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md\n\nGenerate documentation for $1 component following the template structure.\nInclude:\n- Component purpose and usage\n- API reference\n- Examples\n- Testing guidelines\n```\n\n**When to use:** Standardized output generation\n\n### Pattern 3: Multi-Script Workflow\n\nCommands that orchestrate multiple plugin scripts:\n\n```markdown\n---\ndescription: Complete build and test workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nValidate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\n\nReview all outputs and report:\n1. Build status\n2. Validation results\n3. Test results\n4. Recommended next steps\n```\n\n**When to use:** Complex plugin workflows with multiple steps\n\n### Pattern 4: Environment-Aware Commands\n\nCommands that adapt to environment:\n\n```markdown\n---\ndescription: Deploy based on environment\nargument-hint: [dev|staging|prod]\n---\n\nEnvironment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\nEnvironment check: !`echo \"Deploying to: $1\"`\n\nDeploy application using $1 environment configuration.\nVerify deployment and run smoke tests.\n```\n\n**When to use:** Commands that behave differently per environment\n\n### Pattern 5: Plugin Data Management\n\nCommands that manage plugin-specific data:\n\n```markdown\n---\ndescription: Save analysis results to plugin cache\nallowed-tools: Bash(*), Read, Write\n---\n\nCache directory: ${CLAUDE_PLUGIN_ROOT}/cache/\n\nAnalyze @$1 and save results to cache:\n!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`\n\nStore analysis for future reference and comparison.\n```\n\n**When to use:** Commands that need persistent data storage\n\n## Integration with Plugin Components\n\n### Invoking Plugin Agents\n\nCommands can trigger plugin agents using the Task tool:\n\n```markdown\n---\ndescription: Deep analysis using plugin agent\nargument-hint: [file-path]\n---\n\nInitiate deep code analysis of @$1 using the code-analyzer agent.\n\nThe agent will:\n1. Analyze code structure\n2. Identify patterns\n3. Suggest improvements\n4. Generate detailed report\n\nNote: This uses the Task tool to launch the plugin's code-analyzer agent.\n```\n\n**Key points:**\n- Agent must be defined in plugin's `agents/` directory\n- Claude will automatically use Task tool to launch agent\n- Agent has access to same plugin resources\n\n### Invoking Plugin Skills\n\nCommands can reference plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: API documentation with best practices\nargument-hint: [api-file]\n---\n\nDocument the API in @$1 following our API documentation standards.\n\nUse the api-docs-standards skill to ensure documentation includes:\n- Endpoint descriptions\n- Parameter specifications\n- Response formats\n- Error codes\n- Usage examples\n\nNote: This leverages the plugin's api-docs-standards skill for consistency.\n```\n\n**Key points:**\n- Skill must be defined in plugin's `skills/` directory\n- Mention skill by name to hint Claude should invoke it\n- Skills provide specialized domain knowledge\n\n### Coordinating with Plugin Hooks\n\nCommands can be designed to work with plugin hooks:\n\n```markdown\n---\ndescription: Commit with pre-commit validation\nallowed-tools: Bash(git:*)\n---\n\nStage changes: !\\`git add $1\\`\n\nCommit changes: !\\`git commit -m \"$2\"\\`\n\nNote: This commit will trigger the plugin's pre-commit hook for validation.\nReview hook output for any issues.\n```\n\n**Key points:**\n- Hooks execute automatically on events\n- Commands can prepare state for hooks\n- Document hook interaction in command\n\n### Multi-Component Plugin Commands\n\nCommands that coordinate multiple plugin components:\n\n```markdown\n---\ndescription: Comprehensive code review workflow\nargument-hint: [file-path]\n---\n\nFile to review: @$1\n\nExecute comprehensive review:\n\n1. **Static Analysis** (via plugin scripts)\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\n2. **Deep Review** (via plugin agent)\n Launch the code-reviewer agent for detailed analysis.\n\n3. **Best Practices** (via plugin skill)\n Use the code-standards skill to ensure compliance.\n\n4. **Documentation** (via plugin template)\n Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nGenerate final report combining all outputs.\n```\n\n**When to use:** Complex workflows leveraging multiple plugin capabilities\n\n## Validation Patterns\n\n### Input Validation\n\nCommands should validate inputs before processing:\n\n```markdown\n---\ndescription: Deploy to environment with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\n$IF($1 in [dev, staging, prod],\n Deploy to $1 environment using validated configuration,\n ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod\n)\n```\n\n**Validation approaches:**\n1. Bash validation using grep/test\n2. Inline validation in prompt\n3. Script-based validation\n\n### File Existence Checks\n\nVerify required files exist:\n\n```markdown\n---\ndescription: Process configuration file\nargument-hint: [config-file]\n---\n\nCheck file: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nProcess configuration if file exists: @$1\n\nIf file doesn't exist, explain:\n- Expected location\n- Required format\n- How to create it\n```\n\n### Required Arguments\n\nValidate required arguments provided:\n\n```markdown\n---\ndescription: Create deployment with version\nargument-hint: [environment] [version]\n---\n\nValidate inputs: !`test -n \"$1\" -a -n \"$2\" && echo \"OK\" || echo \"MISSING\"`\n\n$IF($1 AND $2,\n Deploy version $2 to $1 environment,\n ERROR: Both environment and version required. Usage: /deploy [env] [version]\n)\n```\n\n### Plugin Resource Validation\n\nVerify plugin resources available:\n\n```markdown\n---\ndescription: Run analysis with plugin tools\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n- Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo \"✓\" || echo \"✗\"`\n- Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, proceed with analysis.\nOtherwise, report missing components and installation steps.\n```\n\n### Output Validation\n\nValidate command execution results:\n\n```markdown\n---\ndescription: Build and validate output\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\n\nValidate output:\n- Exit code: !`echo $?`\n- Output exists: !`test -d dist && echo \"✓\" || echo \"✗\"`\n- File count: !`find dist -type f | wc -l`\n\nReport build status and any validation failures.\n```\n\n### Graceful Error Handling\n\nHandle errors gracefully with helpful messages:\n\n```markdown\n---\ndescription: Process file with error handling\nargument-hint: [file-path]\n---\n\nTry processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo \"ERROR: $?\"`\n\nIf processing succeeded:\n- Report results\n- Suggest next steps\n\nIf processing failed:\n- Explain likely causes\n- Provide troubleshooting steps\n- Suggest alternative approaches\n```\n\n## Best Practices Summary\n\n### Plugin Commands Should:\n\n1. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths**\n - Scripts, templates, configuration, resources\n\n2. **Validate inputs early**\n - Check required arguments\n - Verify file existence\n - Validate argument formats\n\n3. **Document plugin structure**\n - Explain required files\n - Document script purposes\n - Clarify dependencies\n\n4. **Integrate with plugin components**\n - Reference agents for complex tasks\n - Use skills for specialized knowledge\n - Coordinate with hooks when relevant\n\n5. **Provide helpful error messages**\n - Explain what went wrong\n - Suggest how to fix\n - Offer alternatives\n\n6. **Handle edge cases**\n - Missing files\n - Invalid arguments\n - Failed script execution\n - Missing dependencies\n\n7. **Keep commands focused**\n - One clear purpose per command\n - Delegate complex logic to scripts\n - Use agents for multi-step workflows\n\n8. **Test across installations**\n - Verify paths work everywhere\n - Test with different arguments\n - Validate error cases\n\n---\n\nFor general command development, see main SKILL.md.\nFor command examples, see examples/ directory.\n","isInternal":false,"tokens":3344,"sizeBytes":14622},{"name":"testing-strategies.md","path":"plugins/plugin-dev/skills/command-development/references/testing-strategies.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/references/testing-strategies.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Command Testing Strategies\n\nComprehensive strategies for testing slash commands before deployment and distribution.\n\n## Overview\n\nTesting commands ensures they work correctly, handle edge cases, and provide good user experience. A systematic testing approach catches issues early and builds confidence in command reliability.\n\n## Testing Levels\n\n### Level 1: Syntax and Structure Validation\n\n**What to test:**\n- YAML frontmatter syntax\n- Markdown format\n- File location and naming\n\n**How to test:**\n\n```bash\n# Validate YAML frontmatter\nhead -n 20 .claude/commands/my-command.md | grep -A 10 \"^---\"\n\n# Check for closing frontmatter marker\nhead -n 20 .claude/commands/my-command.md | grep -c \"^---\" # Should be 2\n\n# Verify file has .md extension\nls .claude/commands/*.md\n\n# Check file is in correct location\ntest -f .claude/commands/my-command.md && echo \"Found\" || echo \"Missing\"\n```\n\n**Automated validation script:**\n\n```bash\n#!/bin/bash\n# validate-command.sh\n\nCOMMAND_FILE=\"$1\"\n\nif [ ! -f \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File not found: $COMMAND_FILE\"\n exit 1\nfi\n\n# Check .md extension\nif [[ ! \"$COMMAND_FILE\" =~ \\.md$ ]]; then\n echo \"ERROR: File must have .md extension\"\n exit 1\nfi\n\n# Validate YAML frontmatter if present\nif head -n 1 \"$COMMAND_FILE\" | grep -q \"^---\"; then\n # Count frontmatter markers\n MARKERS=$(head -n 50 \"$COMMAND_FILE\" | grep -c \"^---\")\n if [ \"$MARKERS\" -ne 2 ]; then\n echo \"ERROR: Invalid YAML frontmatter (need exactly 2 '---' markers)\"\n exit 1\n fi\n echo \"✓ YAML frontmatter syntax valid\"\nfi\n\n# Check for empty file\nif [ ! -s \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File is empty\"\n exit 1\nfi\n\necho \"✓ Command file structure valid\"\n```\n\n### Level 2: Frontmatter Field Validation\n\n**What to test:**\n- Field types correct\n- Values in valid ranges\n- Required fields present (if any)\n\n**Validation script:**\n\n```bash\n#!/bin/bash\n# validate-frontmatter.sh\n\nCOMMAND_FILE=\"$1\"\n\n# Extract YAML frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/p' \"$COMMAND_FILE\" | sed '1d;$d')\n\nif [ -z \"$FRONTMATTER\" ]; then\n echo \"No frontmatter to validate\"\n exit 0\nfi\n\n# Check 'model' field if present\nif echo \"$FRONTMATTER\" | grep -q \"^model:\"; then\n MODEL=$(echo \"$FRONTMATTER\" | grep \"^model:\" | cut -d: -f2 | tr -d ' ')\n if ! echo \"sonnet opus haiku\" | grep -qw \"$MODEL\"; then\n echo \"ERROR: Invalid model '$MODEL' (must be sonnet, opus, or haiku)\"\n exit 1\n fi\n echo \"✓ Model field valid: $MODEL\"\nfi\n\n# Check 'allowed-tools' field format\nif echo \"$FRONTMATTER\" | grep -q \"^allowed-tools:\"; then\n echo \"✓ allowed-tools field present\"\n # Could add more sophisticated validation here\nfi\n\n# Check 'description' length\nif echo \"$FRONTMATTER\" | grep -q \"^description:\"; then\n DESC=$(echo \"$FRONTMATTER\" | grep \"^description:\" | cut -d: -f2-)\n LENGTH=${#DESC}\n if [ \"$LENGTH\" -gt 80 ]; then\n echo \"WARNING: Description length $LENGTH (recommend < 60 chars)\"\n else\n echo \"✓ Description length acceptable: $LENGTH chars\"\n fi\nfi\n\necho \"✓ Frontmatter fields valid\"\n```\n\n### Level 3: Manual Command Invocation\n\n**What to test:**\n- Command appears in `/help`\n- Command executes without errors\n- Output is as expected\n\n**Test procedure:**\n\n```bash\n# 1. Start Claude Code\nclaude --debug\n\n# 2. Check command appears in help\n> /help\n# Look for your command in the list\n\n# 3. Invoke command without arguments\n> /my-command\n# Check for reasonable error or behavior\n\n# 4. Invoke with valid arguments\n> /my-command arg1 arg2\n# Verify expected behavior\n\n# 5. Check debug logs\ntail -f ~/.claude/debug-logs/latest\n# Look for errors or warnings\n```\n\n### Level 4: Argument Testing\n\n**What to test:**\n- Positional arguments work ($1, $2, etc.)\n- $ARGUMENTS captures all arguments\n- Missing arguments handled gracefully\n- Invalid arguments detected\n\n**Test matrix:**\n\n| Test Case | Command | Expected Result |\n|-----------|---------|-----------------|\n| No args | `/cmd` | Graceful handling or useful message |\n| One arg | `/cmd arg1` | $1 substituted correctly |\n| Two args | `/cmd arg1 arg2` | $1 and $2 substituted |\n| Extra args | `/cmd a b c d` | All captured or extras ignored appropriately |\n| Special chars | `/cmd \"arg with spaces\"` | Quotes handled correctly |\n| Empty arg | `/cmd \"\"` | Empty string handled |\n\n**Test script:**\n\n```bash\n#!/bin/bash\n# test-command-arguments.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing argument handling for /$COMMAND\"\necho\n\necho \"Test 1: No arguments\"\necho \" Command: /$COMMAND\"\necho \" Expected: [describe expected behavior]\"\necho \" Manual test required\"\necho\n\necho \"Test 2: Single argument\"\necho \" Command: /$COMMAND test-value\"\necho \" Expected: 'test-value' appears in output\"\necho \" Manual test required\"\necho\n\necho \"Test 3: Multiple arguments\"\necho \" Command: /$COMMAND arg1 arg2 arg3\"\necho \" Expected: All arguments used appropriately\"\necho \" Manual test required\"\necho\n\necho \"Test 4: Special characters\"\necho \" Command: /$COMMAND \\\"value with spaces\\\"\"\necho \" Expected: Entire phrase captured\"\necho \" Manual test required\"\n```\n\n### Level 5: File Reference Testing\n\n**What to test:**\n- @ syntax loads file contents\n- Non-existent files handled\n- Large files handled appropriately\n- Multiple file references work\n\n**Test procedure:**\n\n```bash\n# Create test files\necho \"Test content\" > /tmp/test-file.txt\necho \"Second file\" > /tmp/test-file-2.txt\n\n# Test single file reference\n> /my-command /tmp/test-file.txt\n# Verify file content is read\n\n# Test non-existent file\n> /my-command /tmp/nonexistent.txt\n# Verify graceful error handling\n\n# Test multiple files\n> /my-command /tmp/test-file.txt /tmp/test-file-2.txt\n# Verify both files processed\n\n# Test large file\ndd if=/dev/zero of=/tmp/large-file.bin bs=1M count=100\n> /my-command /tmp/large-file.bin\n# Verify reasonable behavior (may truncate or warn)\n\n# Cleanup\nrm /tmp/test-file*.txt /tmp/large-file.bin\n```\n\n### Level 6: Bash Execution Testing\n\n**What to test:**\n- !` commands execute correctly\n- Command output included in prompt\n- Command failures handled\n- Security: only allowed commands run\n\n**Test procedure:**\n\n```bash\n# Create test command with bash execution\ncat > .claude/commands/test-bash.md << 'EOF'\n---\ndescription: Test bash execution\nallowed-tools: Bash(echo:*), Bash(date:*)\n---\n\nCurrent date: !`date`\nTest output: !`echo \"Hello from bash\"`\n\nAnalysis of output above...\nEOF\n\n# Test in Claude Code\n> /test-bash\n# Verify:\n# 1. Date appears correctly\n# 2. Echo output appears\n# 3. No errors in debug logs\n\n# Test with disallowed command (should fail or be blocked)\ncat > .claude/commands/test-forbidden.md << 'EOF'\n---\ndescription: Test forbidden command\nallowed-tools: Bash(echo:*)\n---\n\nTrying forbidden: !`ls -la /`\nEOF\n\n> /test-forbidden\n# Verify: Permission denied or appropriate error\n```\n\n### Level 7: Integration Testing\n\n**What to test:**\n- Commands work with other plugin components\n- Commands interact correctly with each other\n- State management works across invocations\n- Workflow commands execute in sequence\n\n**Test scenarios:**\n\n**Scenario 1: Command + Hook Integration**\n\n```bash\n# Setup: Command that triggers a hook\n# Test: Invoke command, verify hook executes\n\n# Command: .claude/commands/risky-operation.md\n# Hook: PreToolUse that validates the operation\n\n> /risky-operation\n# Verify: Hook executes and validates before command completes\n```\n\n**Scenario 2: Command Sequence**\n\n```bash\n# Setup: Multi-command workflow\n> /workflow-init\n# Verify: State file created\n\n> /workflow-step2\n# Verify: State file read, step 2 executes\n\n> /workflow-complete\n# Verify: State file cleaned up\n```\n\n**Scenario 3: Command + MCP Integration**\n\n```bash\n# Setup: Command uses MCP tools\n# Test: Verify MCP server accessible\n\n> /mcp-command\n# Verify:\n# 1. MCP server starts (if stdio)\n# 2. Tool calls succeed\n# 3. Results included in output\n```\n\n## Automated Testing Approaches\n\n### Command Test Suite\n\nCreate a test suite script:\n\n```bash\n#!/bin/bash\n# test-commands.sh - Command test suite\n\nTEST_DIR=\".claude/commands\"\nFAILED_TESTS=0\n\necho \"Command Test Suite\"\necho \"==================\"\necho\n\nfor cmd_file in \"$TEST_DIR\"/*.md; do\n cmd_name=$(basename \"$cmd_file\" .md)\n echo \"Testing: $cmd_name\"\n\n # Validate structure\n if ./validate-command.sh \"$cmd_file\"; then\n echo \" ✓ Structure valid\"\n else\n echo \" ✗ Structure invalid\"\n ((FAILED_TESTS++))\n fi\n\n # Validate frontmatter\n if ./validate-frontmatter.sh \"$cmd_file\"; then\n echo \" ✓ Frontmatter valid\"\n else\n echo \" ✗ Frontmatter invalid\"\n ((FAILED_TESTS++))\n fi\n\n echo\ndone\n\necho \"==================\"\necho \"Tests complete\"\necho \"Failed: $FAILED_TESTS\"\n\nexit $FAILED_TESTS\n```\n\n### Pre-Commit Hook\n\nValidate commands before committing:\n\n```bash\n#!/bin/bash\n# .git/hooks/pre-commit\n\necho \"Validating commands...\"\n\nCOMMANDS_CHANGED=$(git diff --cached --name-only | grep \"\\.claude/commands/.*\\.md\")\n\nif [ -z \"$COMMANDS_CHANGED\" ]; then\n echo \"No commands changed\"\n exit 0\nfi\n\nfor cmd in $COMMANDS_CHANGED; do\n echo \"Checking: $cmd\"\n\n if ! ./scripts/validate-command.sh \"$cmd\"; then\n echo \"ERROR: Command validation failed: $cmd\"\n exit 1\n fi\ndone\n\necho \"✓ All commands valid\"\n```\n\n### Continuous Testing\n\nTest commands in CI/CD:\n\n```yaml\n# .github/workflows/test-commands.yml\nname: Test Commands\n\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n\n - name: Validate command structure\n run: |\n for cmd in .claude/commands/*.md; do\n echo \"Testing: $cmd\"\n ./scripts/validate-command.sh \"$cmd\"\n done\n\n - name: Validate frontmatter\n run: |\n for cmd in .claude/commands/*.md; do\n ./scripts/validate-frontmatter.sh \"$cmd\"\n done\n\n - name: Check for TODOs\n run: |\n if grep -r \"TODO\" .claude/commands/; then\n echo \"ERROR: TODOs found in commands\"\n exit 1\n fi\n```\n\n## Edge Case Testing\n\n### Test Edge Cases\n\n**Empty arguments:**\n```bash\n> /cmd \"\"\n> /cmd '' ''\n```\n\n**Special characters:**\n```bash\n> /cmd \"arg with spaces\"\n> /cmd arg-with-dashes\n> /cmd arg_with_underscores\n> /cmd arg/with/slashes\n> /cmd 'arg with \"quotes\"'\n```\n\n**Long arguments:**\n```bash\n> /cmd $(python -c \"print('a' * 10000)\")\n```\n\n**Unusual file paths:**\n```bash\n> /cmd ./file\n> /cmd ../file\n> /cmd ~/file\n> /cmd \"/path with spaces/file\"\n```\n\n**Bash command edge cases:**\n```markdown\n# Commands that might fail\n!`exit 1`\n!`false`\n!`command-that-does-not-exist`\n\n# Commands with special output\n!`echo \"\"`\n!`cat /dev/null`\n!`yes | head -n 1000000`\n```\n\n## Performance Testing\n\n### Response Time Testing\n\n```bash\n#!/bin/bash\n# test-command-performance.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing performance of /$COMMAND\"\necho\n\nfor i in {1..5}; do\n echo \"Run $i:\"\n START=$(date +%s%N)\n\n # Invoke command (manual step - record time)\n echo \" Invoke: /$COMMAND\"\n echo \" Start time: $START\"\n echo \" (Record end time manually)\"\n echo\ndone\n\necho \"Analyze results:\"\necho \" - Average response time\"\necho \" - Variance\"\necho \" - Acceptable threshold: < 3 seconds for fast commands\"\n```\n\n### Resource Usage Testing\n\n```bash\n# Monitor Claude Code during command execution\n# In terminal 1:\nclaude --debug\n\n# In terminal 2:\nwatch -n 1 'ps aux | grep claude'\n\n# Execute command and observe:\n# - Memory usage\n# - CPU usage\n# - Process count\n```\n\n## User Experience Testing\n\n### Usability Checklist\n\n- [ ] Command name is intuitive\n- [ ] Description is clear in `/help`\n- [ ] Arguments are well-documented\n- [ ] Error messages are helpful\n- [ ] Output is formatted readably\n- [ ] Long-running commands show progress\n- [ ] Results are actionable\n- [ ] Edge cases have good UX\n\n### User Acceptance Testing\n\nRecruit testers:\n\n```markdown\n# Testing Guide for Beta Testers\n\n## Command: /my-new-command\n\n### Test Scenarios\n\n1. **Basic usage:**\n - Run: `/my-new-command`\n - Expected: [describe]\n - Rate clarity: 1-5\n\n2. **With arguments:**\n - Run: `/my-new-command arg1 arg2`\n - Expected: [describe]\n - Rate usefulness: 1-5\n\n3. **Error case:**\n - Run: `/my-new-command invalid-input`\n - Expected: Helpful error message\n - Rate error message: 1-5\n\n### Feedback Questions\n\n1. Was the command easy to understand?\n2. Did the output meet your expectations?\n3. What would you change?\n4. Would you use this command regularly?\n```\n\n## Testing Checklist\n\nBefore releasing a command:\n\n### Structure\n- [ ] File in correct location\n- [ ] Correct .md extension\n- [ ] Valid YAML frontmatter (if present)\n- [ ] Markdown syntax correct\n\n### Functionality\n- [ ] Command appears in `/help`\n- [ ] Description is clear\n- [ ] Command executes without errors\n- [ ] Arguments work as expected\n- [ ] File references work\n- [ ] Bash execution works (if used)\n\n### Edge Cases\n- [ ] Missing arguments handled\n- [ ] Invalid arguments detected\n- [ ] Non-existent files handled\n- [ ] Special characters work\n- [ ] Long inputs handled\n\n### Integration\n- [ ] Works with other commands\n- [ ] Works with hooks (if applicable)\n- [ ] Works with MCP (if applicable)\n- [ ] State management works\n\n### Quality\n- [ ] Performance acceptable\n- [ ] No security issues\n- [ ] Error messages helpful\n- [ ] Output formatted well\n- [ ] Documentation complete\n\n### Distribution\n- [ ] Tested by others\n- [ ] Feedback incorporated\n- [ ] README updated\n- [ ] Examples provided\n\n## Debugging Failed Tests\n\n### Common Issues and Solutions\n\n**Issue: Command not appearing in /help**\n\n```bash\n# Check file location\nls -la .claude/commands/my-command.md\n\n# Check permissions\nchmod 644 .claude/commands/my-command.md\n\n# Check syntax\nhead -n 20 .claude/commands/my-command.md\n\n# Restart Claude Code\nclaude --debug\n```\n\n**Issue: Arguments not substituting**\n\n```bash\n# Verify syntax\ngrep '\\$1' .claude/commands/my-command.md\ngrep '\\$ARGUMENTS' .claude/commands/my-command.md\n\n# Test with simple command first\necho \"Test: \\$1 and \\$2\" > .claude/commands/test-args.md\n```\n\n**Issue: Bash commands not executing**\n\n```bash\n# Check allowed-tools\ngrep \"allowed-tools\" .claude/commands/my-command.md\n\n# Verify command syntax\ngrep '!\\`' .claude/commands/my-command.md\n\n# Test command manually\ndate\necho \"test\"\n```\n\n**Issue: File references not working**\n\n```bash\n# Check @ syntax\ngrep '@' .claude/commands/my-command.md\n\n# Verify file exists\nls -la /path/to/referenced/file\n\n# Check permissions\nchmod 644 /path/to/referenced/file\n```\n\n## Best Practices\n\n1. **Test early, test often**: Validate as you develop\n2. **Automate validation**: Use scripts for repeatable checks\n3. **Test edge cases**: Don't just test the happy path\n4. **Get feedback**: Have others test before wide release\n5. **Document tests**: Keep test scenarios for regression testing\n6. **Monitor in production**: Watch for issues after release\n7. **Iterate**: Improve based on real usage data\n","isInternal":false,"tokens":3974,"sizeBytes":14803},{"name":"SKILL.md","path":"plugins/plugin-dev/skills/command-development/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/SKILL.md","title":"Command Development","category":"anthropic-skill","format":"markdown","content":"---\nname: Command Development\ndescription: This skill should be used when the user asks to \"create a slash command\", \"add a command\", \"write a custom command\", \"define command arguments\", \"use command frontmatter\", \"organize commands\", \"create command with file references\", \"interactive command\", \"use AskUserQuestion in command\", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.\nversion: 0.2.0\n---\n\n# Command Development for Claude Code\n\n## Overview\n\nSlash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.\n\n**Key concepts:**\n- Markdown file format for commands\n- YAML frontmatter for configuration\n- Dynamic arguments and file references\n- Bash execution for context\n- Command organization and namespacing\n\n## Command Basics\n\n### What is a Slash Command?\n\nA slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:\n- **Reusability**: Define once, use repeatedly\n- **Consistency**: Standardize common workflows\n- **Sharing**: Distribute across team or projects\n- **Efficiency**: Quick access to complex prompts\n\n### Critical: Commands are Instructions FOR Claude\n\n**Commands are written for agent consumption, not human consumption.**\n\nWhen a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.\n\n**Correct approach (instructions for Claude):**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication issues\n\nProvide specific line numbers and severity ratings.\n```\n\n**Incorrect approach (messages to user):**\n```markdown\nThis command will review your code for security issues.\nYou'll receive a report with vulnerability details.\n```\n\nThe first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.\n\n### Command Locations\n\n**Project commands** (shared with team):\n- Location: `.claude/commands/`\n- Scope: Available in specific project\n- Label: Shown as \"(project)\" in `/help`\n- Use for: Team workflows, project-specific tasks\n\n**Personal commands** (available everywhere):\n- Location: `~/.claude/commands/`\n- Scope: Available in all projects\n- Label: Shown as \"(user)\" in `/help`\n- Use for: Personal workflows, cross-project utilities\n\n**Plugin commands** (bundled with plugins):\n- Location: `plugin-name/commands/`\n- Scope: Available when plugin installed\n- Label: Shown as \"(plugin-name)\" in `/help`\n- Use for: Plugin-specific functionality\n\n## File Format\n\n### Basic Structure\n\nCommands are Markdown files with `.md` extension:\n\n```\n.claude/commands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**Simple command:**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication bypass\n- Insecure data handling\n```\n\nNo frontmatter needed for basic commands.\n\n### With YAML Frontmatter\n\nAdd configuration using YAML frontmatter:\n\n```markdown\n---\ndescription: Review code for security issues\nallowed-tools: Read, Grep, Bash(git:*)\nmodel: sonnet\n---\n\nReview this code for security vulnerabilities...\n```\n\n## YAML Frontmatter Fields\n\n### description\n\n**Purpose:** Brief description shown in `/help`\n**Type:** String\n**Default:** First line of command prompt\n\n```yaml\n---\ndescription: Review pull request for code quality\n---\n```\n\n**Best practice:** Clear, actionable description (under 60 characters)\n\n### allowed-tools\n\n**Purpose:** Specify which tools command can use\n**Type:** String or Array\n**Default:** Inherits from conversation\n\n```yaml\n---\nallowed-tools: Read, Write, Edit, Bash(git:*)\n---\n```\n\n**Patterns:**\n- `Read, Write, Edit` - Specific tools\n- `Bash(git:*)` - Bash with git commands only\n- `*` - All tools (rarely needed)\n\n**Use when:** Command requires specific tool access\n\n### model\n\n**Purpose:** Specify model for command execution\n**Type:** String (sonnet, opus, haiku)\n**Default:** Inherits from conversation\n\n```yaml\n---\nmodel: haiku\n---\n```\n\n**Use cases:**\n- `haiku` - Fast, simple commands\n- `sonnet` - Standard workflows\n- `opus` - Complex analysis\n\n### argument-hint\n\n**Purpose:** Document expected arguments for autocomplete\n**Type:** String\n**Default:** None\n\n```yaml\n---\nargument-hint: [pr-number] [priority] [assignee]\n---\n```\n\n**Benefits:**\n- Helps users understand command arguments\n- Improves command discovery\n- Documents command interface\n\n### disable-model-invocation\n\n**Purpose:** Prevent SlashCommand tool from programmatically calling command\n**Type:** Boolean\n**Default:** false\n\n```yaml\n---\ndisable-model-invocation: true\n---\n```\n\n**Use when:** Command should only be manually invoked\n\n## Dynamic Arguments\n\n### Using $ARGUMENTS\n\nCapture all arguments as single string:\n\n```markdown\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$ARGUMENTS following our coding standards and best practices.\n```\n\n**Usage:**\n```\n> /fix-issue 123\n> /fix-issue 456\n```\n\n**Expands to:**\n```\nFix issue #123 following our coding standards...\nFix issue #456 following our coding standards...\n```\n\n### Using Positional Arguments\n\nCapture individual arguments with `$1`, `$2`, `$3`, etc.:\n\n```markdown\n---\ndescription: Review PR with priority and assignee\nargument-hint: [pr-number] [priority] [assignee]\n---\n\nReview pull request #$1 with priority level $2.\nAfter review, assign to $3 for follow-up.\n```\n\n**Usage:**\n```\n> /review-pr 123 high alice\n```\n\n**Expands to:**\n```\nReview pull request #123 with priority level high.\nAfter review, assign to alice for follow-up.\n```\n\n### Combining Arguments\n\nMix positional and remaining arguments:\n\n```markdown\nDeploy $1 to $2 environment with options: $3\n```\n\n**Usage:**\n```\n> /deploy api staging --force --skip-tests\n```\n\n**Expands to:**\n```\nDeploy api to staging environment with options: --force --skip-tests\n```\n\n## File References\n\n### Using @ Syntax\n\nInclude file contents in command:\n\n```markdown\n---\ndescription: Review specific file\nargument-hint: [file-path]\n---\n\nReview @$1 for:\n- Code quality\n- Best practices\n- Potential bugs\n```\n\n**Usage:**\n```\n> /review-file src/api/users.ts\n```\n\n**Effect:** Claude reads `src/api/users.ts` before processing command\n\n### Multiple File References\n\nReference multiple files:\n\n```markdown\nCompare @src/old-version.js with @src/new-version.js\n\nIdentify:\n- Breaking changes\n- New features\n- Bug fixes\n```\n\n### Static File References\n\nReference known files without arguments:\n\n```markdown\nReview @package.json and @tsconfig.json for consistency\n\nEnsure:\n- TypeScript version matches\n- Dependencies are aligned\n- Build configuration is correct\n```\n\n## Bash Execution in Commands\n\nCommands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.\n\n**When to use:**\n- Include dynamic context (git status, environment vars, etc.)\n- Gather project/repository state\n- Build context-aware workflows\n\n**Implementation details:**\nFor complete syntax, examples, and best practices, see `references/plugin-features-reference.md` section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues\n\n## Command Organization\n\n### Flat Structure\n\nSimple organization for small command sets:\n\n```\n.claude/commands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**Use when:** 5-15 commands, no clear categories\n\n### Namespaced Structure\n\nOrganize commands in subdirectories:\n\n```\n.claude/commands/\n├── ci/\n│ ├── build.md # /build (project:ci)\n│ ├── test.md # /test (project:ci)\n│ └── lint.md # /lint (project:ci)\n├── git/\n│ ├── commit.md # /commit (project:git)\n│ └── pr.md # /pr (project:git)\n└── docs/\n ├── generate.md # /generate (project:docs)\n └── publish.md # /publish (project:docs)\n```\n\n**Benefits:**\n- Logical grouping by category\n- Namespace shown in `/help`\n- Easier to find related commands\n\n**Use when:** 15+ commands, clear categories\n\n## Best Practices\n\n### Command Design\n\n1. **Single responsibility:** One command, one task\n2. **Clear descriptions:** Self-explanatory in `/help`\n3. **Explicit dependencies:** Use `allowed-tools` when needed\n4. **Document arguments:** Always provide `argument-hint`\n5. **Consistent naming:** Use verb-noun pattern (review-pr, fix-issue)\n\n### Argument Handling\n\n1. **Validate arguments:** Check for required arguments in prompt\n2. **Provide defaults:** Suggest defaults when arguments missing\n3. **Document format:** Explain expected argument format\n4. **Handle edge cases:** Consider missing or invalid arguments\n\n```markdown\n---\nargument-hint: [pr-number]\n---\n\n$IF($1,\n Review PR #$1,\n Please provide a PR number. Usage: /review-pr [number]\n)\n```\n\n### File References\n\n1. **Explicit paths:** Use clear file paths\n2. **Check existence:** Handle missing files gracefully\n3. **Relative paths:** Use project-relative paths\n4. **Glob support:** Consider using Glob tool for patterns\n\n### Bash Commands\n\n1. **Limit scope:** Use `Bash(git:*)` not `Bash(*)`\n2. **Safe commands:** Avoid destructive operations\n3. **Handle errors:** Consider command failures\n4. **Keep fast:** Long-running commands slow invocation\n\n### Documentation\n\n1. **Add comments:** Explain complex logic\n2. **Provide examples:** Show usage in comments\n3. **List requirements:** Document dependencies\n4. **Version commands:** Note breaking changes\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment] [version]\n---\n\n\n\nDeploy application to $1 environment using version $2...\n```\n\n## Common Patterns\n\n### Review Pattern\n\n```markdown\n---\ndescription: Review code changes\nallowed-tools: Read, Bash(git:*)\n---\n\nFiles changed: !`git diff --name-only`\n\nReview each file for:\n1. Code quality and style\n2. Potential bugs or issues\n3. Test coverage\n4. Documentation needs\n\nProvide specific feedback for each file.\n```\n\n### Testing Pattern\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*)\n---\n\nRun tests: !`npm test $1`\n\nAnalyze results and suggest fixes for failures.\n```\n\n### Documentation Pattern\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1 including:\n- Function/class descriptions\n- Parameter documentation\n- Return value descriptions\n- Usage examples\n- Edge cases and errors\n```\n\n### Workflow Pattern\n\n```markdown\n---\ndescription: Complete PR workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read\n---\n\nPR #$1 Workflow:\n\n1. Fetch PR: !`gh pr view $1`\n2. Review changes\n3. Run checks\n4. Approve or request changes\n```\n\n## Troubleshooting\n\n**Command not appearing:**\n- Check file is in correct directory\n- Verify `.md` extension present\n- Ensure valid Markdown format\n- Restart Claude Code\n\n**Arguments not working:**\n- Verify `$1`, `$2` syntax correct\n- Check `argument-hint` matches usage\n- Ensure no extra spaces\n\n**Bash execution failing:**\n- Check `allowed-tools` includes Bash\n- Verify command syntax in backticks\n- Test command in terminal first\n- Check for required permissions\n\n**File references not working:**\n- Verify `@` syntax correct\n- Check file path is valid\n- Ensure Read tool allowed\n- Use absolute or project-relative paths\n\n## Plugin-Specific Features\n\n### CLAUDE_PLUGIN_ROOT Variable\n\nPlugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path.\n\n**Purpose:**\n- Reference plugin files portably\n- Execute plugin scripts\n- Load plugin configuration\n- Access plugin templates\n\n**Basic usage:**\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*)\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\nReview results and report findings.\n```\n\n**Common patterns:**\n\n```markdown\n# Execute plugin script\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n\n# Load plugin configuration\n@${CLAUDE_PLUGIN_ROOT}/config/settings.json\n\n# Use plugin template\n@${CLAUDE_PLUGIN_ROOT}/templates/report.md\n\n# Access plugin resources\n@${CLAUDE_PLUGIN_ROOT}/docs/reference.md\n```\n\n**Why use it:**\n- Works across all installations\n- Portable between systems\n- No hardcoded paths needed\n- Essential for multi-file plugins\n\n### Plugin Command Organization\n\nPlugin commands discovered automatically from `commands/` directory:\n\n```\nplugin-name/\n├── commands/\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ ├── bar.md # /bar (plugin:plugin-name)\n│ └── utils/\n│ └── helper.md # /helper (plugin:plugin-name:utils)\n└── plugin.json\n```\n\n**Namespace benefits:**\n- Logical command grouping\n- Shown in `/help` output\n- Avoid name conflicts\n- Organize related commands\n\n**Naming conventions:**\n- Use descriptive action names\n- Avoid generic names (test, run)\n- Consider plugin-specific prefix\n- Use hyphens for multi-word names\n\n### Plugin Command Patterns\n\n**Configuration-based pattern:**\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nDeploy to $1 using configuration settings.\nMonitor deployment and report status.\n```\n\n**Template-based pattern:**\n\n```markdown\n---\ndescription: Generate docs from template\nargument-hint: [component]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md\n\nGenerate documentation for $1 following template structure.\n```\n\n**Multi-script pattern:**\n\n```markdown\n---\ndescription: Complete build workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\nPackage: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`\n\nReview outputs and report workflow status.\n```\n\n**See `references/plugin-features-reference.md` for detailed patterns.**\n\n## Integration with Plugin Components\n\nCommands can integrate with other plugin components for powerful workflows.\n\n### Agent Integration\n\nLaunch plugin agents for complex tasks:\n\n```markdown\n---\ndescription: Deep code review\nargument-hint: [file-path]\n---\n\nInitiate comprehensive review of @$1 using the code-reviewer agent.\n\nThe agent will analyze:\n- Code structure\n- Security issues\n- Performance\n- Best practices\n\nAgent uses plugin resources:\n- ${CLAUDE_PLUGIN_ROOT}/config/rules.json\n- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md\n```\n\n**Key points:**\n- Agent must exist in `plugin/agents/` directory\n- Claude uses Task tool to launch agent\n- Document agent capabilities\n- Reference plugin resources agent uses\n\n### Skill Integration\n\nLeverage plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: Document API with standards\nargument-hint: [api-file]\n---\n\nDocument API in @$1 following plugin standards.\n\nUse the api-docs-standards skill to ensure:\n- Complete endpoint documentation\n- Consistent formatting\n- Example quality\n- Error documentation\n\nGenerate production-ready API docs.\n```\n\n**Key points:**\n- Skill must exist in `plugin/skills/` directory\n- Mention skill name to trigger invocation\n- Document skill purpose\n- Explain what skill provides\n\n### Hook Coordination\n\nDesign commands that work with plugin hooks:\n- Commands can prepare state for hooks to process\n- Hooks execute automatically on tool events\n- Commands should document expected hook behavior\n- Guide Claude on interpreting hook output\n\nSee `references/plugin-features-reference.md` for examples of commands that coordinate with hooks\n\n### Multi-Component Workflows\n\nCombine agents, skills, and scripts:\n\n```markdown\n---\ndescription: Comprehensive review workflow\nargument-hint: [file]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget: @$1\n\nPhase 1 - Static Analysis:\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\nPhase 2 - Deep Review:\nLaunch code-reviewer agent for detailed analysis.\n\nPhase 3 - Standards Check:\nUse coding-standards skill for validation.\n\nPhase 4 - Report:\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review.md\n\nCompile findings into report following template.\n```\n\n**When to use:**\n- Complex multi-step workflows\n- Leverage multiple plugin capabilities\n- Require specialized analysis\n- Need structured outputs\n\n## Validation Patterns\n\nCommands should validate inputs and resources before processing.\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\nIf $1 is valid environment:\n Deploy to $1\nOtherwise:\n Explain valid environments: dev, staging, prod\n Show usage: /deploy [environment]\n```\n\n### File Existence Checks\n\n```markdown\n---\ndescription: Process configuration\nargument-hint: [config-file]\n---\n\nCheck file exists: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nIf file exists:\n Process configuration: @$1\nOtherwise:\n Explain where to place config file\n Show expected format\n Provide example configuration\n```\n\n### Plugin Resource Validation\n\n```markdown\n---\ndescription: Run plugin analyzer\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, run analysis.\nOtherwise, report missing components.\n```\n\n### Error Handling\n\n```markdown\n---\ndescription: Build with error handling\nallowed-tools: Bash(*)\n---\n\nExecute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo \"BUILD_FAILED\"`\n\nIf build succeeded:\n Report success and output location\nIf build failed:\n Analyze error output\n Suggest likely causes\n Provide troubleshooting steps\n```\n\n**Best practices:**\n- Validate early in command\n- Provide helpful error messages\n- Suggest corrective actions\n- Handle edge cases gracefully\n\n---\n\nFor detailed frontmatter field specifications, see `references/frontmatter-reference.md`.\nFor plugin-specific features and patterns, see `references/plugin-features-reference.md`.\nFor command pattern examples, see `examples/` directory.\n","frontmatter":{"name":"Command Development","description":"This skill should be used when the user asks to \"create a slash command\", \"add a command\", \"write a custom command\", \"define command arguments\", \"use command frontmatter\", \"organize commands\", \"create command with file references\", \"interactive command\", \"use AskUserQuestion in command\", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.","version":"0.2.0"},"isInternal":false,"tokens":4281,"sizeBytes":18941},{"name":"advanced.md","path":"plugins/plugin-dev/skills/hook-development/references/advanced.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/hook-development/references/advanced.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Advanced Hook Use Cases\n\nThis reference covers advanced hook patterns and techniques for sophisticated automation workflows.\n\n## Multi-Stage Validation\n\nCombine command and prompt hooks for layered validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Use case:** Fast deterministic checks followed by intelligent analysis\n\n**Example quick-check.sh:**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Immediate approval for safe commands\nif [[ \"$command\" =~ ^(ls|pwd|echo|date|whoami)$ ]]; then\n exit 0\nfi\n\n# Let prompt hook handle complex cases\nexit 0\n```\n\nThe command hook quickly approves obviously safe commands, while the prompt hook analyzes everything else.\n\n## Conditional Hook Execution\n\nExecute hooks based on environment or context:\n\n```bash\n#!/bin/bash\n# Only run in CI environment\nif [ -z \"$CI\" ]; then\n echo '{\"continue\": true}' # Skip in non-CI\n exit 0\nfi\n\n# Run validation logic in CI\ninput=$(cat)\n# ... validation code ...\n```\n\n**Use cases:**\n- Different behavior in CI vs local development\n- Project-specific validation\n- User-specific rules\n\n**Example: Skip certain checks for trusted users:**\n```bash\n#!/bin/bash\n# Skip detailed checks for admin users\nif [ \"$USER\" = \"admin\" ]; then\n exit 0\nfi\n\n# Full validation for other users\ninput=$(cat)\n# ... validation code ...\n```\n\n## Hook Chaining via State\n\nShare state between hooks using temporary files:\n\n```bash\n# Hook 1: Analyze and save state\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Analyze command\nrisk_level=$(calculate_risk \"$command\")\necho \"$risk_level\" > /tmp/hook-state-$$\n\nexit 0\n```\n\n```bash\n# Hook 2: Use saved state\n#!/bin/bash\nrisk_level=$(cat /tmp/hook-state-$$ 2>/dev/null || echo \"unknown\")\n\nif [ \"$risk_level\" = \"high\" ]; then\n echo \"High risk operation detected\" >&2\n exit 2\nfi\n```\n\n**Important:** This only works for sequential hook events (e.g., PreToolUse then PostToolUse), not parallel hooks.\n\n## Dynamic Hook Configuration\n\nModify hook behavior based on project configuration:\n\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Read project-specific config\nif [ -f \".claude-hooks-config.json\" ]; then\n strict_mode=$(jq -r '.strict_mode' .claude-hooks-config.json)\n\n if [ \"$strict_mode\" = \"true\" ]; then\n # Apply strict validation\n # ...\n else\n # Apply lenient validation\n # ...\n fi\nfi\n```\n\n**Example .claude-hooks-config.json:**\n```json\n{\n \"strict_mode\": true,\n \"allowed_commands\": [\"ls\", \"pwd\", \"grep\"],\n \"forbidden_paths\": [\"/etc\", \"/sys\"]\n}\n```\n\n## Context-Aware Prompt Hooks\n\nUse transcript and session context for intelligent decisions:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review the full transcript at $TRANSCRIPT_PATH. Check: 1) Were tests run after code changes? 2) Did the build succeed? 3) Were all user questions answered? 4) Is there any unfinished work? Return 'approve' only if everything is complete.\"\n }\n ]\n }\n ]\n}\n```\n\nThe LLM can read the transcript file and make context-aware decisions.\n\n## Performance Optimization\n\n### Caching Validation Results\n\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncache_key=$(echo -n \"$file_path\" | md5sum | cut -d' ' -f1)\ncache_file=\"/tmp/hook-cache-$cache_key\"\n\n# Check cache\nif [ -f \"$cache_file\" ]; then\n cache_age=$(($(date +%s) - $(stat -f%m \"$cache_file\" 2>/dev/null || stat -c%Y \"$cache_file\")))\n if [ \"$cache_age\" -lt 300 ]; then # 5 minute cache\n cat \"$cache_file\"\n exit 0\n fi\nfi\n\n# Perform validation\nresult='{\"decision\": \"approve\"}'\n\n# Cache result\necho \"$result\" > \"$cache_file\"\necho \"$result\"\n```\n\n### Parallel Execution Optimization\n\nSince hooks run in parallel, design them to be independent:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash check-size.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"command\",\n \"command\": \"bash check-path.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check content safety\", // Independent\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nAll three hooks run simultaneously, reducing total latency.\n\n## Cross-Event Workflows\n\nCoordinate hooks across different events:\n\n**SessionStart - Set up tracking:**\n```bash\n#!/bin/bash\n# Initialize session tracking\necho \"0\" > /tmp/test-count-$$\necho \"0\" > /tmp/build-count-$$\n```\n\n**PostToolUse - Track events:**\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\nif [ \"$tool_name\" = \"Bash\" ]; then\n command=$(echo \"$input\" | jq -r '.tool_result')\n if [[ \"$command\" == *\"test\"* ]]; then\n count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n echo $((count + 1)) > /tmp/test-count-$$\n fi\nfi\n```\n\n**Stop - Verify based on tracking:**\n```bash\n#!/bin/bash\ntest_count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n\nif [ \"$test_count\" -eq 0 ]; then\n echo '{\"decision\": \"block\", \"reason\": \"No tests were run\"}' >&2\n exit 2\nfi\n```\n\n## Integration with External Systems\n\n### Slack Notifications\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ndecision=\"blocked\"\n\n# Send notification to Slack\ncurl -X POST \"$SLACK_WEBHOOK\" \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"text\\\": \\\"Hook ${decision} ${tool_name} operation\\\"}\" \\\n 2>/dev/null\n\necho '{\"decision\": \"deny\"}' >&2\nexit 2\n```\n\n### Database Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\n\n# Log to database\npsql \"$DATABASE_URL\" -c \"INSERT INTO hook_logs (event, data) VALUES ('PreToolUse', '$input')\" \\\n 2>/dev/null\n\nexit 0\n```\n\n### Metrics Collection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Send metrics to monitoring system\necho \"hook.pretooluse.${tool_name}:1|c\" | nc -u -w1 statsd.local 8125\n\nexit 0\n```\n\n## Security Patterns\n\n### Rate Limiting\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Track command frequency\nrate_file=\"/tmp/hook-rate-$$\"\ncurrent_minute=$(date +%Y%m%d%H%M)\n\nif [ -f \"$rate_file\" ]; then\n last_minute=$(head -1 \"$rate_file\")\n count=$(tail -1 \"$rate_file\")\n\n if [ \"$current_minute\" = \"$last_minute\" ]; then\n if [ \"$count\" -gt 10 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Rate limit exceeded\"}' >&2\n exit 2\n fi\n count=$((count + 1))\n else\n count=1\n fi\nelse\n count=1\nfi\n\necho \"$current_minute\" > \"$rate_file\"\necho \"$count\" >> \"$rate_file\"\n\nexit 0\n```\n\n### Audit Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ntimestamp=$(date -Iseconds)\n\n# Append to audit log\necho \"$timestamp | $USER | $tool_name | $input\" >> ~/.claude/audit.log\n\nexit 0\n```\n\n### Secret Detection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncontent=$(echo \"$input\" | jq -r '.tool_input.content')\n\n# Check for common secret patterns\nif echo \"$content\" | grep -qE \"(api[_-]?key|password|secret|token).{0,20}['\\\"]?[A-Za-z0-9]{20,}\"; then\n echo '{\"decision\": \"deny\", \"reason\": \"Potential secret detected in content\"}' >&2\n exit 2\nfi\n\nexit 0\n```\n\n## Testing Advanced Hooks\n\n### Unit Testing Hook Scripts\n\n```bash\n# test-hook.sh\n#!/bin/bash\n\n# Test 1: Approve safe command\nresult=$(echo '{\"tool_input\": {\"command\": \"ls\"}}' | bash validate-bash.sh)\nif [ $? -eq 0 ]; then\n echo \"✓ Test 1 passed\"\nelse\n echo \"✗ Test 1 failed\"\nfi\n\n# Test 2: Block dangerous command\nresult=$(echo '{\"tool_input\": {\"command\": \"rm -rf /\"}}' | bash validate-bash.sh)\nif [ $? -eq 2 ]; then\n echo \"✓ Test 2 passed\"\nelse\n echo \"✗ Test 2 failed\"\nfi\n```\n\n### Integration Testing\n\nCreate test scenarios that exercise the full hook workflow:\n\n```bash\n# integration-test.sh\n#!/bin/bash\n\n# Set up test environment\nexport CLAUDE_PROJECT_DIR=\"/tmp/test-project\"\nexport CLAUDE_PLUGIN_ROOT=\"$(pwd)\"\nmkdir -p \"$CLAUDE_PROJECT_DIR\"\n\n# Test SessionStart hook\necho '{}' | bash hooks/session-start.sh\nif [ -f \"/tmp/session-initialized\" ]; then\n echo \"✓ SessionStart hook works\"\nelse\n echo \"✗ SessionStart hook failed\"\nfi\n\n# Clean up\nrm -rf \"$CLAUDE_PROJECT_DIR\"\n```\n\n## Best Practices for Advanced Hooks\n\n1. **Keep hooks independent**: Don't rely on execution order\n2. **Use timeouts**: Set appropriate limits for each hook type\n3. **Handle errors gracefully**: Provide clear error messages\n4. **Document complexity**: Explain advanced patterns in README\n5. **Test thoroughly**: Cover edge cases and failure modes\n6. **Monitor performance**: Track hook execution time\n7. **Version configuration**: Use version control for hook configs\n8. **Provide escape hatches**: Allow users to bypass hooks when needed\n\n## Common Pitfalls\n\n### ❌ Assuming Hook Order\n\n```bash\n# BAD: Assumes hooks run in specific order\n# Hook 1 saves state, Hook 2 reads it\n# This can fail because hooks run in parallel!\n```\n\n### ❌ Long-Running Hooks\n\n```bash\n# BAD: Hook takes 2 minutes to run\nsleep 120\n# This will timeout and block the workflow\n```\n\n### ❌ Uncaught Exceptions\n\n```bash\n# BAD: Script crashes on unexpected input\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncat \"$file_path\" # Fails if file doesn't exist\n```\n\n### ✅ Proper Error Handling\n\n```bash\n# GOOD: Handles errors gracefully\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nif [ ! -f \"$file_path\" ]; then\n echo '{\"continue\": true, \"systemMessage\": \"File not found, skipping check\"}' >&2\n exit 0\nfi\n```\n\n## Conclusion\n\nAdvanced hook patterns enable sophisticated automation while maintaining reliability and performance. Use these techniques when basic hooks are insufficient, but always prioritize simplicity and maintainability.\n","isInternal":false,"tokens":2782,"sizeBytes":10148},{"name":"migration.md","path":"plugins/plugin-dev/skills/hook-development/references/migration.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/hook-development/references/migration.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Migrating from Basic to Advanced Hooks\n\nThis guide shows how to migrate from basic command hooks to advanced prompt-based hooks for better maintainability and flexibility.\n\n## Why Migrate?\n\nPrompt-based hooks offer several advantages:\n\n- **Natural language reasoning**: LLM understands context and intent\n- **Better edge case handling**: Adapts to unexpected scenarios\n- **No bash scripting required**: Simpler to write and maintain\n- **More flexible validation**: Can handle complex logic without coding\n\n## Migration Example: Bash Command Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-bash.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-bash.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Hard-coded validation logic\nif [[ \"$command\" == *\"rm -rf\"* ]]; then\n echo \"Dangerous command detected\" >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Only checks for exact \"rm -rf\" pattern\n- Doesn't catch variations like `rm -fr` or `rm -r -f`\n- Misses other dangerous commands (`dd`, `mkfs`, etc.)\n- No context awareness\n- Requires bash scripting knowledge\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. Analyze for: 1) Destructive operations (rm -rf, dd, mkfs, etc) 2) Privilege escalation (sudo) 3) Network operations without user consent. Return 'approve' or 'deny' with explanation.\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Catches all variations and patterns\n- Understands intent, not just literal strings\n- No script file needed\n- Easy to extend with new criteria\n- Context-aware decisions\n- Natural language explanation in denial\n\n## Migration Example: File Write Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-write.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-write.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Check for path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Check for system paths\nif [[ \"$file_path\" == \"/etc/\"* ]] || [[ \"$file_path\" == \"/sys/\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"System file\"}' >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Hard-coded path patterns\n- Doesn't understand symlinks\n- Missing edge cases (e.g., `/etc` vs `/etc/`)\n- No consideration of file content\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Content preview: $TOOL_INPUT.content (first 200 chars). Verify: 1) Not system directories (/etc, /sys, /usr) 2) Not credentials (.env, tokens, secrets) 3) No path traversal 4) Content doesn't expose secrets. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Context-aware (considers content too)\n- Handles symlinks and edge cases\n- Natural understanding of \"system directories\"\n- Can detect secrets in content\n- Easy to extend criteria\n\n## When to Keep Command Hooks\n\nCommand hooks still have their place:\n\n### 1. Deterministic Performance Checks\n\n```bash\n#!/bin/bash\n# Check file size quickly\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nsize=$(stat -f%z \"$file_path\" 2>/dev/null || stat -c%s \"$file_path\" 2>/dev/null)\n\nif [ \"$size\" -gt 10000000 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File too large\"}' >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Validation is purely mathematical or deterministic.\n\n### 2. External Tool Integration\n\n```bash\n#!/bin/bash\n# Run security scanner\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nscan_result=$(security-scanner \"$file_path\")\n\nif [ \"$?\" -ne 0 ]; then\n echo \"Security scan failed: $scan_result\" >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Integrating with external tools that provide yes/no answers.\n\n### 3. Very Fast Checks (< 50ms)\n\n```bash\n#!/bin/bash\n# Quick regex check\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\nif [[ \"$command\" =~ ^(ls|pwd|echo)$ ]]; then\n exit 0 # Safe commands\nfi\n```\n\n**Use command hooks when:** Performance is critical and logic is simple.\n\n## Hybrid Approach\n\nCombine both for multi-stage validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\nThe command hook does fast deterministic checks, while the prompt hook handles complex reasoning.\n\n## Migration Checklist\n\nWhen migrating hooks:\n\n- [ ] Identify the validation logic in the command hook\n- [ ] Convert hard-coded patterns to natural language criteria\n- [ ] Test with edge cases the old hook missed\n- [ ] Verify LLM understands the intent\n- [ ] Set appropriate timeout (usually 15-30s for prompt hooks)\n- [ ] Document the new hook in README\n- [ ] Remove or archive old script files\n\n## Migration Tips\n\n1. **Start with one hook**: Don't migrate everything at once\n2. **Test thoroughly**: Verify prompt hook catches what command hook caught\n3. **Look for improvements**: Use migration as opportunity to enhance validation\n4. **Keep scripts for reference**: Archive old scripts in case you need to reference the logic\n5. **Document reasoning**: Explain why prompt hook is better in README\n\n## Complete Migration Example\n\n### Original Plugin Structure\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json\n└── scripts/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### After Migration\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json # Now uses prompt hooks\n└── scripts/ # Archive or delete\n └── archive/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### Updated hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety: destructive ops, privilege escalation, network access\"\n }\n ]\n },\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety: system paths, credentials, path traversal, content secrets\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests were run if code was modified\"\n }\n ]\n }\n ]\n}\n```\n\n**Result:** Simpler, more maintainable, more powerful.\n\n## Common Migration Patterns\n\n### Pattern: String Contains → Natural Language\n\n**Before:**\n```bash\nif [[ \"$command\" == *\"sudo\"* ]]; then\n echo \"Privilege escalation\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check for privilege escalation (sudo, su, etc)\"\n```\n\n### Pattern: Regex → Intent\n\n**Before:**\n```bash\nif [[ \"$file\" =~ \\.(env|secret|key|token)$ ]]; then\n echo \"Credential file\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Verify not writing to credential files (.env, secrets, keys, tokens)\"\n```\n\n### Pattern: Multiple Conditions → Criteria List\n\n**Before:**\n```bash\nif [ condition1 ] || [ condition2 ] || [ condition3 ]; then\n echo \"Invalid\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check: 1) condition1 2) condition2 3) condition3. Deny if any fail.\"\n```\n\n## Conclusion\n\nMigrating to prompt-based hooks makes plugins more maintainable, flexible, and powerful. Reserve command hooks for deterministic checks and external tool integration.\n","isInternal":false,"tokens":2135,"sizeBytes":8299},{"name":"patterns.md","path":"plugins/plugin-dev/skills/hook-development/references/patterns.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/hook-development/references/patterns.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Common Hook Patterns\n\nThis reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases.\n\n## Pattern 1: Security Validation\n\nBlock dangerous file writes using prompt-based hooks:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Preventing writes to sensitive files or system directories.\n\n## Pattern 2: Test Enforcement\n\nEnsure tests run before stopping:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Enforcing quality standards and preventing incomplete work.\n\n## Pattern 3: Context Loading\n\nLoad project-specific context at session start:\n\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (load-context.sh):**\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Detect project type\nif [ -f \"package.json\" ]; then\n echo \"📦 Node.js project detected\"\n echo \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\nelif [ -f \"Cargo.toml\" ]; then\n echo \"🦀 Rust project detected\"\n echo \"export PROJECT_TYPE=rust\" >> \"$CLAUDE_ENV_FILE\"\nfi\n```\n\n**Use for:** Automatically detecting and configuring project-specific settings.\n\n## Pattern 4: Notification Logging\n\nLog all notifications for audit or analysis:\n\n```json\n{\n \"Notification\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Tracking user notifications or integration with external logging systems.\n\n## Pattern 5: MCP Tool Monitoring\n\nMonitor and validate MCP tool usage:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"mcp__.*__delete.*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Protecting against destructive MCP operations.\n\n## Pattern 6: Build Verification\n\nEnsure project builds after code changes:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Catching build errors before committing or stopping work.\n\n## Pattern 7: Permission Confirmation\n\nAsk user before dangerous operations:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** User confirmation on potentially destructive commands.\n\n## Pattern 8: Code Quality Checks\n\nRun linters or formatters on file edits:\n\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (check-quality.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run linter if applicable\nif [[ \"$file_path\" == *.js ]] || [[ \"$file_path\" == *.ts ]]; then\n npx eslint \"$file_path\" 2>&1 || true\nfi\n```\n\n**Use for:** Automatic code quality enforcement.\n\n## Pattern Combinations\n\nCombine multiple patterns for comprehensive protection:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n },\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests run and build succeeded\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\nThis provides multi-layered protection and automation.\n\n## Pattern 9: Temporarily Active Hooks\n\nCreate hooks that only run when explicitly enabled via flag files:\n\n```bash\n#!/bin/bash\n# Hook only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-security-scan\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Quick exit when disabled\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run security scan\nsecurity-scanner \"$file_path\"\n```\n\n**Activation:**\n```bash\n# Enable the hook\ntouch .enable-security-scan\n\n# Disable the hook\nrm .enable-security-scan\n```\n\n**Use for:**\n- Temporary debugging hooks\n- Feature flags for development\n- Project-specific validation that's opt-in\n- Performance-intensive checks only when needed\n\n**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes.\n\n## Pattern 10: Configuration-Driven Hooks\n\nUse JSON configuration to control hook behavior:\n\n```bash\n#!/bin/bash\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json\"\n\n# Read configuration\nif [ -f \"$CONFIG_FILE\" ]; then\n strict_mode=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n max_file_size=$(jq -r '.maxFileSize // 1000000' \"$CONFIG_FILE\")\nelse\n # Defaults\n strict_mode=false\n max_file_size=1000000\nfi\n\n# Skip if not in strict mode\nif [ \"$strict_mode\" != \"true\" ]; then\n exit 0\nfi\n\n# Apply configured limits\ninput=$(cat)\nfile_size=$(echo \"$input\" | jq -r '.tool_input.content | length')\n\nif [ \"$file_size\" -gt \"$max_file_size\" ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File exceeds configured size limit\"}' >&2\n exit 2\nfi\n```\n\n**Configuration file (.claude/my-plugin.local.json):**\n```json\n{\n \"strictMode\": true,\n \"maxFileSize\": 500000,\n \"allowedPaths\": [\"/tmp\", \"/home/user/projects\"]\n}\n```\n\n**Use for:**\n- User-configurable hook behavior\n- Per-project settings\n- Team-specific rules\n- Dynamic validation criteria\n","isInternal":false,"tokens":1805,"sizeBytes":7144},{"name":"SKILL.md","path":"plugins/plugin-dev/skills/hook-development/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/hook-development/SKILL.md","title":"Hook Development","category":"anthropic-skill","format":"markdown","content":"---\nname: Hook Development\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse/PostToolUse/Stop hook\", \"validate tool use\", \"implement prompt-based hooks\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"set up event-driven automation\", \"block dangerous commands\", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.\nversion: 0.1.0\n---\n\n# Hook Development for Claude Code Plugins\n\n## Overview\n\nHooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.\n\n**Key capabilities:**\n- Validate tool calls before execution (PreToolUse)\n- React to tool results (PostToolUse)\n- Enforce completion standards (Stop, SubagentStop)\n- Load project context (SessionStart)\n- Automate workflows across the development lifecycle\n\n## Hook Types\n\n### Prompt-Based Hooks (Recommended)\n\nUse LLM-driven decision making for context-aware validation:\n\n```json\n{\n \"type\": \"prompt\",\n \"prompt\": \"Evaluate if this tool use is appropriate: $TOOL_INPUT\",\n \"timeout\": 30\n}\n```\n\n**Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse\n\n**Benefits:**\n- Context-aware decisions based on natural language reasoning\n- Flexible evaluation logic without bash scripting\n- Better edge case handling\n- Easier to maintain and extend\n\n### Command Hooks\n\nExecute bash commands for deterministic checks:\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 60\n}\n```\n\n**Use for:**\n- Fast deterministic validations\n- File system operations\n- External tool integrations\n- Performance-critical checks\n\n## Hook Configuration Formats\n\n### Plugin hooks.json Format\n\n**For plugin hooks** in `hooks/hooks.json`, use wrapper format:\n\n```json\n{\n \"description\": \"Brief explanation of hooks (optional)\",\n \"hooks\": {\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n }\n}\n```\n\n**Key points:**\n- `description` field is optional\n- `hooks` field is required wrapper containing actual hook events\n- This is the **plugin-specific format**\n\n**Example:**\n```json\n{\n \"description\": \"Validation hooks for code quality\",\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh\"\n }\n ]\n }\n ]\n }\n}\n```\n\n### Settings Format (Direct)\n\n**For user settings** in `.claude/settings.json`, use direct format:\n\n```json\n{\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**Key points:**\n- No wrapper - events directly at top level\n- No description field\n- This is the **settings format**\n\n**Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{\"hooks\": {...}}`.\n\n## Hook Events\n\n### PreToolUse\n\nExecute before any tool runs. Use to approve, deny, or modify tool calls.\n\n**Example (prompt-based):**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output for PreToolUse:**\n```json\n{\n \"hookSpecificOutput\": {\n \"permissionDecision\": \"allow|deny|ask\",\n \"updatedInput\": {\"field\": \"modified_value\"}\n },\n \"systemMessage\": \"Explanation for Claude\"\n}\n```\n\n### PostToolUse\n\nExecute after tool completes. Use to react to results, provide feedback, or log.\n\n**Example:**\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output behavior:**\n- Exit 0: stdout shown in transcript\n- Exit 2: stderr fed back to Claude\n- systemMessage included in context\n\n### Stop\n\nExecute when main agent considers stopping. Use to validate completeness.\n\n**Example:**\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue.\"\n }\n ]\n }\n ]\n}\n```\n\n**Decision output:**\n```json\n{\n \"decision\": \"approve|block\",\n \"reason\": \"Explanation\",\n \"systemMessage\": \"Additional context\"\n}\n```\n\n### SubagentStop\n\nExecute when subagent considers stopping. Use to ensure subagent completed its task.\n\nSimilar to Stop hook, but for subagents.\n\n### UserPromptSubmit\n\nExecute when user submits a prompt. Use to add context, validate, or block prompts.\n\n**Example:**\n```json\n{\n \"UserPromptSubmit\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings.\"\n }\n ]\n }\n ]\n}\n```\n\n### SessionStart\n\nExecute when Claude Code session begins. Use to load context and set environment.\n\n**Example:**\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`:\n```bash\necho \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\n```\n\nSee `examples/load-context.sh` for complete example.\n\n### SessionEnd\n\nExecute when session ends. Use for cleanup, logging, and state preservation.\n\n### PreCompact\n\nExecute before context compaction. Use to add critical information to preserve.\n\n### Notification\n\nExecute when Claude sends notifications. Use to react to user notifications.\n\n## Hook Output Format\n\n### Standard Output (All Hooks)\n\n```json\n{\n \"continue\": true,\n \"suppressOutput\": false,\n \"systemMessage\": \"Message for Claude\"\n}\n```\n\n- `continue`: If false, halt processing (default true)\n- `suppressOutput`: Hide output from transcript (default false)\n- `systemMessage`: Message shown to Claude\n\n### Exit Codes\n\n- `0` - Success (stdout shown in transcript)\n- `2` - Blocking error (stderr fed back to Claude)\n- Other - Non-blocking error\n\n## Hook Input Format\n\nAll hooks receive JSON via stdin with common fields:\n\n```json\n{\n \"session_id\": \"abc123\",\n \"transcript_path\": \"/path/to/transcript.txt\",\n \"cwd\": \"/current/working/dir\",\n \"permission_mode\": \"ask|allow\",\n \"hook_event_name\": \"PreToolUse\"\n}\n```\n\n**Event-specific fields:**\n\n- **PreToolUse/PostToolUse:** `tool_name`, `tool_input`, `tool_result`\n- **UserPromptSubmit:** `user_prompt`\n- **Stop/SubagentStop:** `reason`\n\nAccess fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc.\n\n## Environment Variables\n\nAvailable in all command hooks:\n\n- `$CLAUDE_PROJECT_DIR` - Project root path\n- `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths)\n- `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here\n- `$CLAUDE_CODE_REMOTE` - Set if running in remote context\n\n**Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:**\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\"\n}\n```\n\n## Plugin Hook Configuration\n\nIn plugins, define hooks in `hooks/hooks.json`:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\",\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nPlugin hooks merge with user's hooks and run in parallel.\n\n## Matchers\n\n### Tool Name Matching\n\n**Exact match:**\n```json\n\"matcher\": \"Write\"\n```\n\n**Multiple tools:**\n```json\n\"matcher\": \"Read|Write|Edit\"\n```\n\n**Wildcard (all tools):**\n```json\n\"matcher\": \"*\"\n```\n\n**Regex patterns:**\n```json\n\"matcher\": \"mcp__.*__delete.*\" // All MCP delete tools\n```\n\n**Note:** Matchers are case-sensitive.\n\n### Common Patterns\n\n```json\n// All MCP tools\n\"matcher\": \"mcp__.*\"\n\n// Specific plugin's MCP tools\n\"matcher\": \"mcp__plugin_asana_.*\"\n\n// All file operations\n\"matcher\": \"Read|Write|Edit\"\n\n// Bash commands only\n\"matcher\": \"Bash\"\n```\n\n## Security Best Practices\n\n### Input Validation\n\nAlways validate inputs in command hooks:\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Validate tool name format\nif [[ ! \"$tool_name\" =~ ^[a-zA-Z0-9_]+$ ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Invalid tool name\"}' >&2\n exit 2\nfi\n```\n\n### Path Safety\n\nCheck for path traversal and sensitive files:\n\n```bash\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Deny path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Deny sensitive files\nif [[ \"$file_path\" == *\".env\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Sensitive file\"}' >&2\n exit 2\nfi\n```\n\nSee `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples.\n\n### Quote All Variables\n\n```bash\n# GOOD: Quoted\necho \"$file_path\"\ncd \"$CLAUDE_PROJECT_DIR\"\n\n# BAD: Unquoted (injection risk)\necho $file_path\ncd $CLAUDE_PROJECT_DIR\n```\n\n### Set Appropriate Timeouts\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash script.sh\",\n \"timeout\": 10\n}\n```\n\n**Defaults:** Command hooks (60s), Prompt hooks (30s)\n\n## Performance Considerations\n\n### Parallel Execution\n\nAll matching hooks run **in parallel**:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\"type\": \"command\", \"command\": \"check1.sh\"}, // Parallel\n {\"type\": \"command\", \"command\": \"check2.sh\"}, // Parallel\n {\"type\": \"prompt\", \"prompt\": \"Validate...\"} // Parallel\n ]\n }\n ]\n}\n```\n\n**Design implications:**\n- Hooks don't see each other's output\n- Non-deterministic ordering\n- Design for independence\n\n### Optimization\n\n1. Use command hooks for quick deterministic checks\n2. Use prompt hooks for complex reasoning\n3. Cache validation results in temp files\n4. Minimize I/O in hot paths\n\n## Temporarily Active Hooks\n\nCreate hooks that activate conditionally by checking for a flag file or configuration:\n\n**Pattern: Flag file activation**\n```bash\n#!/bin/bash\n# Only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-strict-validation\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Flag not present, skip validation\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\n# ... validation logic ...\n```\n\n**Pattern: Configuration-based activation**\n```bash\n#!/bin/bash\n# Check configuration for activation\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/plugin-config.json\"\n\nif [ -f \"$CONFIG_FILE\" ]; then\n enabled=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n if [ \"$enabled\" != \"true\" ]; then\n exit 0 # Not enabled, skip\n fi\nfi\n\n# Enabled, run hook logic\ninput=$(cat)\n# ... hook logic ...\n```\n\n**Use cases:**\n- Enable strict validation only when needed\n- Temporary debugging hooks\n- Project-specific hook behavior\n- Feature flags for hooks\n\n**Best practice:** Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.\n\n## Hook Lifecycle and Limitations\n\n### Hooks Load at Session Start\n\n**Important:** Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.\n\n**Cannot hot-swap hooks:**\n- Editing `hooks/hooks.json` won't affect current session\n- Adding new hook scripts won't be recognized\n- Changing hook commands/prompts won't update\n- Must restart Claude Code: exit and run `claude` again\n\n**To test hook changes:**\n1. Edit hook configuration or scripts\n2. Exit Claude Code session\n3. Restart: `claude` or `cc`\n4. New hook configuration loads\n5. Test hooks with `claude --debug`\n\n### Hook Validation at Startup\n\nHooks are validated when Claude Code starts:\n- Invalid JSON in hooks.json causes loading failure\n- Missing scripts cause warnings\n- Syntax errors reported in debug mode\n\nUse `/hooks` command to review loaded hooks in current session.\n\n## Debugging Hooks\n\n### Enable Debug Mode\n\n```bash\nclaude --debug\n```\n\nLook for hook registration, execution logs, input/output JSON, and timing information.\n\n### Test Hook Scripts\n\nTest command hooks directly:\n\n```bash\necho '{\"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"/test\"}}' | \\\n bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\n\necho \"Exit code: $?\"\n```\n\n### Validate JSON Output\n\nEnsure hooks output valid JSON:\n\n```bash\noutput=$(./your-hook.sh < test-input.json)\necho \"$output\" | jq .\n```\n\n## Quick Reference\n\n### Hook Events Summary\n\n| Event | When | Use For |\n|-------|------|---------|\n| PreToolUse | Before tool | Validation, modification |\n| PostToolUse | After tool | Feedback, logging |\n| UserPromptSubmit | User input | Context, validation |\n| Stop | Agent stopping | Completeness check |\n| SubagentStop | Subagent done | Task validation |\n| SessionStart | Session begins | Context loading |\n| SessionEnd | Session ends | Cleanup, logging |\n| PreCompact | Before compact | Preserve context |\n| Notification | User notified | Logging, reactions |\n\n### Best Practices\n\n**DO:**\n- ✅ Use prompt-based hooks for complex logic\n- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability\n- ✅ Validate all inputs in command hooks\n- ✅ Quote all bash variables\n- ✅ Set appropriate timeouts\n- ✅ Return structured JSON output\n- ✅ Test hooks thoroughly\n\n**DON'T:**\n- ❌ Use hardcoded paths\n- ❌ Trust user input without validation\n- ❌ Create long-running hooks\n- ❌ Rely on hook execution order\n- ❌ Modify global state unpredictably\n- ❌ Log sensitive information\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed patterns and advanced techniques, consult:\n\n- **`references/patterns.md`** - Common hook patterns (8+ proven patterns)\n- **`references/migration.md`** - Migrating from basic to advanced hooks\n- **`references/advanced.md`** - Advanced use cases and techniques\n\n### Example Hook Scripts\n\nWorking examples in `examples/`:\n\n- **`validate-write.sh`** - File write validation example\n- **`validate-bash.sh`** - Bash command validation example\n- **`load-context.sh`** - SessionStart context loading example\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-hook-schema.sh`** - Validate hooks.json structure and syntax\n- **`test-hook.sh`** - Test hooks with sample input before deployment\n- **`hook-linter.sh`** - Check hook scripts for common issues and best practices\n\n### External Resources\n\n- **Official Docs**: https://docs.claude.com/en/docs/claude-code/hooks\n- **Examples**: See security-guidance plugin in marketplace\n- **Testing**: Use `claude --debug` for detailed logs\n- **Validation**: Use `jq` to validate hook JSON output\n\n## Implementation Workflow\n\nTo implement hooks in a plugin:\n\n1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.)\n2. Decide between prompt-based (flexible) or command (deterministic) hooks\n3. Write hook configuration in `hooks/hooks.json`\n4. For command hooks, create hook scripts\n5. Use ${CLAUDE_PLUGIN_ROOT} for all file references\n6. Validate configuration with `scripts/validate-hook-schema.sh hooks/hooks.json`\n7. Test hooks with `scripts/test-hook.sh` before deployment\n8. Test in Claude Code with `claude --debug`\n9. Document hooks in plugin README\n\nFocus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.\n","frontmatter":{"name":"Hook Development","description":"This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse/PostToolUse/Stop hook\", \"validate tool use\", \"implement prompt-based hooks\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"set up event-driven automation\", \"block dangerous commands\", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.","version":"0.1.0"},"isInternal":false,"tokens":3997,"sizeBytes":16246},{"name":"http-server.json","path":"plugins/plugin-dev/skills/mcp-integration/examples/http-server.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/mcp-integration/examples/http-server.json","title":"Examples Skill","category":"anthropic-skill","format":"json","content":"{\n \"_comment\": \"Example HTTP MCP server configuration for REST APIs\",\n \"rest-api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"Content-Type\": \"application/json\",\n \"X-API-Version\": \"2024-01-01\"\n }\n },\n \"internal-service\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"X-Service-Name\": \"claude-plugin\"\n }\n }\n}\n","frontmatter":{"_comment":"Example HTTP MCP server configuration for REST APIs","rest-api":{"type":"http","url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer ${API_TOKEN}","Content-Type":"application/json","X-API-Version":"2024-01-01"}},"internal-service":{"type":"http","url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer ${API_TOKEN}","X-Service-Name":"claude-plugin"}}},"isInternal":false,"tokens":142,"sizeBytes":502},{"name":"sse-server.json","path":"plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json","title":"Examples Skill","category":"anthropic-skill","format":"json","content":"{\n \"_comment\": \"Example SSE MCP server configuration for hosted cloud services\",\n \"asana\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.asana.com/sse\"\n },\n \"github\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.github.com/sse\"\n },\n \"custom-service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-API-Version\": \"v1\",\n \"X-Client-ID\": \"${CLIENT_ID}\"\n }\n }\n}\n","frontmatter":{"_comment":"Example SSE MCP server configuration for hosted cloud services","asana":{"type":"sse","url":"https://mcp.asana.com/sse"},"github":{"type":"sse","url":"https://mcp.github.com/sse"},"custom-service":{"type":"sse","url":"https://mcp.example.com/sse","headers":{"X-API-Version":"v1","X-Client-ID":"${CLIENT_ID}"}}},"isInternal":false,"tokens":132,"sizeBytes":413},{"name":"stdio-server.json","path":"plugins/plugin-dev/skills/mcp-integration/examples/stdio-server.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/mcp-integration/examples/stdio-server.json","title":"Examples Skill","category":"anthropic-skill","format":"json","content":"{\n \"_comment\": \"Example stdio MCP server configuration for local file system access\",\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"${CLAUDE_PROJECT_DIR}\"],\n \"env\": {\n \"LOG_LEVEL\": \"info\"\n }\n },\n \"database\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server.js\",\n \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config/db.json\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_POOL_SIZE\": \"10\"\n }\n },\n \"custom-tools\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\", \"--port\", \"8080\"],\n \"env\": {\n \"API_KEY\": \"${CUSTOM_API_KEY}\",\n \"DEBUG\": \"false\"\n }\n }\n}\n","frontmatter":{"_comment":"Example stdio MCP server configuration for local file system access","filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","${CLAUDE_PROJECT_DIR}"],"env":{"LOG_LEVEL":"info"}},"database":{"command":"${CLAUDE_PLUGIN_ROOT}/servers/db-server.js","args":["--config","${CLAUDE_PLUGIN_ROOT}/config/db.json"],"env":{"DATABASE_URL":"${DATABASE_URL}","DB_POOL_SIZE":"10"}},"custom-tools":{"command":"python","args":["-m","my_mcp_server","--port","8080"],"env":{"API_KEY":"${CUSTOM_API_KEY}","DEBUG":"false"}}},"isInternal":false,"tokens":200,"sizeBytes":686},{"name":"authentication.md","path":"plugins/plugin-dev/skills/mcp-integration/references/authentication.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/mcp-integration/references/authentication.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# MCP Authentication Patterns\n\nComplete guide to authentication methods for MCP servers in Claude Code plugins.\n\n## Overview\n\nMCP servers support multiple authentication methods depending on the server type and service requirements. Choose the method that best matches your use case and security requirements.\n\n## OAuth (Automatic)\n\n### How It Works\n\nClaude Code automatically handles the complete OAuth 2.0 flow for SSE and HTTP servers:\n\n1. User attempts to use MCP tool\n2. Claude Code detects authentication needed\n3. Opens browser for OAuth consent\n4. User authorizes in browser\n5. Tokens stored securely by Claude Code\n6. Automatic token refresh\n\n### Configuration\n\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\"\n }\n}\n```\n\nNo additional auth configuration needed! Claude Code handles everything.\n\n### Supported Services\n\n**Known OAuth-enabled MCP servers:**\n- Asana: `https://mcp.asana.com/sse`\n- GitHub (when available)\n- Google services (when available)\n- Custom OAuth servers\n\n### OAuth Scopes\n\nOAuth scopes are determined by the MCP server. Users see required scopes during the consent flow.\n\n**Document required scopes in your README:**\n```markdown\n## Authentication\n\nThis plugin requires the following Asana permissions:\n- Read tasks and projects\n- Create and update tasks\n- Access workspace data\n```\n\n### Token Storage\n\nTokens are stored securely by Claude Code:\n- Not accessible to plugins\n- Encrypted at rest\n- Automatic refresh\n- Cleared on sign-out\n\n### Troubleshooting OAuth\n\n**Authentication loop:**\n- Clear cached tokens (sign out and sign in)\n- Check OAuth redirect URLs\n- Verify server OAuth configuration\n\n**Scope issues:**\n- User may need to re-authorize for new scopes\n- Check server documentation for required scopes\n\n**Token expiration:**\n- Claude Code auto-refreshes\n- If refresh fails, prompts re-authentication\n\n## Token-Based Authentication\n\n### Bearer Tokens\n\nMost common for HTTP and WebSocket servers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\"\n }\n }\n}\n```\n\n**Environment variable:**\n```bash\nexport API_TOKEN=\"your-secret-token-here\"\n```\n\n### API Keys\n\nAlternative to Bearer tokens, often in custom headers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"X-API-Key\": \"${API_KEY}\",\n \"X-API-Secret\": \"${API_SECRET}\"\n }\n }\n}\n```\n\n### Custom Headers\n\nServices may use custom authentication headers.\n\n**Configuration:**\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-Auth-Token\": \"${AUTH_TOKEN}\",\n \"X-User-ID\": \"${USER_ID}\",\n \"X-Tenant-ID\": \"${TENANT_ID}\"\n }\n }\n}\n```\n\n### Documenting Token Requirements\n\nAlways document in your README:\n\n```markdown\n## Setup\n\n### Required Environment Variables\n\nSet these environment variables before using the plugin:\n\n\\`\\`\\`bash\nexport API_TOKEN=\"your-token-here\"\nexport API_SECRET=\"your-secret-here\"\n\\`\\`\\`\n\n### Obtaining Tokens\n\n1. Visit https://api.example.com/tokens\n2. Create a new API token\n3. Copy the token and secret\n4. Set environment variables as shown above\n\n### Token Permissions\n\nThe API token needs the following permissions:\n- Read access to resources\n- Write access for creating items\n- Delete access (optional, for cleanup operations)\n\\`\\`\\`\n```\n\n## Environment Variable Authentication (stdio)\n\n### Passing Credentials to Server\n\nFor stdio servers, pass credentials via environment variables:\n\n```json\n{\n \"database\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server_db\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_USER\": \"${DB_USER}\",\n \"DB_PASSWORD\": \"${DB_PASSWORD}\"\n }\n }\n}\n```\n\n### User Environment Variables\n\n```bash\n# User sets these in their shell\nexport DATABASE_URL=\"postgresql://localhost/mydb\"\nexport DB_USER=\"myuser\"\nexport DB_PASSWORD=\"mypassword\"\n```\n\n### Documentation Template\n\n```markdown\n## Database Configuration\n\nSet these environment variables:\n\n\\`\\`\\`bash\nexport DATABASE_URL=\"postgresql://host:port/database\"\nexport DB_USER=\"username\"\nexport DB_PASSWORD=\"password\"\n\\`\\`\\`\n\nOr create a `.env` file (add to `.gitignore`):\n\n\\`\\`\\`\nDATABASE_URL=postgresql://localhost:5432/mydb\nDB_USER=myuser\nDB_PASSWORD=mypassword\n\\`\\`\\`\n\nLoad with: \\`source .env\\` or \\`export $(cat .env | xargs)\\`\n\\`\\`\\`\n```\n\n## Dynamic Headers\n\n### Headers Helper Script\n\nFor tokens that change or expire, use a helper script:\n\n```json\n{\n \"api\": {\n \"type\": \"sse\",\n \"url\": \"https://api.example.com\",\n \"headersHelper\": \"${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh\"\n }\n}\n```\n\n**Script (get-headers.sh):**\n```bash\n#!/bin/bash\n# Generate dynamic authentication headers\n\n# Fetch fresh token\nTOKEN=$(get-fresh-token-from-somewhere)\n\n# Output JSON headers\ncat <___`. Use these tools in commands and agents just like built-in Claude Code tools.\n\n## Tool Naming Convention\n\n### Format\n\n```\nmcp__plugin____\n```\n\n### Examples\n\n**Asana plugin with asana server:**\n- `mcp__plugin_asana_asana__asana_create_task`\n- `mcp__plugin_asana_asana__asana_search_tasks`\n- `mcp__plugin_asana_asana__asana_get_project`\n\n**Custom plugin with database server:**\n- `mcp__plugin_myplug_database__query`\n- `mcp__plugin_myplug_database__execute`\n- `mcp__plugin_myplug_database__list_tables`\n\n### Discovering Tool Names\n\n**Use `/mcp` command:**\n```bash\n/mcp\n```\n\nThis shows:\n- All available MCP servers\n- Tools provided by each server\n- Tool schemas and descriptions\n- Full tool names for use in configuration\n\n## Using Tools in Commands\n\n### Pre-Allowing Tools\n\nSpecify MCP tools in command frontmatter:\n\n```markdown\n---\ndescription: Create a new Asana task\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\"\n]\n---\n\n# Create Task Command\n\nTo create a task:\n1. Gather task details from user\n2. Use mcp__plugin_asana_asana__asana_create_task with the details\n3. Confirm creation to user\n```\n\n### Multiple Tools\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\",\n \"mcp__plugin_asana_asana__asana_search_tasks\",\n \"mcp__plugin_asana_asana__asana_get_project\"\n]\n---\n```\n\n### Wildcard (Use Sparingly)\n\n```markdown\n---\nallowed-tools: [\"mcp__plugin_asana_asana__*\"]\n---\n```\n\n**Caution:** Only use wildcards if the command truly needs access to all tools from a server.\n\n### Tool Usage in Command Instructions\n\n**Example command:**\n```markdown\n---\ndescription: Search and create Asana tasks\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_search_tasks\",\n \"mcp__plugin_asana_asana__asana_create_task\"\n]\n---\n\n# Asana Task Management\n\n## Searching Tasks\n\nTo search for tasks:\n1. Use mcp__plugin_asana_asana__asana_search_tasks\n2. Provide search filters (assignee, project, etc.)\n3. Display results to user\n\n## Creating Tasks\n\nTo create a task:\n1. Gather task details:\n - Title (required)\n - Description\n - Project\n - Assignee\n - Due date\n2. Use mcp__plugin_asana_asana__asana_create_task\n3. Show confirmation with task link\n```\n\n## Using Tools in Agents\n\n### Agent Configuration\n\nAgents can use MCP tools autonomously without pre-allowing them:\n\n```markdown\n---\nname: asana-status-updater\ndescription: This agent should be used when the user asks to \"update Asana status\", \"generate project report\", or \"sync Asana tasks\"\nmodel: inherit\ncolor: blue\n---\n\n## Role\n\nAutonomous agent for generating Asana project status reports.\n\n## Process\n\n1. **Query tasks**: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks\n2. **Analyze progress**: Calculate completion rates and identify blockers\n3. **Generate report**: Create formatted status update\n4. **Update Asana**: Use mcp__plugin_asana_asana__asana_create_comment to post report\n\n## Available Tools\n\nThe agent has access to all Asana MCP tools without pre-approval.\n```\n\n### Agent Tool Access\n\nAgents have broader tool access than commands:\n- Can use any tool Claude determines is necessary\n- Don't need pre-allowed lists\n- Should document which tools they typically use\n\n## Tool Call Patterns\n\n### Pattern 1: Simple Tool Call\n\nSingle tool call with validation:\n\n```markdown\nSteps:\n1. Validate user provided required fields\n2. Call mcp__plugin_api_server__create_item with validated data\n3. Check for errors\n4. Display confirmation\n```\n\n### Pattern 2: Sequential Tools\n\nChain multiple tool calls:\n\n```markdown\nSteps:\n1. Search for existing items: mcp__plugin_api_server__search\n2. If not found, create new: mcp__plugin_api_server__create\n3. Add metadata: mcp__plugin_api_server__update_metadata\n4. Return final item ID\n```\n\n### Pattern 3: Batch Operations\n\nMultiple calls with same tool:\n\n```markdown\nSteps:\n1. Get list of items to process\n2. For each item:\n - Call mcp__plugin_api_server__update_item\n - Track success/failure\n3. Report results summary\n```\n\n### Pattern 4: Error Handling\n\nGraceful error handling:\n\n```markdown\nSteps:\n1. Try to call mcp__plugin_api_server__get_data\n2. If error (rate limit, network, etc.):\n - Wait and retry (max 3 attempts)\n - If still failing, inform user\n - Suggest checking configuration\n3. On success, process data\n```\n\n## Tool Parameters\n\n### Understanding Tool Schemas\n\nEach MCP tool has a schema defining its parameters. View with `/mcp`.\n\n**Example schema:**\n```json\n{\n \"name\": \"asana_create_task\",\n \"description\": \"Create a new Asana task\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Task title\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"Task description\"\n },\n \"workspace\": {\n \"type\": \"string\",\n \"description\": \"Workspace GID\"\n }\n },\n \"required\": [\"name\", \"workspace\"]\n }\n}\n```\n\n### Calling Tools with Parameters\n\nClaude automatically structures tool calls based on schema:\n\n```typescript\n// Claude generates this internally\n{\n toolName: \"mcp__plugin_asana_asana__asana_create_task\",\n input: {\n name: \"Review PR #123\",\n notes: \"Code review for new feature\",\n workspace: \"12345\",\n assignee: \"67890\",\n due_on: \"2025-01-15\"\n }\n}\n```\n\n### Parameter Validation\n\n**In commands, validate before calling:**\n\n```markdown\nSteps:\n1. Check required parameters:\n - Title is not empty\n - Workspace ID is provided\n - Due date is valid format (YYYY-MM-DD)\n2. If validation fails, ask user to provide missing data\n3. If validation passes, call MCP tool\n4. Handle tool errors gracefully\n```\n\n## Response Handling\n\n### Success Responses\n\n```markdown\nSteps:\n1. Call MCP tool\n2. On success:\n - Extract relevant data from response\n - Format for user display\n - Provide confirmation message\n - Include relevant links or IDs\n```\n\n### Error Responses\n\n```markdown\nSteps:\n1. Call MCP tool\n2. On error:\n - Check error type (auth, rate limit, validation, etc.)\n - Provide helpful error message\n - Suggest remediation steps\n - Don't expose internal error details to user\n```\n\n### Partial Success\n\n```markdown\nSteps:\n1. Batch operation with multiple MCP calls\n2. Track successes and failures separately\n3. Report summary:\n - \"Successfully processed 8 of 10 items\"\n - \"Failed items: [item1, item2] due to [reason]\"\n - Suggest retry or manual intervention\n```\n\n## Performance Optimization\n\n### Batching Requests\n\n**Good: Single query with filters**\n```markdown\nSteps:\n1. Call mcp__plugin_api_server__search with filters:\n - project_id: \"123\"\n - status: \"active\"\n - limit: 100\n2. Process all results\n```\n\n**Avoid: Many individual queries**\n```markdown\nSteps:\n1. For each item ID:\n - Call mcp__plugin_api_server__get_item\n - Process item\n```\n\n### Caching Results\n\n```markdown\nSteps:\n1. Call expensive MCP operation: mcp__plugin_api_server__analyze\n2. Store results in variable for reuse\n3. Use cached results for subsequent operations\n4. Only re-fetch if data changes\n```\n\n### Parallel Tool Calls\n\nWhen tools don't depend on each other, call in parallel:\n\n```markdown\nSteps:\n1. Make parallel calls (Claude handles this automatically):\n - mcp__plugin_api_server__get_project\n - mcp__plugin_api_server__get_users\n - mcp__plugin_api_server__get_tags\n2. Wait for all to complete\n3. Combine results\n```\n\n## Integration Best Practices\n\n### User Experience\n\n**Provide feedback:**\n```markdown\nSteps:\n1. Inform user: \"Searching Asana tasks...\"\n2. Call mcp__plugin_asana_asana__asana_search_tasks\n3. Show progress: \"Found 15 tasks, analyzing...\"\n4. Present results\n```\n\n**Handle long operations:**\n```markdown\nSteps:\n1. Warn user: \"This may take a minute...\"\n2. Break into smaller steps with updates\n3. Show incremental progress\n4. Final summary when complete\n```\n\n### Error Messages\n\n**Good error messages:**\n```\n❌ \"Could not create task. Please check:\n 1. You're logged into Asana\n 2. You have access to workspace 'Engineering'\n 3. The project 'Q1 Goals' exists\"\n```\n\n**Poor error messages:**\n```\n❌ \"Error: MCP tool returned 403\"\n```\n\n### Documentation\n\n**Document MCP tool usage in command:**\n```markdown\n## MCP Tools Used\n\nThis command uses the following Asana MCP tools:\n- **asana_search_tasks**: Search for tasks matching criteria\n- **asana_create_task**: Create new task with details\n- **asana_update_task**: Update existing task properties\n\nEnsure you're authenticated to Asana before running this command.\n```\n\n## Testing Tool Usage\n\n### Local Testing\n\n1. **Configure MCP server** in `.mcp.json`\n2. **Install plugin locally** in `.claude-plugin/`\n3. **Verify tools available** with `/mcp`\n4. **Test command** that uses tools\n5. **Check debug output**: `claude --debug`\n\n### Test Scenarios\n\n**Test successful calls:**\n```markdown\nSteps:\n1. Create test data in external service\n2. Run command that queries this data\n3. Verify correct results returned\n```\n\n**Test error cases:**\n```markdown\nSteps:\n1. Test with missing authentication\n2. Test with invalid parameters\n3. Test with non-existent resources\n4. Verify graceful error handling\n```\n\n**Test edge cases:**\n```markdown\nSteps:\n1. Test with empty results\n2. Test with maximum results\n3. Test with special characters\n4. Test with concurrent access\n```\n\n## Common Patterns\n\n### Pattern: CRUD Operations\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_api_server__create_item\",\n \"mcp__plugin_api_server__read_item\",\n \"mcp__plugin_api_server__update_item\",\n \"mcp__plugin_api_server__delete_item\"\n]\n---\n\n# Item Management\n\n## Create\nUse create_item with required fields...\n\n## Read\nUse read_item with item ID...\n\n## Update\nUse update_item with item ID and changes...\n\n## Delete\nUse delete_item with item ID (ask for confirmation first)...\n```\n\n### Pattern: Search and Process\n\n```markdown\nSteps:\n1. **Search**: mcp__plugin_api_server__search with filters\n2. **Filter**: Apply additional local filtering if needed\n3. **Transform**: Process each result\n4. **Present**: Format and display to user\n```\n\n### Pattern: Multi-Step Workflow\n\n```markdown\nSteps:\n1. **Setup**: Gather all required information\n2. **Validate**: Check data completeness\n3. **Execute**: Chain of MCP tool calls:\n - Create parent resource\n - Create child resources\n - Link resources together\n - Add metadata\n4. **Verify**: Confirm all steps succeeded\n5. **Report**: Provide summary to user\n```\n\n## Troubleshooting\n\n### Tools Not Available\n\n**Check:**\n- MCP server configured correctly\n- Server connected (check `/mcp`)\n- Tool names match exactly (case-sensitive)\n- Restart Claude Code after config changes\n\n### Tool Calls Failing\n\n**Check:**\n- Authentication is valid\n- Parameters match tool schema\n- Required parameters provided\n- Check `claude --debug` logs\n\n### Performance Issues\n\n**Check:**\n- Batching queries instead of individual calls\n- Caching results when appropriate\n- Not making unnecessary tool calls\n- Parallel calls when possible\n\n## Conclusion\n\nEffective MCP tool usage requires:\n1. **Understanding tool schemas** via `/mcp`\n2. **Pre-allowing tools** in commands appropriately\n3. **Handling errors gracefully**\n4. **Optimizing performance** with batching and caching\n5. **Providing good UX** with feedback and clear errors\n6. **Testing thoroughly** before deployment\n\nFollow these patterns for robust MCP tool integration in your plugin commands and agents.\n","isInternal":false,"tokens":2909,"sizeBytes":11674},{"name":"SKILL.md","path":"plugins/plugin-dev/skills/mcp-integration/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/mcp-integration/SKILL.md","title":"MCP Integration","category":"anthropic-skill","format":"markdown","content":"---\nname: MCP Integration\ndescription: This skill should be used when the user asks to \"add MCP server\", \"integrate MCP\", \"configure MCP in plugin\", \"use .mcp.json\", \"set up Model Context Protocol\", \"connect external service\", mentions \"${CLAUDE_PLUGIN_ROOT} with MCP\", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.\nversion: 0.1.0\n---\n\n# MCP Integration for Claude Code Plugins\n\n## Overview\n\nModel Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.\n\n**Key capabilities:**\n- Connect to external services (databases, APIs, file systems)\n- Provide 10+ related tools from a single service\n- Handle OAuth and complex authentication flows\n- Bundle MCP servers with plugins for automatic setup\n\n## MCP Server Configuration Methods\n\nPlugins can bundle MCP servers in two ways:\n\n### Method 1: Dedicated .mcp.json (Recommended)\n\nCreate `.mcp.json` at plugin root:\n\n```json\n{\n \"database-tools\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server\",\n \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config.json\"],\n \"env\": {\n \"DB_URL\": \"${DB_URL}\"\n }\n }\n}\n```\n\n**Benefits:**\n- Clear separation of concerns\n- Easier to maintain\n- Better for multiple servers\n\n### Method 2: Inline in plugin.json\n\nAdd `mcpServers` field to plugin.json:\n\n```json\n{\n \"name\": \"my-plugin\",\n \"version\": \"1.0.0\",\n \"mcpServers\": {\n \"plugin-api\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/api-server\",\n \"args\": [\"--port\", \"8080\"]\n }\n }\n}\n```\n\n**Benefits:**\n- Single configuration file\n- Good for simple single-server plugins\n\n## MCP Server Types\n\n### stdio (Local Process)\n\nExecute local MCP servers as child processes. Best for local tools and custom servers.\n\n**Configuration:**\n```json\n{\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/allowed/path\"],\n \"env\": {\n \"LOG_LEVEL\": \"debug\"\n }\n }\n}\n```\n\n**Use cases:**\n- File system access\n- Local database connections\n- Custom MCP servers\n- NPM-packaged MCP servers\n\n**Process management:**\n- Claude Code spawns and manages the process\n- Communicates via stdin/stdout\n- Terminates when Claude Code exits\n\n### SSE (Server-Sent Events)\n\nConnect to hosted MCP servers with OAuth support. Best for cloud services.\n\n**Configuration:**\n```json\n{\n \"asana\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.asana.com/sse\"\n }\n}\n```\n\n**Use cases:**\n- Official hosted MCP servers (Asana, GitHub, etc.)\n- Cloud services with MCP endpoints\n- OAuth-based authentication\n- No local installation needed\n\n**Authentication:**\n- OAuth flows handled automatically\n- User prompted on first use\n- Tokens managed by Claude Code\n\n### HTTP (REST API)\n\nConnect to RESTful MCP servers with token authentication.\n\n**Configuration:**\n```json\n{\n \"api-service\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"X-Custom-Header\": \"value\"\n }\n }\n}\n```\n\n**Use cases:**\n- REST API-based MCP servers\n- Token-based authentication\n- Custom API backends\n- Stateless interactions\n\n### WebSocket (Real-time)\n\nConnect to WebSocket MCP servers for real-time bidirectional communication.\n\n**Configuration:**\n```json\n{\n \"realtime-service\": {\n \"type\": \"ws\",\n \"url\": \"wss://mcp.example.com/ws\",\n \"headers\": {\n \"Authorization\": \"Bearer ${TOKEN}\"\n }\n }\n}\n```\n\n**Use cases:**\n- Real-time data streaming\n- Persistent connections\n- Push notifications from server\n- Low-latency requirements\n\n## Environment Variable Expansion\n\nAll MCP configurations support environment variable substitution:\n\n**${CLAUDE_PLUGIN_ROOT}** - Plugin directory (always use for portability):\n```json\n{\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/my-server\"\n}\n```\n\n**User environment variables** - From user's shell:\n```json\n{\n \"env\": {\n \"API_KEY\": \"${MY_API_KEY}\",\n \"DATABASE_URL\": \"${DB_URL}\"\n }\n}\n```\n\n**Best practice:** Document all required environment variables in plugin README.\n\n## MCP Tool Naming\n\nWhen MCP servers provide tools, they're automatically prefixed:\n\n**Format:** `mcp__plugin____`\n\n**Example:**\n- Plugin: `asana`\n- Server: `asana`\n- Tool: `create_task`\n- **Full name:** `mcp__plugin_asana_asana__asana_create_task`\n\n### Using MCP Tools in Commands\n\nPre-allow specific MCP tools in command frontmatter:\n\n```markdown\n---\nallowed-tools: [\n \"mcp__plugin_asana_asana__asana_create_task\",\n \"mcp__plugin_asana_asana__asana_search_tasks\"\n]\n---\n```\n\n**Wildcard (use sparingly):**\n```markdown\n---\nallowed-tools: [\"mcp__plugin_asana_asana__*\"]\n---\n```\n\n**Best practice:** Pre-allow specific tools, not wildcards, for security.\n\n## Lifecycle Management\n\n**Automatic startup:**\n- MCP servers start when plugin enables\n- Connection established before first tool use\n- Restart required for configuration changes\n\n**Lifecycle:**\n1. Plugin loads\n2. MCP configuration parsed\n3. Server process started (stdio) or connection established (SSE/HTTP/WS)\n4. Tools discovered and registered\n5. Tools available as `mcp__plugin_...__...`\n\n**Viewing servers:**\nUse `/mcp` command to see all servers including plugin-provided ones.\n\n## Authentication Patterns\n\n### OAuth (SSE/HTTP)\n\nOAuth handled automatically by Claude Code:\n\n```json\n{\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\"\n}\n```\n\nUser authenticates in browser on first use. No additional configuration needed.\n\n### Token-Based (Headers)\n\nStatic or environment variable tokens:\n\n```json\n{\n \"type\": \"http\",\n \"url\": \"https://api.example.com\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\"\n }\n}\n```\n\nDocument required environment variables in README.\n\n### Environment Variables (stdio)\n\nPass configuration to MCP server:\n\n```json\n{\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\"],\n \"env\": {\n \"DATABASE_URL\": \"${DB_URL}\",\n \"API_KEY\": \"${API_KEY}\",\n \"LOG_LEVEL\": \"info\"\n }\n}\n```\n\n## Integration Patterns\n\n### Pattern 1: Simple Tool Wrapper\n\nCommands use MCP tools with user interaction:\n\n```markdown\n# Command: create-item.md\n---\nallowed-tools: [\"mcp__plugin_name_server__create_item\"]\n---\n\nSteps:\n1. Gather item details from user\n2. Use mcp__plugin_name_server__create_item\n3. Confirm creation\n```\n\n**Use for:** Adding validation or preprocessing before MCP calls.\n\n### Pattern 2: Autonomous Agent\n\nAgents use MCP tools autonomously:\n\n```markdown\n# Agent: data-analyzer.md\n\nAnalysis Process:\n1. Query data via mcp__plugin_db_server__query\n2. Process and analyze results\n3. Generate insights report\n```\n\n**Use for:** Multi-step MCP workflows without user interaction.\n\n### Pattern 3: Multi-Server Plugin\n\nIntegrate multiple MCP servers:\n\n```json\n{\n \"github\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.github.com/sse\"\n },\n \"jira\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.jira.com/sse\"\n }\n}\n```\n\n**Use for:** Workflows spanning multiple services.\n\n## Security Best Practices\n\n### Use HTTPS/WSS\n\nAlways use secure connections:\n\n```json\n✅ \"url\": \"https://mcp.example.com/sse\"\n❌ \"url\": \"http://mcp.example.com/sse\"\n```\n\n### Token Management\n\n**DO:**\n- ✅ Use environment variables for tokens\n- ✅ Document required env vars in README\n- ✅ Let OAuth flow handle authentication\n\n**DON'T:**\n- ❌ Hardcode tokens in configuration\n- ❌ Commit tokens to git\n- ❌ Share tokens in documentation\n\n### Permission Scoping\n\nPre-allow only necessary MCP tools:\n\n```markdown\n✅ allowed-tools: [\n \"mcp__plugin_api_server__read_data\",\n \"mcp__plugin_api_server__create_item\"\n]\n\n❌ allowed-tools: [\"mcp__plugin_api_server__*\"]\n```\n\n## Error Handling\n\n### Connection Failures\n\nHandle MCP server unavailability:\n- Provide fallback behavior in commands\n- Inform user of connection issues\n- Check server URL and configuration\n\n### Tool Call Errors\n\nHandle failed MCP operations:\n- Validate inputs before calling MCP tools\n- Provide clear error messages\n- Check rate limiting and quotas\n\n### Configuration Errors\n\nValidate MCP configuration:\n- Test server connectivity during development\n- Validate JSON syntax\n- Check required environment variables\n\n## Performance Considerations\n\n### Lazy Loading\n\nMCP servers connect on-demand:\n- Not all servers connect at startup\n- First tool use triggers connection\n- Connection pooling managed automatically\n\n### Batching\n\nBatch similar requests when possible:\n\n```\n# Good: Single query with filters\ntasks = search_tasks(project=\"X\", assignee=\"me\", limit=50)\n\n# Avoid: Many individual queries\nfor id in task_ids:\n task = get_task(id)\n```\n\n## Testing MCP Integration\n\n### Local Testing\n\n1. Configure MCP server in `.mcp.json`\n2. Install plugin locally (`.claude-plugin/`)\n3. Run `/mcp` to verify server appears\n4. Test tool calls in commands\n5. Check `claude --debug` logs for connection issues\n\n### Validation Checklist\n\n- [ ] MCP configuration is valid JSON\n- [ ] Server URL is correct and accessible\n- [ ] Required environment variables documented\n- [ ] Tools appear in `/mcp` output\n- [ ] Authentication works (OAuth or tokens)\n- [ ] Tool calls succeed from commands\n- [ ] Error cases handled gracefully\n\n## Debugging\n\n### Enable Debug Logging\n\n```bash\nclaude --debug\n```\n\nLook for:\n- MCP server connection attempts\n- Tool discovery logs\n- Authentication flows\n- Tool call errors\n\n### Common Issues\n\n**Server not connecting:**\n- Check URL is correct\n- Verify server is running (stdio)\n- Check network connectivity\n- Review authentication configuration\n\n**Tools not available:**\n- Verify server connected successfully\n- Check tool names match exactly\n- Run `/mcp` to see available tools\n- Restart Claude Code after config changes\n\n**Authentication failing:**\n- Clear cached auth tokens\n- Re-authenticate\n- Check token scopes and permissions\n- Verify environment variables set\n\n## Quick Reference\n\n### MCP Server Types\n\n| Type | Transport | Best For | Auth |\n|------|-----------|----------|------|\n| stdio | Process | Local tools, custom servers | Env vars |\n| SSE | HTTP | Hosted services, cloud APIs | OAuth |\n| HTTP | REST | API backends, token auth | Tokens |\n| ws | WebSocket | Real-time, streaming | Tokens |\n\n### Configuration Checklist\n\n- [ ] Server type specified (stdio/SSE/HTTP/ws)\n- [ ] Type-specific fields complete (command or url)\n- [ ] Authentication configured\n- [ ] Environment variables documented\n- [ ] HTTPS/WSS used (not HTTP/WS)\n- [ ] ${CLAUDE_PLUGIN_ROOT} used for paths\n\n### Best Practices\n\n**DO:**\n- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths\n- ✅ Document required environment variables\n- ✅ Use secure connections (HTTPS/WSS)\n- ✅ Pre-allow specific MCP tools in commands\n- ✅ Test MCP integration before publishing\n- ✅ Handle connection and tool errors gracefully\n\n**DON'T:**\n- ❌ Hardcode absolute paths\n- ❌ Commit credentials to git\n- ❌ Use HTTP instead of HTTPS\n- ❌ Pre-allow all tools with wildcards\n- ❌ Skip error handling\n- ❌ Forget to document setup\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed information, consult:\n\n- **`references/server-types.md`** - Deep dive on each server type\n- **`references/authentication.md`** - Authentication patterns and OAuth\n- **`references/tool-usage.md`** - Using MCP tools in commands and agents\n\n### Example Configurations\n\nWorking examples in `examples/`:\n\n- **`stdio-server.json`** - Local stdio MCP server\n- **`sse-server.json`** - Hosted SSE server with OAuth\n- **`http-server.json`** - REST API with token auth\n\n### External Resources\n\n- **Official MCP Docs**: https://modelcontextprotocol.io/\n- **Claude Code MCP Docs**: https://docs.claude.com/en/docs/claude-code/mcp\n- **MCP SDK**: @modelcontextprotocol/sdk\n- **Testing**: Use `claude --debug` and `/mcp` command\n\n## Implementation Workflow\n\nTo add MCP integration to a plugin:\n\n1. Choose MCP server type (stdio, SSE, HTTP, ws)\n2. Create `.mcp.json` at plugin root with configuration\n3. Use ${CLAUDE_PLUGIN_ROOT} for all file references\n4. Document required environment variables in README\n5. Test locally with `/mcp` command\n6. Pre-allow MCP tools in relevant commands\n7. Handle authentication (OAuth or tokens)\n8. Test error cases (connection failures, auth errors)\n9. Document MCP integration in plugin README\n\nFocus on stdio for custom/local servers, SSE for hosted services with OAuth.\n","frontmatter":{"name":"MCP Integration","description":"This skill should be used when the user asks to \"add MCP server\", \"integrate MCP\", \"configure MCP in plugin\", \"use .mcp.json\", \"set up Model Context Protocol\", \"connect external service\", mentions \"${CLAUDE_PLUGIN_ROOT} with MCP\", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.","version":"0.1.0"},"isInternal":false,"tokens":3039,"sizeBytes":12519},{"name":"create-settings-command.md","path":"plugins/plugin-dev/skills/plugin-settings/examples/create-settings-command.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-settings/examples/create-settings-command.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"---\ndescription: \"Create plugin settings file with user preferences\"\nallowed-tools: [\"Write\", \"AskUserQuestion\"]\n---\n\n# Create Plugin Settings\n\nThis command helps users create a `.claude/my-plugin.local.md` settings file.\n\n## Steps\n\n### Step 1: Ask User for Preferences\n\nUse AskUserQuestion to gather configuration:\n\n```json\n{\n \"questions\": [\n {\n \"question\": \"Enable plugin for this project?\",\n \"header\": \"Enable Plugin\",\n \"multiSelect\": false,\n \"options\": [\n {\n \"label\": \"Yes\",\n \"description\": \"Plugin will be active\"\n },\n {\n \"label\": \"No\",\n \"description\": \"Plugin will be disabled\"\n }\n ]\n },\n {\n \"question\": \"Validation mode?\",\n \"header\": \"Mode\",\n \"multiSelect\": false,\n \"options\": [\n {\n \"label\": \"Strict\",\n \"description\": \"Maximum validation and security checks\"\n },\n {\n \"label\": \"Standard\",\n \"description\": \"Balanced validation (recommended)\"\n },\n {\n \"label\": \"Lenient\",\n \"description\": \"Minimal validation only\"\n }\n ]\n }\n ]\n}\n```\n\n### Step 2: Parse Answers\n\nExtract answers from AskUserQuestion result:\n\n- answers[\"0\"]: enabled (Yes/No)\n- answers[\"1\"]: mode (Strict/Standard/Lenient)\n\n### Step 3: Create Settings File\n\nUse Write tool to create `.claude/my-plugin.local.md`:\n\n```markdown\n---\nenabled: \nvalidation_mode: \nmax_file_size: 1000000\nnotify_on_errors: true\n---\n\n# Plugin Configuration\n\nYour plugin is configured with validation mode.\n\nTo modify settings, edit this file and restart Claude Code.\n```\n\n### Step 4: Inform User\n\nTell the user:\n- Settings file created at `.claude/my-plugin.local.md`\n- Current configuration summary\n- How to edit manually if needed\n- Reminder: Restart Claude Code for changes to take effect\n- Settings file is gitignored (won't be committed)\n\n## Implementation Notes\n\nAlways validate user input before writing:\n- Check mode is valid\n- Validate numeric fields are numbers\n- Ensure paths don't have traversal attempts\n- Sanitize any free-text fields\n","frontmatter":{"description":"Create plugin settings file with user preferences","allowed-tools":["Write","AskUserQuestion"],"allowedTools":["Write","AskUserQuestion"]},"allowedTools":["Write","AskUserQuestion"],"isInternal":false,"tokens":497,"sizeBytes":2177},{"name":"example-settings.md","path":"plugins/plugin-dev/skills/plugin-settings/examples/example-settings.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-settings/examples/example-settings.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# Example Plugin Settings File\n\n## Template: Basic Configuration\n\n**.claude/my-plugin.local.md:**\n\n```markdown\n---\nenabled: true\nmode: standard\n---\n\n# My Plugin Configuration\n\nPlugin is active in standard mode.\n```\n\n## Template: Advanced Configuration\n\n**.claude/my-plugin.local.md:**\n\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\nnotification_level: info\nretry_attempts: 3\ntimeout_seconds: 60\ncustom_path: \"/path/to/data\"\n---\n\n# My Plugin Advanced Configuration\n\nThis project uses custom plugin configuration with:\n- Standard validation mode\n- 1MB file size limit\n- JavaScript/TypeScript files allowed\n- Info-level logging\n- 3 retry attempts\n\n## Additional Notes\n\nContact @team-lead with questions about this configuration.\n```\n\n## Template: Agent State File\n\n**.claude/multi-agent-swarm.local.md:**\n\n```markdown\n---\nagent_name: database-implementation\ntask_number: 4.2\npr_number: 5678\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.5\", \"Task 4.1\"]\nadditional_instructions: \"Use PostgreSQL, not MySQL\"\n---\n\n# Task Assignment: Database Schema Implementation\n\nImplement the database schema for the new features module.\n\n## Requirements\n\n- Create migration files\n- Add indexes for performance\n- Write tests for constraints\n- Document schema in README\n\n## Success Criteria\n\n- Migrations run successfully\n- All tests pass\n- PR created with CI green\n- Schema documented\n\n## Coordination\n\nDepends on:\n- Task 3.5: API endpoint definitions\n- Task 4.1: Data model design\n\nReport status to coordinator session 'team-leader'.\n```\n\n## Template: Feature Flag Pattern\n\n**.claude/experimental-features.local.md:**\n\n```markdown\n---\nenabled: true\nfeatures:\n - ai_suggestions\n - auto_formatting\n - advanced_refactoring\nexperimental_mode: false\n---\n\n# Experimental Features Configuration\n\nCurrent enabled features:\n- AI-powered code suggestions\n- Automatic code formatting\n- Advanced refactoring tools\n\nExperimental mode is OFF (stable features only).\n```\n\n## Usage in Hooks\n\nThese templates can be read by hooks:\n\n```bash\n# Check if plugin is configured\nif [[ ! -f \".claude/my-plugin.local.md\" ]]; then\n exit 0 # Not configured, skip hook\nfi\n\n# Read settings\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \".claude/my-plugin.local.md\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Apply settings\nif [[ \"$ENABLED\" == \"true\" ]]; then\n # Hook is active\n # ...\nfi\n```\n\n## Gitignore\n\nAlways add to project `.gitignore`:\n\n```gitignore\n# Plugin settings (user-local, not committed)\n.claude/*.local.md\n.claude/*.local.json\n```\n\n## Editing Settings\n\nUsers can edit settings files manually:\n\n```bash\n# Edit settings\nvim .claude/my-plugin.local.md\n\n# Changes take effect after restart\nexit # Exit Claude Code\nclaude # Restart\n```\n\nChanges require Claude Code restart - hooks can't be hot-swapped.\n","isInternal":false,"tokens":732,"sizeBytes":2930},{"name":"parsing-techniques.md","path":"plugins/plugin-dev/skills/plugin-settings/references/parsing-techniques.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-settings/references/parsing-techniques.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Settings File Parsing Techniques\n\nComplete guide to parsing `.claude/plugin-name.local.md` files in bash scripts.\n\n## File Structure\n\nSettings files use markdown with YAML frontmatter:\n\n```markdown\n---\nfield1: value1\nfield2: \"value with spaces\"\nnumeric_field: 42\nboolean_field: true\nlist_field: [\"item1\", \"item2\", \"item3\"]\n---\n\n# Markdown Content\n\nThis body content can be extracted separately.\nIt's useful for prompts, documentation, or additional context.\n```\n\n## Parsing Frontmatter\n\n### Extract Frontmatter Block\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\n\n# Extract everything between --- markers (excluding the markers themselves)\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n```\n\n**How it works:**\n- `sed -n` - Suppress automatic printing\n- `/^---$/,/^---$/` - Range from first `---` to second `---`\n- `{ /^---$/d; p; }` - Delete the `---` lines, print everything else\n\n### Extract Individual Fields\n\n**String fields:**\n```bash\n# Simple value\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//')\n\n# Quoted value (removes surrounding quotes)\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Use in condition\nif [[ \"$ENABLED\" == \"true\" ]]; then\n # Enabled\nfi\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n\n# Validate it's a number\nif [[ \"$MAX\" =~ ^[0-9]+$ ]]; then\n # Use in numeric comparison\n if [[ $MAX -gt 100 ]]; then\n # Too large\n fi\nfi\n```\n\n**List fields (simple):**\n```bash\n# YAML: list: [\"item1\", \"item2\", \"item3\"]\nLIST=$(echo \"$FRONTMATTER\" | grep '^list:' | sed 's/list: *//')\n# Result: [\"item1\", \"item2\", \"item3\"]\n\n# For simple checks:\nif [[ \"$LIST\" == *\"item1\"* ]]; then\n # List contains item1\nfi\n```\n\n**List fields (proper parsing with jq):**\n```bash\n# For proper list handling, use yq or convert to JSON\n# This requires yq to be installed (brew install yq)\n\n# Extract list as JSON array\nLIST=$(echo \"$FRONTMATTER\" | yq -o json '.list' 2>/dev/null)\n\n# Iterate over items\necho \"$LIST\" | jq -r '.[]' | while read -r item; do\n echo \"Processing: $item\"\ndone\n```\n\n## Parsing Markdown Body\n\n### Extract Body Content\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\n\n# Extract everything after the closing ---\n# Counts --- markers: first is opening, second is closing, everything after is body\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n**How it works:**\n- `/^---$/` - Match `---` lines\n- `{i++; next}` - Increment counter and skip the `---` line\n- `i>=2` - Print all lines after second `---`\n\n**Handles edge case:** If `---` appears in the markdown body, it still works because we only count the first two `---` at the start.\n\n### Use Body as Prompt\n\n```bash\n# Extract body\nPROMPT=$(awk '/^---$/{i++; next} i>=2' \"$RALPH_STATE_FILE\")\n\n# Feed back to Claude\necho '{\"decision\": \"block\", \"reason\": \"'\"$PROMPT\"'\"}' | jq .\n```\n\n**Important:** Use `jq -n --arg` for safer JSON construction with user content:\n\n```bash\nPROMPT=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n\n# Safe JSON construction\njq -n --arg prompt \"$PROMPT\" '{\n \"decision\": \"block\",\n \"reason\": $prompt\n}'\n```\n\n## Common Parsing Patterns\n\n### Pattern: Field with Default\n\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Use default if empty\nif [[ -z \"$VALUE\" ]]; then\n VALUE=\"default_value\"\nfi\n```\n\n### Pattern: Optional Field\n\n```bash\nOPTIONAL=$(echo \"$FRONTMATTER\" | grep '^optional_field:' | sed 's/optional_field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Only use if present\nif [[ -n \"$OPTIONAL\" ]] && [[ \"$OPTIONAL\" != \"null\" ]]; then\n # Field is set, use it\n echo \"Optional field: $OPTIONAL\"\nfi\n```\n\n### Pattern: Multiple Fields at Once\n\n```bash\n# Parse all fields in one pass\nwhile IFS=': ' read -r key value; do\n # Remove quotes if present\n value=$(echo \"$value\" | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n case \"$key\" in\n enabled)\n ENABLED=\"$value\"\n ;;\n mode)\n MODE=\"$value\"\n ;;\n max_size)\n MAX_SIZE=\"$value\"\n ;;\n esac\ndone <<< \"$FRONTMATTER\"\n```\n\n## Updating Settings Files\n\n### Atomic Updates\n\nAlways use temp file + atomic move to prevent corruption:\n\n```bash\n#!/bin/bash\nFILE=\".claude/my-plugin.local.md\"\nNEW_VALUE=\"updated_value\"\n\n# Create temp file\nTEMP_FILE=\"${FILE}.tmp.$$\"\n\n# Update field using sed\nsed \"s/^field_name: .*/field_name: $NEW_VALUE/\" \"$FILE\" > \"$TEMP_FILE\"\n\n# Atomic replace\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### Update Single Field\n\n```bash\n# Increment iteration counter\nCURRENT=$(echo \"$FRONTMATTER\" | grep '^iteration:' | sed 's/iteration: *//')\nNEXT=$((CURRENT + 1))\n\n# Update file\nTEMP_FILE=\"${FILE}.tmp.$$\"\nsed \"s/^iteration: .*/iteration: $NEXT/\" \"$FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### Update Multiple Fields\n\n```bash\n# Update several fields at once\nTEMP_FILE=\"${FILE}.tmp.$$\"\n\nsed -e \"s/^iteration: .*/iteration: $NEXT_ITERATION/\" \\\n -e \"s/^pr_number: .*/pr_number: $PR_NUMBER/\" \\\n -e \"s/^status: .*/status: $NEW_STATUS/\" \\\n \"$FILE\" > \"$TEMP_FILE\"\n\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n## Validation Techniques\n\n### Validate File Exists and Is Readable\n\n```bash\nFILE=\".claude/my-plugin.local.md\"\n\nif [[ ! -f \"$FILE\" ]]; then\n echo \"Settings file not found\" >&2\n exit 1\nfi\n\nif [[ ! -r \"$FILE\" ]]; then\n echo \"Settings file not readable\" >&2\n exit 1\nfi\n```\n\n### Validate Frontmatter Structure\n\n```bash\n# Count --- markers (should be exactly 2 at start)\nMARKER_COUNT=$(grep -c '^---$' \"$FILE\" 2>/dev/null || echo \"0\")\n\nif [[ $MARKER_COUNT -lt 2 ]]; then\n echo \"Invalid settings file: missing frontmatter markers\" >&2\n exit 1\nfi\n```\n\n### Validate Field Values\n\n```bash\nMODE=$(echo \"$FRONTMATTER\" | grep '^mode:' | sed 's/mode: *//')\n\ncase \"$MODE\" in\n strict|standard|lenient)\n # Valid mode\n ;;\n *)\n echo \"Invalid mode: $MODE (must be strict, standard, or lenient)\" >&2\n exit 1\n ;;\nesac\n```\n\n### Validate Numeric Ranges\n\n```bash\nMAX_SIZE=$(echo \"$FRONTMATTER\" | grep '^max_size:' | sed 's/max_size: *//')\n\nif ! [[ \"$MAX_SIZE\" =~ ^[0-9]+$ ]]; then\n echo \"max_size must be a number\" >&2\n exit 1\nfi\n\nif [[ $MAX_SIZE -lt 1 ]] || [[ $MAX_SIZE -gt 10000000 ]]; then\n echo \"max_size out of range (1-10000000)\" >&2\n exit 1\nfi\n```\n\n## Edge Cases and Gotchas\n\n### Quotes in Values\n\nYAML allows both quoted and unquoted strings:\n\n```yaml\n# These are equivalent:\nfield1: value\nfield2: \"value\"\nfield3: 'value'\n```\n\n**Handle both:**\n```bash\n# Remove surrounding quotes if present\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/' | sed \"s/^'\\\\(.*\\\\)'$/\\\\1/\")\n```\n\n### --- in Markdown Body\n\nIf the markdown body contains `---`, the parsing still works because we only match the first two:\n\n```markdown\n---\nfield: value\n---\n\n# Body\n\nHere's a separator:\n---\n\nMore content after the separator.\n```\n\nThe `awk '/^---$/{i++; next} i>=2'` pattern handles this correctly.\n\n### Empty Values\n\nHandle missing or empty fields:\n\n```yaml\nfield1:\nfield2: \"\"\nfield3: null\n```\n\n**Parsing:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field1:' | sed 's/field1: *//')\n# VALUE will be empty string\n\n# Check for empty/null\nif [[ -z \"$VALUE\" ]] || [[ \"$VALUE\" == \"null\" ]]; then\n VALUE=\"default\"\nfi\n```\n\n### Special Characters\n\nValues with special characters need careful handling:\n\n```yaml\nmessage: \"Error: Something went wrong!\"\npath: \"/path/with spaces/file.txt\"\nregex: \"^[a-zA-Z0-9_]+$\"\n```\n\n**Safe parsing:**\n```bash\n# Always quote variables when using\nMESSAGE=$(echo \"$FRONTMATTER\" | grep '^message:' | sed 's/message: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\necho \"Message: $MESSAGE\" # Quoted!\n```\n\n## Performance Optimization\n\n### Cache Parsed Values\n\nIf reading settings multiple times:\n\n```bash\n# Parse once\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Extract multiple fields from cached frontmatter\nFIELD1=$(echo \"$FRONTMATTER\" | grep '^field1:' | sed 's/field1: *//')\nFIELD2=$(echo \"$FRONTMATTER\" | grep '^field2:' | sed 's/field2: *//')\nFIELD3=$(echo \"$FRONTMATTER\" | grep '^field3:' | sed 's/field3: *//')\n```\n\n**Don't:** Re-parse file for each field.\n\n### Lazy Loading\n\nOnly parse settings when needed:\n\n```bash\n#!/bin/bash\ninput=$(cat)\n\n# Quick checks first (no file I/O)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\nif [[ \"$tool_name\" != \"Write\" ]]; then\n exit 0 # Not a write operation, skip\nfi\n\n# Only now check settings file\nif [[ -f \".claude/my-plugin.local.md\" ]]; then\n # Parse settings\n # ...\nfi\n```\n\n## Debugging\n\n### Print Parsed Values\n\n```bash\n#!/bin/bash\nset -x # Enable debug tracing\n\nFILE=\".claude/my-plugin.local.md\"\n\nif [[ -f \"$FILE\" ]]; then\n echo \"Settings file found\" >&2\n\n FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n echo \"Frontmatter:\" >&2\n echo \"$FRONTMATTER\" >&2\n\n ENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n echo \"Enabled: $ENABLED\" >&2\nfi\n```\n\n### Validate Parsing\n\n```bash\n# Show what was parsed\necho \"Parsed values:\" >&2\necho \" enabled: $ENABLED\" >&2\necho \" mode: $MODE\" >&2\necho \" max_size: $MAX_SIZE\" >&2\n\n# Verify expected values\nif [[ \"$ENABLED\" != \"true\" ]] && [[ \"$ENABLED\" != \"false\" ]]; then\n echo \"⚠️ Unexpected enabled value: $ENABLED\" >&2\nfi\n```\n\n## Alternative: Using yq\n\nFor complex YAML, consider using `yq`:\n\n```bash\n# Install: brew install yq\n\n# Parse YAML properly\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Extract fields with yq\nENABLED=$(echo \"$FRONTMATTER\" | yq '.enabled')\nMODE=$(echo \"$FRONTMATTER\" | yq '.mode')\nLIST=$(echo \"$FRONTMATTER\" | yq -o json '.list_field')\n\n# Iterate list properly\necho \"$LIST\" | jq -r '.[]' | while read -r item; do\n echo \"Item: $item\"\ndone\n```\n\n**Pros:**\n- Proper YAML parsing\n- Handles complex structures\n- Better list/object support\n\n**Cons:**\n- Requires yq installation\n- Additional dependency\n- May not be available on all systems\n\n**Recommendation:** Use sed/grep for simple fields, yq for complex structures.\n\n## Complete Example\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Configuration\nSETTINGS_FILE=\".claude/my-plugin.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$SETTINGS_FILE\" ]]; then\n # Use defaults\n ENABLED=true\n MODE=standard\n MAX_SIZE=1000000\nelse\n # Parse frontmatter\n FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$SETTINGS_FILE\")\n\n # Extract fields with defaults\n ENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n ENABLED=${ENABLED:-true}\n\n MODE=$(echo \"$FRONTMATTER\" | grep '^mode:' | sed 's/mode: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n MODE=${MODE:-standard}\n\n MAX_SIZE=$(echo \"$FRONTMATTER\" | grep '^max_size:' | sed 's/max_size: *//')\n MAX_SIZE=${MAX_SIZE:-1000000}\n\n # Validate values\n if [[ \"$ENABLED\" != \"true\" ]] && [[ \"$ENABLED\" != \"false\" ]]; then\n echo \"⚠️ Invalid enabled value, using default\" >&2\n ENABLED=true\n fi\n\n if ! [[ \"$MAX_SIZE\" =~ ^[0-9]+$ ]]; then\n echo \"⚠️ Invalid max_size, using default\" >&2\n MAX_SIZE=1000000\n fi\nfi\n\n# Quick exit if disabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0\nfi\n\n# Use configuration\necho \"Configuration loaded: mode=$MODE, max_size=$MAX_SIZE\" >&2\n\n# Apply logic based on settings\ncase \"$MODE\" in\n strict)\n # Strict validation\n ;;\n standard)\n # Standard validation\n ;;\n lenient)\n # Lenient validation\n ;;\nesac\n```\n\nThis provides robust settings handling with defaults, validation, and error recovery.\n","isInternal":false,"tokens":3529,"sizeBytes":11513},{"name":"real-world-examples.md","path":"plugins/plugin-dev/skills/plugin-settings/references/real-world-examples.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-settings/references/real-world-examples.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Real-World Plugin Settings Examples\n\nDetailed analysis of how production plugins use the `.claude/plugin-name.local.md` pattern.\n\n## multi-agent-swarm Plugin\n\n### Settings File Structure\n\n**.claude/multi-agent-swarm.local.md:**\n\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: \"Use JWT tokens, not sessions\"\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\n\n## Requirements\n- JWT token generation and validation\n- Refresh token flow\n- Secure password hashing\n\n## Success Criteria\n- Auth endpoints implemented\n- Tests passing (100% coverage)\n- PR created and CI green\n- Documentation updated\n\n## Coordination\nDepends on Task 3.4 (user model).\nReport status to 'team-leader' session.\n```\n\n### How It's Used\n\n**File:** `hooks/agent-stop-notification.sh`\n\n**Purpose:** Send notifications to coordinator when agent becomes idle\n\n**Implementation:**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nSWARM_STATE_FILE=\".claude/multi-agent-swarm.local.md\"\n\n# Quick exit if no swarm active\nif [[ ! -f \"$SWARM_STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Parse frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$SWARM_STATE_FILE\")\n\n# Extract configuration\nCOORDINATOR_SESSION=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's/coordinator_session: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's/agent_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nTASK_NUMBER=$(echo \"$FRONTMATTER\" | grep '^task_number:' | sed 's/task_number: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nPR_NUMBER=$(echo \"$FRONTMATTER\" | grep '^pr_number:' | sed 's/pr_number: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0\nfi\n\n# Send notification to coordinator\nNOTIFICATION=\"🤖 Agent ${AGENT_NAME} (Task ${TASK_NUMBER}, PR #${PR_NUMBER}) is idle.\"\n\nif tmux has-session -t \"$COORDINATOR_SESSION\" 2>/dev/null; then\n tmux send-keys -t \"$COORDINATOR_SESSION\" \"$NOTIFICATION\" Enter\n sleep 0.5\n tmux send-keys -t \"$COORDINATOR_SESSION\" Enter\nfi\n\nexit 0\n```\n\n**Key patterns:**\n1. **Quick exit** (line 7-9): Returns immediately if file doesn't exist\n2. **Field extraction** (lines 11-17): Parses each frontmatter field\n3. **Enabled check** (lines 19-21): Respects enabled flag\n4. **Action based on settings** (lines 23-29): Uses coordinator_session to send notification\n\n### Creation\n\n**File:** `commands/launch-swarm.md`\n\nSettings files are created during swarm launch with:\n\n```bash\ncat > \"$WORKTREE_PATH/.claude/multi-agent-swarm.local.md\" < temp.md\nmv temp.md \".claude/multi-agent-swarm.local.md\"\n```\n\n## ralph-wiggum Plugin\n\n### Settings File Structure\n\n**.claude/ralph-loop.local.md:**\n\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\nstarted_at: \"2025-01-15T14:30:00Z\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\nDocument any changes needed in CLAUDE.md.\n```\n\n### How It's Used\n\n**File:** `hooks/stop-hook.sh`\n\n**Purpose:** Prevent session exit and loop Claude's output back as input\n\n**Implementation:**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nRALPH_STATE_FILE=\".claude/ralph-loop.local.md\"\n\n# Quick exit if no active loop\nif [[ ! -f \"$RALPH_STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Parse frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$RALPH_STATE_FILE\")\n\n# Extract configuration\nITERATION=$(echo \"$FRONTMATTER\" | grep '^iteration:' | sed 's/iteration: *//')\nMAX_ITERATIONS=$(echo \"$FRONTMATTER\" | grep '^max_iterations:' | sed 's/max_iterations: *//')\nCOMPLETION_PROMISE=$(echo \"$FRONTMATTER\" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Check max iterations\nif [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then\n echo \"🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached.\"\n rm \"$RALPH_STATE_FILE\"\n exit 0\nfi\n\n# Get transcript and check for completion promise\nTRANSCRIPT_PATH=$(echo \"$HOOK_INPUT\" | jq -r '.transcript_path')\nLAST_OUTPUT=$(grep '\"role\":\"assistant\"' \"$TRANSCRIPT_PATH\" | tail -1 | jq -r '.message.content | map(select(.type == \"text\")) | map(.text) | join(\"\\n\")')\n\n# Check for completion\nif [[ \"$COMPLETION_PROMISE\" != \"null\" ]] && [[ -n \"$COMPLETION_PROMISE\" ]]; then\n PROMISE_TEXT=$(echo \"$LAST_OUTPUT\" | perl -0777 -pe 's/.*?(.*?)<\\/promise>.*/$1/s; s/^\\s+|\\s+$//g')\n\n if [[ \"$PROMISE_TEXT\" = \"$COMPLETION_PROMISE\" ]]; then\n echo \"✅ Ralph loop: Detected completion\"\n rm \"$RALPH_STATE_FILE\"\n exit 0\n fi\nfi\n\n# Continue loop - increment iteration\nNEXT_ITERATION=$((ITERATION + 1))\n\n# Extract prompt from markdown body\nPROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' \"$RALPH_STATE_FILE\")\n\n# Update iteration counter\nTEMP_FILE=\"${RALPH_STATE_FILE}.tmp.$$\"\nsed \"s/^iteration: .*/iteration: $NEXT_ITERATION/\" \"$RALPH_STATE_FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$RALPH_STATE_FILE\"\n\n# Block exit and feed prompt back\njq -n \\\n --arg prompt \"$PROMPT_TEXT\" \\\n --arg msg \"🔄 Ralph iteration $NEXT_ITERATION\" \\\n '{\n \"decision\": \"block\",\n \"reason\": $prompt,\n \"systemMessage\": $msg\n }'\n\nexit 0\n```\n\n**Key patterns:**\n1. **Quick exit** (line 7-9): Skip if not active\n2. **Iteration tracking** (lines 11-20): Count and enforce max iterations\n3. **Promise detection** (lines 25-33): Check for completion signal in output\n4. **Prompt extraction** (line 38): Read markdown body as next prompt\n5. **State update** (lines 40-43): Increment iteration atomically\n6. **Loop continuation** (lines 45-53): Block exit and feed prompt back\n\n### Creation\n\n**File:** `scripts/setup-ralph-loop.sh`\n\n```bash\n#!/bin/bash\nPROMPT=\"$1\"\nMAX_ITERATIONS=\"${2:-0}\"\nCOMPLETION_PROMISE=\"${3:-}\"\n\n# Create state file\ncat > \".claude/ralph-loop.local.md\" < \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n**Why:** Prevents corruption if process is interrupted.\n\n### 4. Quote Handling\n\nBoth strip surrounding quotes from YAML values:\n\n```bash\nsed 's/^\"\\(.*\\)\"$/\\1/'\n```\n\n**Why:** YAML allows both `field: value` and `field: \"value\"`.\n\n### 5. Error Handling\n\nBoth handle missing/corrupt files gracefully:\n\n```bash\nif [[ ! -f \"$FILE\" ]]; then\n exit 0 # No error, just not configured\nfi\n\nif [[ -z \"$CRITICAL_FIELD\" ]]; then\n echo \"Settings file corrupt\" >&2\n rm \"$FILE\" # Clean up\n exit 0\nfi\n```\n\n**Why:** Fails gracefully instead of crashing.\n\n## Anti-Patterns to Avoid\n\n### ❌ Hardcoded Paths\n\n```bash\n# BAD\nFILE=\"/Users/alice/.claude/my-plugin.local.md\"\n\n# GOOD\nFILE=\".claude/my-plugin.local.md\"\n```\n\n### ❌ Unquoted Variables\n\n```bash\n# BAD\necho $VALUE\n\n# GOOD\necho \"$VALUE\"\n```\n\n### ❌ Non-Atomic Updates\n\n```bash\n# BAD: Can corrupt file if interrupted\nsed -i \"s/field: .*/field: $VALUE/\" \"$FILE\"\n\n# GOOD: Atomic\nTEMP_FILE=\"${FILE}.tmp.$$\"\nsed \"s/field: .*/field: $VALUE/\" \"$FILE\" > \"$TEMP_FILE\"\nmv \"$TEMP_FILE\" \"$FILE\"\n```\n\n### ❌ No Default Values\n\n```bash\n# BAD: Fails if field missing\nif [[ $MAX -gt 100 ]]; then\n # MAX might be empty!\nfi\n\n# GOOD: Provide default\nMAX=${MAX:-10}\n```\n\n### ❌ Ignoring Edge Cases\n\n```bash\n# BAD: Assumes exactly 2 --- markers\nsed -n '/^---$/,/^---$/{ /^---$/d; p; }'\n\n# GOOD: Handles --- in body\nawk '/^---$/{i++; next} i>=2' # For body\n```\n\n## Conclusion\n\nThe `.claude/plugin-name.local.md` pattern provides:\n- Simple, human-readable configuration\n- Version-control friendly (gitignored)\n- Per-project settings\n- Easy parsing with standard bash tools\n- Supports both structured config (YAML) and freeform content (markdown)\n\nUse this pattern for any plugin that needs user-configurable behavior or state persistence.\n","isInternal":false,"tokens":2729,"sizeBytes":9496},{"name":"SKILL.md","path":"plugins/plugin-dev/skills/plugin-settings/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-settings/SKILL.md","title":"Plugin Settings","category":"anthropic-skill","format":"markdown","content":"---\nname: Plugin Settings\ndescription: This skill should be used when the user asks about \"plugin settings\", \"store plugin configuration\", \"user-configurable plugin\", \".local.md files\", \"plugin state files\", \"read YAML frontmatter\", \"per-project plugin settings\", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.\nversion: 0.1.0\n---\n\n# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store user-configurable settings and state in `.claude/plugin-name.local.md` files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.\n\n**Key characteristics:**\n- File location: `.claude/plugin-name.local.md` in project root\n- Structure: YAML frontmatter + markdown body\n- Purpose: Per-project plugin configuration and state\n- Usage: Read from hooks, commands, and agents\n- Lifecycle: User-managed (not in git, should be in `.gitignore`)\n\n## File Structure\n\n### Basic Template\n\n```markdown\n---\nenabled: true\nsetting1: value1\nsetting2: value2\nnumeric_setting: 42\nlist_setting: [\"item1\", \"item2\"]\n---\n\n# Additional Context\n\nThis markdown body can contain:\n- Task descriptions\n- Additional instructions\n- Prompts to feed back to Claude\n- Documentation or notes\n```\n\n### Example: Plugin State File\n\n**.claude/my-plugin.local.md:**\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_retries: 3\nnotification_level: info\ncoordinator_session: team-leader\n---\n\n# Plugin Configuration\n\nThis plugin is configured for standard validation mode.\nContact @team-lead with questions.\n```\n\n## Reading Settings Files\n\n### From Hooks (Bash Scripts)\n\n**Pattern: Check existence and parse frontmatter**\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Define state file path\nSTATE_FILE=\".claude/my-plugin.local.md\"\n\n# Quick exit if file doesn't exist\nif [[ ! -f \"$STATE_FILE\" ]]; then\n exit 0 # Plugin not configured, skip\nfi\n\n# Parse YAML frontmatter (between --- markers)\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$STATE_FILE\")\n\n# Extract individual fields\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0 # Disabled\nfi\n\n# Use configuration in hook logic\nif [[ \"$STRICT_MODE\" == \"true\" ]]; then\n # Apply strict validation\n # ...\nfi\n```\n\nSee `examples/read-settings-hook.sh` for complete working example.\n\n### From Commands\n\nCommands can read settings files to customize behavior:\n\n```markdown\n---\ndescription: Process data with plugin\nallowed-tools: [\"Read\", \"Bash\"]\n---\n\n# Process Command\n\nSteps:\n1. Check if settings exist at `.claude/my-plugin.local.md`\n2. Read configuration using Read tool\n3. Parse YAML frontmatter to extract settings\n4. Apply settings to processing logic\n5. Execute with configured behavior\n```\n\n### From Agents\n\nAgents can reference settings in their instructions:\n\n```markdown\n---\nname: configured-agent\ndescription: Agent that adapts to project settings\n---\n\nCheck for plugin settings at `.claude/my-plugin.local.md`.\nIf present, parse YAML frontmatter and adapt behavior according to:\n- enabled: Whether plugin is active\n- mode: Processing mode (strict, standard, lenient)\n- Additional configuration fields\n```\n\n## Parsing Techniques\n\n### Extract Frontmatter\n\n```bash\n# Extract everything between --- markers\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n```\n\n### Read Individual Fields\n\n**String fields:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n# Compare: if [[ \"$ENABLED\" == \"true\" ]]; then\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n# Use: if [[ $MAX -gt 100 ]]; then\n```\n\n### Read Markdown Body\n\nExtract content after second `---`:\n\n```bash\n# Get everything after closing ---\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n## Common Patterns\n\n### Pattern 1: Temporarily Active Hooks\n\nUse settings file to control hook activation:\n\n```bash\n#!/bin/bash\nSTATE_FILE=\".claude/security-scan.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$STATE_FILE\" ]]; then\n exit 0\nfi\n\n# Read enabled flag\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//')\n\nif [[ \"$ENABLED\" != \"true\" ]]; then\n exit 0 # Disabled\nfi\n\n# Run hook logic\n# ...\n```\n\n**Use case:** Enable/disable hooks without editing hooks.json (requires restart).\n\n### Pattern 2: Agent State Management\n\nStore agent-specific state and configuration:\n\n**.claude/multi-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-agent\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\n---\n\n# Task Assignment\n\nImplement JWT authentication for the API.\n\n**Success Criteria:**\n- Authentication endpoints created\n- Tests passing\n- PR created and CI green\n```\n\nRead from hooks to coordinate agents:\n\n```bash\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's/agent_name: *//')\nCOORDINATOR=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')\n\n# Send notification to coordinator\ntmux send-keys -t \"$COORDINATOR\" \"Agent $AGENT_NAME completed task\" Enter\n```\n\n### Pattern 3: Configuration-Driven Behavior\n\n**.claude/my-plugin.local.md:**\n```markdown\n---\nvalidation_level: strict\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\n---\n\n# Validation Configuration\n\nStrict mode enabled for this project.\nAll writes validated against security policies.\n```\n\nUse in hooks or commands:\n\n```bash\nLEVEL=$(echo \"$FRONTMATTER\" | grep '^validation_level:' | sed 's/validation_level: *//')\n\ncase \"$LEVEL\" in\n strict)\n # Apply strict validation\n ;;\n standard)\n # Apply standard validation\n ;;\n lenient)\n # Apply lenient validation\n ;;\nesac\n```\n\n## Creating Settings Files\n\n### From Commands\n\nCommands can create settings files:\n\n```markdown\n# Setup Command\n\nSteps:\n1. Ask user for configuration preferences\n2. Create `.claude/my-plugin.local.md` with YAML frontmatter\n3. Set appropriate values based on user input\n4. Inform user that settings are saved\n5. Remind user to restart Claude Code for hooks to recognize changes\n```\n\n### Template Generation\n\nProvide template in plugin README:\n\n```markdown\n## Configuration\n\nCreate `.claude/my-plugin.local.md` in your project:\n\n\\`\\`\\`markdown\n---\nenabled: true\nmode: standard\nmax_retries: 3\n---\n\n# Plugin Configuration\n\nYour settings are active.\n\\`\\`\\`\n\nAfter creating or editing, restart Claude Code for changes to take effect.\n```\n\n## Best Practices\n\n### File Naming\n\n✅ **DO:**\n- Use `.claude/plugin-name.local.md` format\n- Match plugin name exactly\n- Use `.local.md` suffix for user-local files\n\n❌ **DON'T:**\n- Use different directory (not `.claude/`)\n- Use inconsistent naming\n- Use `.md` without `.local` (might be committed)\n\n### Gitignore\n\nAlways add to `.gitignore`:\n\n```gitignore\n.claude/*.local.md\n.claude/*.local.json\n```\n\nDocument this in plugin README.\n\n### Defaults\n\nProvide sensible defaults when settings file doesn't exist:\n\n```bash\nif [[ ! -f \"$STATE_FILE\" ]]; then\n # Use defaults\n ENABLED=true\n MODE=standard\nelse\n # Read from file\n # ...\nfi\n```\n\n### Validation\n\nValidate settings values:\n\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's/max_value: *//')\n\n# Validate numeric range\nif ! [[ \"$MAX\" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then\n echo \"⚠️ Invalid max_value in settings (must be 1-100)\" >&2\n MAX=10 # Use default\nfi\n```\n\n### Restart Requirement\n\n**Important:** Settings changes require Claude Code restart.\n\nDocument in your README:\n\n```markdown\n## Changing Settings\n\nAfter editing `.claude/my-plugin.local.md`:\n1. Save the file\n2. Exit Claude Code\n3. Restart: `claude` or `cc`\n4. New settings will be loaded\n```\n\nHooks cannot be hot-swapped within a session.\n\n## Security Considerations\n\n### Sanitize User Input\n\nWhen writing settings files from user input:\n\n```bash\n# Escape quotes in user input\nSAFE_VALUE=$(echo \"$USER_INPUT\" | sed 's/\"/\\\\\"/g')\n\n# Write to file\ncat > \"$STATE_FILE\" <&2\n exit 2\nfi\n```\n\n### Permissions\n\nSettings files should be:\n- Readable by user only (`chmod 600`)\n- Not committed to git\n- Not shared between users\n\n## Real-World Examples\n\n### multi-agent-swarm Plugin\n\n**.claude/multi-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: Use JWT tokens, not sessions\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\nCoordinate with auth-agent on shared types.\n```\n\n**Hook usage (agent-stop-notification.sh):**\n- Checks if file exists (line 15-18: quick exit if not)\n- Parses frontmatter to get coordinator_session, agent_name, enabled\n- Sends notifications to coordinator if enabled\n- Allows quick activation/deactivation via `enabled: true/false`\n\n### ralph-wiggum Plugin\n\n**.claude/ralph-loop.local.md:**\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\n```\n\n**Hook usage (stop-hook.sh):**\n- Checks if file exists (line 15-18: quick exit if not active)\n- Reads iteration count and max_iterations\n- Extracts completion_promise for loop termination\n- Reads body as the prompt to feed back\n- Updates iteration count on each loop\n\n## Quick Reference\n\n### File Location\n\n```\nproject-root/\n└── .claude/\n └── plugin-name.local.md\n```\n\n### Frontmatter Parsing\n\n```bash\n# Extract frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$FILE\")\n\n# Read field\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's/field: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\n```\n\n### Body Parsing\n\n```bash\n# Extract body (after second ---)\nBODY=$(awk '/^---$/{i++; next} i>=2' \"$FILE\")\n```\n\n### Quick Exit Pattern\n\n```bash\nif [[ ! -f \".claude/my-plugin.local.md\" ]]; then\n exit 0 # Not configured\nfi\n```\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed implementation patterns:\n\n- **`references/parsing-techniques.md`** - Complete guide to parsing YAML frontmatter and markdown bodies\n- **`references/real-world-examples.md`** - Deep dive into multi-agent-swarm and ralph-wiggum implementations\n\n### Example Files\n\nWorking examples in `examples/`:\n\n- **`read-settings-hook.sh`** - Hook that reads and uses settings\n- **`create-settings-command.md`** - Command that creates settings file\n- **`example-settings.md`** - Template settings file\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-settings.sh`** - Validate settings file structure\n- **`parse-frontmatter.sh`** - Extract frontmatter fields\n\n## Implementation Workflow\n\nTo add settings to a plugin:\n\n1. Design settings schema (which fields, types, defaults)\n2. Create template file in plugin documentation\n3. Add gitignore entry for `.claude/*.local.md`\n4. Implement settings parsing in hooks/commands\n5. Use quick-exit pattern (check file exists, check enabled field)\n6. Document settings in plugin README with template\n7. Remind users that changes require Claude Code restart\n\nFocus on keeping settings simple and providing good defaults when settings file doesn't exist.\n","frontmatter":{"name":"Plugin Settings","description":"This skill should be used when the user asks about \"plugin settings\", \"store plugin configuration\", \"user-configurable plugin\", \".local.md files\", \"plugin state files\", \"read YAML frontmatter\", \"per-project plugin settings\", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.","version":"0.1.0"},"isInternal":false,"tokens":3111,"sizeBytes":12101},{"name":"advanced-plugin.md","path":"plugins/plugin-dev/skills/plugin-structure/examples/advanced-plugin.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-structure/examples/advanced-plugin.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# Advanced Plugin Example\n\nA complex, enterprise-grade plugin with MCP integration and advanced organization.\n\n## Directory Structure\n\n```\nenterprise-devops/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n│ ├── ci/\n│ │ ├── build.md\n│ │ ├── test.md\n│ │ └── deploy.md\n│ ├── monitoring/\n│ │ ├── status.md\n│ │ └── logs.md\n│ └── admin/\n│ ├── configure.md\n│ └── manage.md\n├── agents/\n│ ├── orchestration/\n│ │ ├── deployment-orchestrator.md\n│ │ └── rollback-manager.md\n│ └── specialized/\n│ ├── kubernetes-expert.md\n│ ├── terraform-expert.md\n│ └── security-auditor.md\n├── skills/\n│ ├── kubernetes-ops/\n│ │ ├── SKILL.md\n│ │ ├── references/\n│ │ │ ├── deployment-patterns.md\n│ │ │ ├── troubleshooting.md\n│ │ │ └── security.md\n│ │ ├── examples/\n│ │ │ ├── basic-deployment.yaml\n│ │ │ ├── stateful-set.yaml\n│ │ │ └── ingress-config.yaml\n│ │ └── scripts/\n│ │ ├── validate-manifest.sh\n│ │ └── health-check.sh\n│ ├── terraform-iac/\n│ │ ├── SKILL.md\n│ │ ├── references/\n│ │ │ └── best-practices.md\n│ │ └── examples/\n│ │ └── module-template/\n│ └── ci-cd-pipelines/\n│ ├── SKILL.md\n│ └── references/\n│ └── pipeline-patterns.md\n├── hooks/\n│ ├── hooks.json\n│ └── scripts/\n│ ├── security/\n│ │ ├── scan-secrets.sh\n│ │ ├── validate-permissions.sh\n│ │ └── audit-changes.sh\n│ ├── quality/\n│ │ ├── check-config.sh\n│ │ └── verify-tests.sh\n│ └── workflow/\n│ ├── notify-team.sh\n│ └── update-status.sh\n├── .mcp.json\n├── servers/\n│ ├── kubernetes-mcp/\n│ │ ├── index.js\n│ │ ├── package.json\n│ │ └── lib/\n│ ├── terraform-mcp/\n│ │ ├── main.py\n│ │ └── requirements.txt\n│ └── github-actions-mcp/\n│ ├── server.js\n│ └── package.json\n├── lib/\n│ ├── core/\n│ │ ├── logger.js\n│ │ ├── config.js\n│ │ └── auth.js\n│ ├── integrations/\n│ │ ├── slack.js\n│ │ ├── pagerduty.js\n│ │ └── datadog.js\n│ └── utils/\n│ ├── retry.js\n│ └── validation.js\n└── config/\n ├── environments/\n │ ├── production.json\n │ ├── staging.json\n │ └── development.json\n └── templates/\n ├── deployment.yaml\n └── service.yaml\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"enterprise-devops\",\n \"version\": \"2.3.1\",\n \"description\": \"Comprehensive DevOps automation for enterprise CI/CD pipelines, infrastructure management, and monitoring\",\n \"author\": {\n \"name\": \"DevOps Platform Team\",\n \"email\": \"devops-platform@company.com\",\n \"url\": \"https://company.com/teams/devops\"\n },\n \"homepage\": \"https://docs.company.com/plugins/devops\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/company/devops-plugin.git\"\n },\n \"license\": \"Apache-2.0\",\n \"keywords\": [\n \"devops\",\n \"ci-cd\",\n \"kubernetes\",\n \"terraform\",\n \"automation\",\n \"infrastructure\",\n \"deployment\",\n \"monitoring\"\n ],\n \"commands\": [\n \"./commands/ci\",\n \"./commands/monitoring\",\n \"./commands/admin\"\n ],\n \"agents\": [\n \"./agents/orchestration\",\n \"./agents/specialized\"\n ],\n \"hooks\": \"./hooks/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n### .mcp.json\n\n```json\n{\n \"mcpServers\": {\n \"kubernetes\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/kubernetes-mcp/index.js\"],\n \"env\": {\n \"KUBECONFIG\": \"${KUBECONFIG}\",\n \"K8S_NAMESPACE\": \"${K8S_NAMESPACE:-default}\"\n }\n },\n \"terraform\": {\n \"command\": \"python\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/terraform-mcp/main.py\"],\n \"env\": {\n \"TF_STATE_BUCKET\": \"${TF_STATE_BUCKET}\",\n \"AWS_REGION\": \"${AWS_REGION}\"\n }\n },\n \"github-actions\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/github-actions-mcp/server.js\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\",\n \"GITHUB_ORG\": \"${GITHUB_ORG}\"\n }\n }\n }\n}\n```\n\n### commands/ci/build.md\n\n```markdown\n---\nname: build\ndescription: Trigger and monitor CI build pipeline\n---\n\n# Build Command\n\nTrigger CI/CD build pipeline and monitor progress in real-time.\n\n## Process\n\n1. **Validation**: Check prerequisites\n - Verify branch status\n - Check for uncommitted changes\n - Validate configuration files\n\n2. **Trigger**: Start build via MCP server\n \\`\\`\\`javascript\n // Uses github-actions MCP server\n const build = await tools.github_actions_trigger_workflow({\n workflow: 'build.yml',\n ref: currentBranch\n })\n \\`\\`\\`\n\n3. **Monitor**: Track build progress\n - Display real-time logs\n - Show test results as they complete\n - Alert on failures\n\n4. **Report**: Summarize results\n - Build status\n - Test coverage\n - Performance metrics\n - Deploy readiness\n\n## Integration\n\nAfter successful build:\n- Offer to deploy to staging\n- Suggest performance optimizations\n- Generate deployment checklist\n```\n\n### agents/orchestration/deployment-orchestrator.md\n\n```markdown\n---\ndescription: Orchestrates complex multi-environment deployments with rollback capabilities and health monitoring\ncapabilities:\n - Plan and execute multi-stage deployments\n - Coordinate service dependencies\n - Monitor deployment health\n - Execute automated rollbacks\n - Manage deployment approvals\n---\n\n# Deployment Orchestrator Agent\n\nSpecialized agent for orchestrating complex deployments across multiple environments.\n\n## Expertise\n\n- **Deployment strategies**: Blue-green, canary, rolling updates\n- **Dependency management**: Service startup ordering, dependency injection\n- **Health monitoring**: Service health checks, metric validation\n- **Rollback automation**: Automatic rollback on failure detection\n- **Approval workflows**: Multi-stage approval processes\n\n## Orchestration Process\n\n1. **Planning Phase**\n - Analyze deployment requirements\n - Identify service dependencies\n - Generate deployment plan\n - Calculate rollback strategy\n\n2. **Validation Phase**\n - Verify environment readiness\n - Check resource availability\n - Validate configurations\n - Run pre-deployment tests\n\n3. **Execution Phase**\n - Deploy services in dependency order\n - Monitor health after each stage\n - Validate metrics and logs\n - Proceed to next stage on success\n\n4. **Verification Phase**\n - Run smoke tests\n - Validate service integration\n - Check performance metrics\n - Confirm deployment success\n\n5. **Rollback Phase** (if needed)\n - Detect failure conditions\n - Execute rollback plan\n - Restore previous state\n - Notify stakeholders\n\n## MCP Integration\n\nUses multiple MCP servers:\n- `kubernetes`: Deploy and manage containers\n- `terraform`: Provision infrastructure\n- `github-actions`: Trigger deployment pipelines\n\n## Monitoring Integration\n\nIntegrates with monitoring tools via lib:\n\\`\\`\\`javascript\nconst { DatadogClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/datadog')\nconst metrics = await DatadogClient.getMetrics(service, timeRange)\n\\`\\`\\`\n\n## Notification Integration\n\nSends updates via Slack and PagerDuty:\n\\`\\`\\`javascript\nconst { SlackClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/slack')\nawait SlackClient.notify({\n channel: '#deployments',\n message: 'Deployment started',\n metadata: deploymentPlan\n})\n\\`\\`\\`\n```\n\n### skills/kubernetes-ops/SKILL.md\n\n```markdown\n---\nname: Kubernetes Operations\ndescription: This skill should be used when deploying to Kubernetes, managing K8s resources, troubleshooting cluster issues, configuring ingress/services, scaling deployments, or working with Kubernetes manifests. Provides comprehensive Kubernetes operational knowledge and best practices.\nversion: 2.0.0\n---\n\n# Kubernetes Operations\n\nComprehensive operational knowledge for managing Kubernetes clusters and workloads.\n\n## Overview\n\nManage Kubernetes infrastructure effectively through:\n- Deployment strategies and patterns\n- Resource configuration and optimization\n- Troubleshooting and debugging\n- Security best practices\n- Performance tuning\n\n## Core Concepts\n\n### Resource Management\n\n**Deployments**: Use for stateless applications\n- Rolling updates for zero-downtime deployments\n- Rollback capabilities for failed deployments\n- Replica management for scaling\n\n**StatefulSets**: Use for stateful applications\n- Stable network identities\n- Persistent storage\n- Ordered deployment and scaling\n\n**DaemonSets**: Use for node-level services\n- Log collectors\n- Monitoring agents\n- Network plugins\n\n### Configuration\n\n**ConfigMaps**: Store non-sensitive configuration\n- Environment-specific settings\n- Application configuration files\n- Feature flags\n\n**Secrets**: Store sensitive data\n- API keys and tokens\n- Database credentials\n- TLS certificates\n\nUse external secret management (Vault, AWS Secrets Manager) for production.\n\n### Networking\n\n**Services**: Expose applications internally\n- ClusterIP for internal communication\n- NodePort for external access (non-production)\n- LoadBalancer for external access (production)\n\n**Ingress**: HTTP/HTTPS routing\n- Path-based routing\n- Host-based routing\n- TLS termination\n- Load balancing\n\n## Deployment Strategies\n\n### Rolling Update\n\nDefault strategy, gradual replacement:\n\\`\\`\\`yaml\nstrategy:\n type: RollingUpdate\n rollingUpdate:\n maxSurge: 1\n maxUnavailable: 0\n\\`\\`\\`\n\n**When to use**: Standard deployments, minor updates\n\n### Recreate\n\nStop all pods, then create new ones:\n\\`\\`\\`yaml\nstrategy:\n type: Recreate\n\\`\\`\\`\n\n**When to use**: Stateful apps that can't run multiple versions\n\n### Blue-Green\n\nRun two complete environments, switch traffic:\n1. Deploy new version (green)\n2. Test green environment\n3. Switch traffic to green\n4. Keep blue for quick rollback\n\n**When to use**: Critical services, need instant rollback\n\n### Canary\n\nGradually roll out to subset of users:\n1. Deploy canary version (10% traffic)\n2. Monitor metrics and errors\n3. Increase traffic gradually\n4. Complete rollout or rollback\n\n**When to use**: High-risk changes, want gradual validation\n\n## Resource Configuration\n\n### Resource Requests and Limits\n\nAlways set for production workloads:\n\\`\\`\\`yaml\nresources:\n requests:\n memory: \"256Mi\"\n cpu: \"250m\"\n limits:\n memory: \"512Mi\"\n cpu: \"500m\"\n\\`\\`\\`\n\n**Requests**: Guaranteed resources\n**Limits**: Maximum allowed resources\n\n### Health Checks\n\nEssential for reliability:\n\\`\\`\\`yaml\nlivenessProbe:\n httpGet:\n path: /health\n port: 8080\n initialDelaySeconds: 30\n periodSeconds: 10\n\nreadinessProbe:\n httpGet:\n path: /ready\n port: 8080\n initialDelaySeconds: 5\n periodSeconds: 5\n\\`\\`\\`\n\n**Liveness**: Restart unhealthy pods\n**Readiness**: Remove unready pods from service\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Pods not starting**\n - Check: `kubectl describe pod `\n - Look for: Image pull errors, resource constraints\n - Fix: Verify image name, increase resources\n\n2. **Service not reachable**\n - Check: `kubectl get svc`, `kubectl get endpoints`\n - Look for: No endpoints, wrong selector\n - Fix: Verify pod labels match service selector\n\n3. **High memory usage**\n - Check: `kubectl top pods`\n - Look for: Pods near memory limit\n - Fix: Increase limits, optimize application\n\n4. **Frequent restarts**\n - Check: `kubectl get pods`, `kubectl logs `\n - Look for: Liveness probe failures, OOMKilled\n - Fix: Adjust health checks, increase memory\n\n### Debugging Commands\n\nGet pod details:\n\\`\\`\\`bash\nkubectl describe pod \nkubectl logs \nkubectl logs --previous # logs from crashed container\n\\`\\`\\`\n\nExecute commands in pod:\n\\`\\`\\`bash\nkubectl exec -it -- /bin/sh\nkubectl exec -- env\n\\`\\`\\`\n\nCheck resource usage:\n\\`\\`\\`bash\nkubectl top nodes\nkubectl top pods\n\\`\\`\\`\n\n## Security Best Practices\n\n### Pod Security\n\n- Run as non-root user\n- Use read-only root filesystem\n- Drop unnecessary capabilities\n- Use security contexts\n\nExample:\n\\`\\`\\`yaml\nsecurityContext:\n runAsNonRoot: true\n runAsUser: 1000\n readOnlyRootFilesystem: true\n capabilities:\n drop:\n - ALL\n\\`\\`\\`\n\n### Network Policies\n\nRestrict pod communication:\n\\`\\`\\`yaml\napiVersion: networking.k8s.io/v1\nkind: NetworkPolicy\nmetadata:\n name: api-allow\nspec:\n podSelector:\n matchLabels:\n app: api\n ingress:\n - from:\n - podSelector:\n matchLabels:\n app: frontend\n\\`\\`\\`\n\n### Secrets Management\n\n- Never commit secrets to git\n- Use external secret managers\n- Rotate secrets regularly\n- Limit secret access with RBAC\n\n## Performance Optimization\n\n### Resource Tuning\n\n1. **Start conservative**: Set low limits initially\n2. **Monitor usage**: Track actual resource consumption\n3. **Adjust gradually**: Increase based on metrics\n4. **Set appropriate requests**: Match typical usage\n5. **Set safe limits**: 2x requests for headroom\n\n### Horizontal Pod Autoscaling\n\nAutomatically scale based on metrics:\n\\`\\`\\`yaml\napiVersion: autoscaling/v2\nkind: HorizontalPodAutoscaler\nmetadata:\n name: api-hpa\nspec:\n scaleTargetRef:\n apiVersion: apps/v1\n kind: Deployment\n name: api\n minReplicas: 2\n maxReplicas: 10\n metrics:\n - type: Resource\n resource:\n name: cpu\n target:\n type: Utilization\n averageUtilization: 70\n\\`\\`\\`\n\n## MCP Server Integration\n\nThis skill works with the kubernetes MCP server for operations:\n\n**List pods**:\n\\`\\`\\`javascript\nconst pods = await tools.k8s_list_pods({ namespace: 'default' })\n\\`\\`\\`\n\n**Get pod logs**:\n\\`\\`\\`javascript\nconst logs = await tools.k8s_get_logs({ pod: 'api-xyz', container: 'app' })\n\\`\\`\\`\n\n**Apply manifests**:\n\\`\\`\\`javascript\nconst result = await tools.k8s_apply_manifest({ file: 'deployment.yaml' })\n\\`\\`\\`\n\n## Detailed References\n\nFor in-depth information:\n- **Deployment patterns**: `references/deployment-patterns.md`\n- **Troubleshooting guide**: `references/troubleshooting.md`\n- **Security hardening**: `references/security.md`\n\n## Example Manifests\n\nFor copy-paste examples:\n- **Basic deployment**: `examples/basic-deployment.yaml`\n- **StatefulSet**: `examples/stateful-set.yaml`\n- **Ingress config**: `examples/ingress-config.yaml`\n\n## Validation Scripts\n\nFor manifest validation:\n\\`\\`\\`bash\nbash ${CLAUDE_PLUGIN_ROOT}/skills/kubernetes-ops/scripts/validate-manifest.sh deployment.yaml\n\\`\\`\\`\n```\n\n### hooks/hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/scan-secrets.sh\",\n \"timeout\": 30\n }\n ]\n },\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Evaluate if this bash command is safe for production environment. Check for destructive operations, missing safeguards, and potential security issues. Commands should be idempotent and reversible.\",\n \"timeout\": 20\n }\n ]\n }\n ],\n \"PostToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/update-status.sh\",\n \"timeout\": 15\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quality/check-config.sh\",\n \"timeout\": 45\n },\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/notify-team.sh\",\n \"timeout\": 30\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/validate-permissions.sh\",\n \"timeout\": 20\n }\n ]\n }\n ]\n}\n```\n\n## Key Features\n\n### Multi-Level Organization\n\n**Commands**: Organized by function (CI, monitoring, admin)\n**Agents**: Separated by role (orchestration vs. specialized)\n**Skills**: Rich resources (references, examples, scripts)\n\n### MCP Integration\n\nThree custom MCP servers:\n- **Kubernetes**: Cluster operations\n- **Terraform**: Infrastructure provisioning\n- **GitHub Actions**: CI/CD automation\n\n### Shared Libraries\n\nReusable code in `lib/`:\n- **Core**: Common utilities (logging, config, auth)\n- **Integrations**: External services (Slack, Datadog)\n- **Utils**: Helper functions (retry, validation)\n\n### Configuration Management\n\nEnvironment-specific configs in `config/`:\n- **Environments**: Per-environment settings\n- **Templates**: Reusable deployment templates\n\n### Security Automation\n\nMultiple security hooks:\n- Secret scanning before writes\n- Permission validation on session start\n- Configuration auditing on completion\n\n### Monitoring Integration\n\nBuilt-in monitoring via lib integrations:\n- Datadog for metrics\n- PagerDuty for alerts\n- Slack for notifications\n\n## Use Cases\n\n1. **Multi-environment deployments**: Orchestrated rollouts across dev/staging/prod\n2. **Infrastructure as code**: Terraform automation with state management\n3. **CI/CD automation**: Build, test, deploy pipelines\n4. **Monitoring and observability**: Integrated metrics and alerting\n5. **Security enforcement**: Automated security scanning and validation\n6. **Team collaboration**: Slack notifications and status updates\n\n## When to Use This Pattern\n\n- Large-scale enterprise deployments\n- Multiple environment management\n- Complex CI/CD workflows\n- Integrated monitoring requirements\n- Security-critical infrastructure\n- Team collaboration needs\n\n## Scaling Considerations\n\n- **Performance**: Separate MCP servers for parallel operations\n- **Organization**: Multi-level directories for scalability\n- **Maintainability**: Shared libraries reduce duplication\n- **Flexibility**: Environment configs enable customization\n- **Security**: Layered security hooks and validation\n","isInternal":false,"tokens":4448,"sizeBytes":18746},{"name":"minimal-plugin.md","path":"plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# Minimal Plugin Example\n\nA bare-bones plugin with a single command.\n\n## Directory Structure\n\n```\nhello-world/\n├── .claude-plugin/\n│ └── plugin.json\n└── commands/\n └── hello.md\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"hello-world\"\n}\n```\n\n### commands/hello.md\n\n```markdown\n---\nname: hello\ndescription: Prints a friendly greeting message\n---\n\n# Hello Command\n\nPrint a friendly greeting to the user.\n\n## Implementation\n\nOutput the following message to the user:\n\n> Hello! This is a simple command from the hello-world plugin.\n>\n> Use this as a starting point for building more complex plugins.\n\nInclude the current timestamp in the greeting to show the command executed successfully.\n```\n\n## Usage\n\nAfter installing the plugin:\n\n```\n$ claude\n> /hello\nHello! This is a simple command from the hello-world plugin.\n\nUse this as a starting point for building more complex plugins.\n\nExecuted at: 2025-01-15 14:30:22 UTC\n```\n\n## Key Points\n\n1. **Minimal manifest**: Only the required `name` field\n2. **Single command**: One markdown file in `commands/` directory\n3. **Auto-discovery**: Claude Code finds the command automatically\n4. **No dependencies**: No scripts, hooks, or external resources\n\n## When to Use This Pattern\n\n- Quick prototypes\n- Single-purpose utilities\n- Learning plugin development\n- Internal team tools with one specific function\n\n## Extending This Plugin\n\nTo add more functionality:\n\n1. **Add commands**: Create more `.md` files in `commands/`\n2. **Add metadata**: Update `plugin.json` with version, description, author\n3. **Add agents**: Create `agents/` directory with agent definitions\n4. **Add hooks**: Create `hooks/hooks.json` for event handling\n","isInternal":false,"tokens":406,"sizeBytes":1731},{"name":"standard-plugin.md","path":"plugins/plugin-dev/skills/plugin-structure/examples/standard-plugin.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-structure/examples/standard-plugin.md","title":"Examples Skill","category":"anthropic-skill","format":"markdown","content":"# Standard Plugin Example\n\nA well-structured plugin with commands, agents, and skills.\n\n## Directory Structure\n\n```\ncode-quality/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n│ ├── lint.md\n│ ├── test.md\n│ └── review.md\n├── agents/\n│ ├── code-reviewer.md\n│ └── test-generator.md\n├── skills/\n│ ├── code-standards/\n│ │ ├── SKILL.md\n│ │ └── references/\n│ │ └── style-guide.md\n│ └── testing-patterns/\n│ ├── SKILL.md\n│ └── examples/\n│ ├── unit-test.js\n│ └── integration-test.js\n├── hooks/\n│ ├── hooks.json\n│ └── scripts/\n│ └── validate-commit.sh\n└── scripts/\n ├── run-linter.sh\n └── generate-report.py\n```\n\n## File Contents\n\n### .claude-plugin/plugin.json\n\n```json\n{\n \"name\": \"code-quality\",\n \"version\": \"1.0.0\",\n \"description\": \"Comprehensive code quality tools including linting, testing, and review automation\",\n \"author\": {\n \"name\": \"Quality Team\",\n \"email\": \"quality@example.com\"\n },\n \"homepage\": \"https://docs.example.com/plugins/code-quality\",\n \"repository\": \"https://github.com/example/code-quality-plugin\",\n \"license\": \"MIT\",\n \"keywords\": [\"code-quality\", \"linting\", \"testing\", \"code-review\", \"automation\"]\n}\n```\n\n### commands/lint.md\n\n```markdown\n---\nname: lint\ndescription: Run linting checks on the codebase\n---\n\n# Lint Command\n\nRun comprehensive linting checks on the project codebase.\n\n## Process\n\n1. Detect project type and installed linters\n2. Run appropriate linters (ESLint, Pylint, RuboCop, etc.)\n3. Collect and format results\n4. Report issues with file locations and severity\n\n## Implementation\n\nExecute the linting script:\n\n\\`\\`\\`bash\nbash ${CLAUDE_PLUGIN_ROOT}/scripts/run-linter.sh\n\\`\\`\\`\n\nParse the output and present issues organized by:\n- Critical issues (must fix)\n- Warnings (should fix)\n- Style suggestions (optional)\n\nFor each issue, show:\n- File path and line number\n- Issue description\n- Suggested fix (if available)\n```\n\n### commands/test.md\n\n```markdown\n---\nname: test\ndescription: Run test suite with coverage reporting\n---\n\n# Test Command\n\nExecute the project test suite and generate coverage reports.\n\n## Process\n\n1. Identify test framework (Jest, pytest, RSpec, etc.)\n2. Run all tests\n3. Generate coverage report\n4. Identify untested code\n\n## Output\n\nPresent results in structured format:\n- Test summary (passed/failed/skipped)\n- Coverage percentage by file\n- Critical untested areas\n- Failed test details\n\n## Integration\n\nAfter test completion, offer to:\n- Fix failing tests\n- Generate tests for untested code (using test-generator agent)\n- Update documentation based on test changes\n```\n\n### agents/code-reviewer.md\n\n```markdown\n---\ndescription: Expert code reviewer specializing in identifying bugs, security issues, and improvement opportunities\ncapabilities:\n - Analyze code for potential bugs and logic errors\n - Identify security vulnerabilities\n - Suggest performance improvements\n - Ensure code follows project standards\n - Review test coverage adequacy\n---\n\n# Code Reviewer Agent\n\nSpecialized agent for comprehensive code review.\n\n## Expertise\n\n- **Bug detection**: Logic errors, edge cases, error handling\n- **Security analysis**: Injection vulnerabilities, authentication issues, data exposure\n- **Performance**: Algorithm efficiency, resource usage, optimization opportunities\n- **Standards compliance**: Style guide adherence, naming conventions, documentation\n- **Test coverage**: Adequacy of test cases, missing scenarios\n\n## Review Process\n\n1. **Initial scan**: Quick pass for obvious issues\n2. **Deep analysis**: Line-by-line review of changed code\n3. **Context evaluation**: Check impact on related code\n4. **Best practices**: Compare against project and language standards\n5. **Recommendations**: Prioritized list of improvements\n\n## Integration with Skills\n\nAutomatically loads `code-standards` skill for project-specific guidelines.\n\n## Output Format\n\nFor each file reviewed:\n- Overall assessment\n- Critical issues (must fix before merge)\n- Important issues (should fix)\n- Suggestions (nice to have)\n- Positive feedback (what was done well)\n```\n\n### agents/test-generator.md\n\n```markdown\n---\ndescription: Generates comprehensive test suites from code analysis\ncapabilities:\n - Analyze code structure and logic flow\n - Generate unit tests for functions and methods\n - Create integration tests for modules\n - Design edge case and error condition tests\n - Suggest test fixtures and mocks\n---\n\n# Test Generator Agent\n\nSpecialized agent for generating comprehensive test suites.\n\n## Expertise\n\n- **Unit testing**: Individual function/method tests\n- **Integration testing**: Module interaction tests\n- **Edge cases**: Boundary conditions, error paths\n- **Test organization**: Proper test structure and naming\n- **Mocking**: Appropriate use of mocks and stubs\n\n## Generation Process\n\n1. **Code analysis**: Understand function purpose and logic\n2. **Path identification**: Map all execution paths\n3. **Input design**: Create test inputs covering all paths\n4. **Assertion design**: Define expected outputs\n5. **Test generation**: Write tests in project's framework\n\n## Integration with Skills\n\nAutomatically loads `testing-patterns` skill for project-specific test conventions.\n\n## Test Quality\n\nGenerated tests include:\n- Happy path scenarios\n- Edge cases and boundary conditions\n- Error handling verification\n- Mock data for external dependencies\n- Clear test descriptions\n```\n\n### skills/code-standards/SKILL.md\n\n```markdown\n---\nname: Code Standards\ndescription: This skill should be used when reviewing code, enforcing style guidelines, checking naming conventions, or ensuring code quality standards. Provides project-specific coding standards and best practices.\nversion: 1.0.0\n---\n\n# Code Standards\n\nComprehensive coding standards and best practices for maintaining code quality.\n\n## Overview\n\nEnforce consistent code quality through standardized conventions for:\n- Code style and formatting\n- Naming conventions\n- Documentation requirements\n- Error handling patterns\n- Security practices\n\n## Style Guidelines\n\n### Formatting\n\n- **Indentation**: 2 spaces (JavaScript/TypeScript), 4 spaces (Python)\n- **Line length**: Maximum 100 characters\n- **Braces**: Same line for opening brace (K&R style)\n- **Whitespace**: Space after commas, around operators\n\n### Naming Conventions\n\n- **Variables**: camelCase for JavaScript, snake_case for Python\n- **Functions**: camelCase, descriptive verb-noun pairs\n- **Classes**: PascalCase\n- **Constants**: UPPER_SNAKE_CASE\n- **Files**: kebab-case for modules\n\n## Documentation Requirements\n\n### Function Documentation\n\nEvery function must include:\n- Purpose description\n- Parameter descriptions with types\n- Return value description with type\n- Example usage (for public functions)\n\n### Module Documentation\n\nEvery module must include:\n- Module purpose\n- Public API overview\n- Usage examples\n- Dependencies\n\n## Error Handling\n\n### Required Practices\n\n- Never swallow errors silently\n- Always log errors with context\n- Use specific error types\n- Provide actionable error messages\n- Clean up resources in finally blocks\n\n### Example Pattern\n\n\\`\\`\\`javascript\nasync function processData(data) {\n try {\n const result = await transform(data)\n return result\n } catch (error) {\n logger.error('Data processing failed', {\n data: sanitize(data),\n error: error.message,\n stack: error.stack\n })\n throw new DataProcessingError('Failed to process data', { cause: error })\n }\n}\n\\`\\`\\`\n\n## Security Practices\n\n- Validate all external input\n- Sanitize data before output\n- Use parameterized queries\n- Never log sensitive information\n- Keep dependencies updated\n\n## Detailed Guidelines\n\nFor comprehensive style guides by language, see:\n- `references/style-guide.md`\n```\n\n### skills/code-standards/references/style-guide.md\n\n```markdown\n# Comprehensive Style Guide\n\nDetailed style guidelines for all supported languages.\n\n## JavaScript/TypeScript\n\n### Variable Declarations\n\nUse `const` by default, `let` when reassignment needed, never `var`:\n\n\\`\\`\\`javascript\n// Good\nconst MAX_RETRIES = 3\nlet currentTry = 0\n\n// Bad\nvar MAX_RETRIES = 3\n\\`\\`\\`\n\n### Function Declarations\n\nUse function expressions for consistency:\n\n\\`\\`\\`javascript\n// Good\nconst calculateTotal = (items) => {\n return items.reduce((sum, item) => sum + item.price, 0)\n}\n\n// Bad (inconsistent style)\nfunction calculateTotal(items) {\n return items.reduce((sum, item) => sum + item.price, 0)\n}\n\\`\\`\\`\n\n### Async/Await\n\nPrefer async/await over promise chains:\n\n\\`\\`\\`javascript\n// Good\nasync function fetchUserData(userId) {\n const user = await db.getUser(userId)\n const orders = await db.getOrders(user.id)\n return { user, orders }\n}\n\n// Bad\nfunction fetchUserData(userId) {\n return db.getUser(userId)\n .then(user => db.getOrders(user.id)\n .then(orders => ({ user, orders })))\n}\n\\`\\`\\`\n\n## Python\n\n### Import Organization\n\nOrder imports: standard library, third-party, local:\n\n\\`\\`\\`python\n# Good\nimport os\nimport sys\n\nimport numpy as np\nimport pandas as pd\n\nfrom app.models import User\nfrom app.utils import helper\n\n# Bad - mixed order\nfrom app.models import User\nimport numpy as np\nimport os\n\\`\\`\\`\n\n### Type Hints\n\nUse type hints for all function signatures:\n\n\\`\\`\\`python\n# Good\ndef calculate_average(numbers: list[float]) -> float:\n return sum(numbers) / len(numbers)\n\n# Bad\ndef calculate_average(numbers):\n return sum(numbers) / len(numbers)\n\\`\\`\\`\n\n## Additional Languages\n\nSee language-specific guides for:\n- Go: `references/go-style.md`\n- Rust: `references/rust-style.md`\n- Ruby: `references/ruby-style.md`\n```\n\n### hooks/hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Before modifying code, verify it meets our coding standards from the code-standards skill. Check formatting, naming conventions, and documentation. If standards aren't met, suggest improvements.\",\n \"timeout\": 30\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate-commit.sh\",\n \"timeout\": 45\n }\n ]\n }\n ]\n}\n```\n\n### hooks/scripts/validate-commit.sh\n\n```bash\n#!/bin/bash\n# Validate code quality before task completion\n\nset -e\n\n# Check if there are any uncommitted changes\nif [[ -z $(git status -s) ]]; then\n echo '{\"systemMessage\": \"No changes to validate. Task complete.\"}'\n exit 0\nfi\n\n# Run linter on changed files\nCHANGED_FILES=$(git diff --name-only --cached | grep -E '\\.(js|ts|py)$' || true)\n\nif [[ -z \"$CHANGED_FILES\" ]]; then\n echo '{\"systemMessage\": \"No code files changed. Validation passed.\"}'\n exit 0\nfi\n\n# Run appropriate linters\nISSUES=0\n\nfor file in $CHANGED_FILES; do\n case \"$file\" in\n *.js|*.ts)\n if ! npx eslint \"$file\" --quiet; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n *.py)\n if ! python -m pylint \"$file\" --errors-only; then\n ISSUES=$((ISSUES + 1))\n fi\n ;;\n esac\ndone\n\nif [[ $ISSUES -gt 0 ]]; then\n echo \"{\\\"systemMessage\\\": \\\"Found $ISSUES code quality issues. Please fix before completing.\\\"}\"\n exit 1\nfi\n\necho '{\"systemMessage\": \"Code quality checks passed. Ready to commit.\"}'\nexit 0\n```\n\n## Usage Examples\n\n### Running Commands\n\n```\n$ claude\n> /lint\nRunning linter checks...\n\nCritical Issues (2):\n src/api/users.js:45 - SQL injection vulnerability\n src/utils/helpers.js:12 - Unhandled promise rejection\n\nWarnings (5):\n src/components/Button.tsx:23 - Missing PropTypes\n ...\n\nStyle Suggestions (8):\n src/index.js:1 - Use const instead of let\n ...\n\n> /test\nRunning test suite...\n\nTest Results:\n ✓ 245 passed\n ✗ 3 failed\n ○ 2 skipped\n\nCoverage: 87.3%\n\nUntested Files:\n src/utils/cache.js - 0% coverage\n src/api/webhooks.js - 23% coverage\n\nFailed Tests:\n 1. User API › GET /users › should handle pagination\n Expected 200, received 500\n ...\n```\n\n### Using Agents\n\n```\n> Review the changes in src/api/users.js\n\n[code-reviewer agent selected automatically]\n\nCode Review: src/api/users.js\n\nCritical Issues:\n 1. Line 45: SQL injection vulnerability\n - Using string concatenation for SQL query\n - Replace with parameterized query\n - Priority: CRITICAL\n\n 2. Line 67: Missing error handling\n - Database query without try/catch\n - Could crash server on DB error\n - Priority: HIGH\n\nSuggestions:\n 1. Line 23: Consider caching user data\n - Frequent DB queries for same users\n - Add Redis caching layer\n - Priority: MEDIUM\n```\n\n## Key Points\n\n1. **Complete manifest**: All recommended metadata fields\n2. **Multiple components**: Commands, agents, skills, hooks\n3. **Rich skills**: References and examples for detailed information\n4. **Automation**: Hooks enforce standards automatically\n5. **Integration**: Components work together cohesively\n\n## When to Use This Pattern\n\n- Production plugins for distribution\n- Team collaboration tools\n- Plugins requiring consistency enforcement\n- Complex workflows with multiple entry points\n","isInternal":false,"tokens":3106,"sizeBytes":13310},{"name":"component-patterns.md","path":"plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Component Organization Patterns\n\nAdvanced patterns for organizing plugin components effectively.\n\n## Component Lifecycle\n\n### Discovery Phase\n\nWhen Claude Code starts:\n\n1. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each\n2. **Discover components**: Look in default and custom paths\n3. **Parse definitions**: Read YAML frontmatter and configurations\n4. **Register components**: Make available to Claude Code\n5. **Initialize**: Start MCP servers, register hooks\n\n**Timing**: Component registration happens during Claude Code initialization, not continuously.\n\n### Activation Phase\n\nWhen components are used:\n\n**Commands**: User types slash command → Claude Code looks up → Executes\n**Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent\n**Skills**: Task context matches description → Claude Code loads skill\n**Hooks**: Event occurs → Claude Code calls matching hooks\n**MCP Servers**: Tool call matches server capability → Forwards to server\n\n## Command Organization Patterns\n\n### Flat Structure\n\nSingle directory with all commands:\n\n```\ncommands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**When to use**:\n- 5-15 commands total\n- All commands at same abstraction level\n- No clear categorization\n\n**Advantages**:\n- Simple, easy to navigate\n- No configuration needed\n- Fast discovery\n\n### Categorized Structure\n\nMultiple directories for different command types:\n\n```\ncommands/ # Core commands\n├── build.md\n└── test.md\n\nadmin-commands/ # Administrative\n├── configure.md\n└── manage.md\n\nworkflow-commands/ # Workflow automation\n├── review.md\n└── deploy.md\n```\n\n**Manifest configuration**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./workflow-commands\"\n ]\n}\n```\n\n**When to use**:\n- 15+ commands\n- Clear functional categories\n- Different permission levels\n\n**Advantages**:\n- Organized by purpose\n- Easier to maintain\n- Can restrict access by directory\n\n### Hierarchical Structure\n\nNested organization for complex plugins:\n\n```\ncommands/\n├── ci/\n│ ├── build.md\n│ ├── test.md\n│ └── lint.md\n├── deployment/\n│ ├── staging.md\n│ └── production.md\n└── management/\n ├── config.md\n └── status.md\n```\n\n**Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths:\n\n```json\n{\n \"commands\": [\n \"./commands/ci\",\n \"./commands/deployment\",\n \"./commands/management\"\n ]\n}\n```\n\n**When to use**:\n- 20+ commands\n- Multi-level categorization\n- Complex workflows\n\n**Advantages**:\n- Maximum organization\n- Clear boundaries\n- Scalable structure\n\n## Agent Organization Patterns\n\n### Role-Based Organization\n\nOrganize agents by their primary role:\n\n```\nagents/\n├── code-reviewer.md # Reviews code\n├── test-generator.md # Generates tests\n├── documentation-writer.md # Writes docs\n└── refactorer.md # Refactors code\n```\n\n**When to use**:\n- Agents have distinct, non-overlapping roles\n- Users invoke agents manually\n- Clear agent responsibilities\n\n### Capability-Based Organization\n\nOrganize by specific capabilities:\n\n```\nagents/\n├── python-expert.md # Python-specific\n├── typescript-expert.md # TypeScript-specific\n├── api-specialist.md # API design\n└── database-specialist.md # Database work\n```\n\n**When to use**:\n- Technology-specific agents\n- Domain expertise focus\n- Automatic agent selection\n\n### Workflow-Based Organization\n\nOrganize by workflow stage:\n\n```\nagents/\n├── planning-agent.md # Planning phase\n├── implementation-agent.md # Coding phase\n├── testing-agent.md # Testing phase\n└── deployment-agent.md # Deployment phase\n```\n\n**When to use**:\n- Sequential workflows\n- Stage-specific expertise\n- Pipeline automation\n\n## Skill Organization Patterns\n\n### Topic-Based Organization\n\nEach skill covers a specific topic:\n\n```\nskills/\n├── api-design/\n│ └── SKILL.md\n├── error-handling/\n│ └── SKILL.md\n├── testing-strategies/\n│ └── SKILL.md\n└── performance-optimization/\n └── SKILL.md\n```\n\n**When to use**:\n- Knowledge-based skills\n- Educational or reference content\n- Broad applicability\n\n### Tool-Based Organization\n\nSkills for specific tools or technologies:\n\n```\nskills/\n├── docker/\n│ ├── SKILL.md\n│ └── references/\n│ └── dockerfile-best-practices.md\n├── kubernetes/\n│ ├── SKILL.md\n│ └── examples/\n│ └── deployment.yaml\n└── terraform/\n ├── SKILL.md\n └── scripts/\n └── validate-config.sh\n```\n\n**When to use**:\n- Tool-specific expertise\n- Complex tool configurations\n- Tool best practices\n\n### Workflow-Based Organization\n\nSkills for complete workflows:\n\n```\nskills/\n├── code-review-workflow/\n│ ├── SKILL.md\n│ └── references/\n│ ├── checklist.md\n│ └── standards.md\n├── deployment-workflow/\n│ ├── SKILL.md\n│ └── scripts/\n│ ├── pre-deploy.sh\n│ └── post-deploy.sh\n└── testing-workflow/\n ├── SKILL.md\n └── examples/\n └── test-structure.md\n```\n\n**When to use**:\n- Multi-step processes\n- Company-specific workflows\n- Process automation\n\n### Skill with Rich Resources\n\nComprehensive skill with all resource types:\n\n```\nskills/\n└── api-testing/\n ├── SKILL.md # Core skill (1500 words)\n ├── references/\n │ ├── rest-api-guide.md\n │ ├── graphql-guide.md\n │ └── authentication.md\n ├── examples/\n │ ├── basic-test.js\n │ ├── authenticated-test.js\n │ └── integration-test.js\n ├── scripts/\n │ ├── run-tests.sh\n │ └── generate-report.py\n └── assets/\n └── test-template.json\n```\n\n**Resource usage**:\n- **SKILL.md**: Overview and when to use resources\n- **references/**: Detailed guides (loaded as needed)\n- **examples/**: Copy-paste code samples\n- **scripts/**: Executable test runners\n- **assets/**: Templates and configurations\n\n## Hook Organization Patterns\n\n### Monolithic Configuration\n\nSingle hooks.json with all hooks:\n\n```\nhooks/\n├── hooks.json # All hook definitions\n└── scripts/\n ├── validate-write.sh\n ├── validate-bash.sh\n └── load-context.sh\n```\n\n**hooks.json**:\n```json\n{\n \"PreToolUse\": [...],\n \"PostToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**When to use**:\n- 5-10 hooks total\n- Simple hook logic\n- Centralized configuration\n\n### Event-Based Organization\n\nSeparate files per event type:\n\n```\nhooks/\n├── hooks.json # Combines all\n├── pre-tool-use.json # PreToolUse hooks\n├── post-tool-use.json # PostToolUse hooks\n├── stop.json # Stop hooks\n└── scripts/\n ├── validate/\n │ ├── write.sh\n │ └── bash.sh\n └── context/\n └── load.sh\n```\n\n**hooks.json** (combines):\n```json\n{\n \"PreToolUse\": ${file:./pre-tool-use.json},\n \"PostToolUse\": ${file:./post-tool-use.json},\n \"Stop\": ${file:./stop.json}\n}\n```\n\n**Note**: Use build script to combine files, Claude Code doesn't support file references.\n\n**When to use**:\n- 10+ hooks\n- Different teams managing different events\n- Complex hook configurations\n\n### Purpose-Based Organization\n\nGroup by functional purpose:\n\n```\nhooks/\n├── hooks.json\n└── scripts/\n ├── security/\n │ ├── validate-paths.sh\n │ ├── check-credentials.sh\n │ └── scan-malware.sh\n ├── quality/\n │ ├── lint-code.sh\n │ ├── check-tests.sh\n │ └── verify-docs.sh\n └── workflow/\n ├── notify-team.sh\n └── update-status.sh\n```\n\n**When to use**:\n- Many hook scripts\n- Clear functional boundaries\n- Team specialization\n\n## Script Organization Patterns\n\n### Flat Scripts\n\nAll scripts in single directory:\n\n```\nscripts/\n├── build.sh\n├── test.py\n├── deploy.sh\n├── validate.js\n└── report.py\n```\n\n**When to use**:\n- 5-10 scripts\n- All scripts related\n- Simple plugin\n\n### Categorized Scripts\n\nGroup by purpose:\n\n```\nscripts/\n├── build/\n│ ├── compile.sh\n│ └── package.sh\n├── test/\n│ ├── run-unit.sh\n│ └── run-integration.sh\n├── deploy/\n│ ├── staging.sh\n│ └── production.sh\n└── utils/\n ├── log.sh\n └── notify.sh\n```\n\n**When to use**:\n- 10+ scripts\n- Clear categories\n- Reusable utilities\n\n### Language-Based Organization\n\nGroup by programming language:\n\n```\nscripts/\n├── bash/\n│ ├── build.sh\n│ └── deploy.sh\n├── python/\n│ ├── analyze.py\n│ └── report.py\n└── javascript/\n ├── bundle.js\n └── optimize.js\n```\n\n**When to use**:\n- Multi-language scripts\n- Different runtime requirements\n- Language-specific dependencies\n\n## Cross-Component Patterns\n\n### Shared Resources\n\nComponents sharing common resources:\n\n```\nplugin/\n├── commands/\n│ ├── test.md # Uses lib/test-utils.sh\n│ └── deploy.md # Uses lib/deploy-utils.sh\n├── agents/\n│ └── tester.md # References lib/test-utils.sh\n├── hooks/\n│ └── scripts/\n│ └── pre-test.sh # Sources lib/test-utils.sh\n└── lib/\n ├── test-utils.sh\n └── deploy-utils.sh\n```\n\n**Usage in components**:\n```bash\n#!/bin/bash\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh\"\nrun_tests\n```\n\n**Benefits**:\n- Code reuse\n- Consistent behavior\n- Easier maintenance\n\n### Layered Architecture\n\nSeparate concerns into layers:\n\n```\nplugin/\n├── commands/ # User interface layer\n├── agents/ # Orchestration layer\n├── skills/ # Knowledge layer\n└── lib/\n ├── core/ # Core business logic\n ├── integrations/ # External services\n └── utils/ # Helper functions\n```\n\n**When to use**:\n- Large plugins (100+ files)\n- Multiple developers\n- Clear separation of concerns\n\n### Plugin Within Plugin\n\nNested plugin structure:\n\n```\nplugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── core/ # Core functionality\n│ ├── commands/\n│ └── agents/\n└── extensions/ # Optional extensions\n ├── extension-a/\n │ ├── commands/\n │ └── agents/\n └── extension-b/\n ├── commands/\n └── agents/\n```\n\n**Manifest**:\n```json\n{\n \"commands\": [\n \"./core/commands\",\n \"./extensions/extension-a/commands\",\n \"./extensions/extension-b/commands\"\n ]\n}\n```\n\n**When to use**:\n- Modular functionality\n- Optional features\n- Plugin families\n\n## Best Practices\n\n### Naming\n\n1. **Consistent naming**: Match file names to component purpose\n2. **Descriptive names**: Indicate what component does\n3. **Avoid abbreviations**: Use full words for clarity\n\n### Organization\n\n1. **Start simple**: Use flat structure, reorganize when needed\n2. **Group related items**: Keep related components together\n3. **Separate concerns**: Don't mix unrelated functionality\n\n### Scalability\n\n1. **Plan for growth**: Choose structure that scales\n2. **Refactor early**: Reorganize before it becomes painful\n3. **Document structure**: Explain organization in README\n\n### Maintainability\n\n1. **Consistent patterns**: Use same structure throughout\n2. **Minimize nesting**: Keep directory depth manageable\n3. **Use conventions**: Follow community standards\n\n### Performance\n\n1. **Avoid deep nesting**: Impacts discovery time\n2. **Minimize custom paths**: Use defaults when possible\n3. **Keep configurations small**: Large configs slow loading\n","isInternal":false,"tokens":2829,"sizeBytes":12086},{"name":"manifest-reference.md","path":"plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Plugin Manifest Reference\n\nComplete reference for `plugin.json` configuration.\n\n## File Location\n\n**Required path**: `.claude-plugin/plugin.json`\n\nThe manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location.\n\n## Complete Field Reference\n\n### Core Fields\n\n#### name (required)\n\n**Type**: String\n**Format**: kebab-case\n**Example**: `\"test-automation-suite\"`\n\nThe unique identifier for the plugin. Used for:\n- Plugin identification in Claude Code\n- Conflict detection with other plugins\n- Command namespacing (optional)\n\n**Requirements**:\n- Must be unique across all installed plugins\n- Use only lowercase letters, numbers, and hyphens\n- No spaces or special characters\n- Start with a letter\n- End with a letter or number\n\n**Validation**:\n```javascript\n/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/\n```\n\n**Examples**:\n- ✅ Good: `api-tester`, `code-review`, `git-workflow-automation`\n- ❌ Bad: `API Tester`, `code_review`, `-git-workflow`, `test-`\n\n#### version\n\n**Type**: String\n**Format**: Semantic versioning (MAJOR.MINOR.PATCH)\n**Example**: `\"2.1.0\"`\n**Default**: `\"0.1.0\"` if not specified\n\nSemantic versioning guidelines:\n- **MAJOR**: Incompatible API changes, breaking changes\n- **MINOR**: New functionality, backward-compatible\n- **PATCH**: Bug fixes, backward-compatible\n\n**Pre-release versions**:\n- `\"1.0.0-alpha.1\"` - Alpha release\n- `\"1.0.0-beta.2\"` - Beta release\n- `\"1.0.0-rc.1\"` - Release candidate\n\n**Examples**:\n- `\"0.1.0\"` - Initial development\n- `\"1.0.0\"` - First stable release\n- `\"1.2.3\"` - Patch update to 1.2\n- `\"2.0.0\"` - Major version with breaking changes\n\n#### description\n\n**Type**: String\n**Length**: 50-200 characters recommended\n**Example**: `\"Automates code review workflows with style checks and automated feedback\"`\n\nBrief explanation of plugin purpose and functionality.\n\n**Best practices**:\n- Focus on what the plugin does, not how\n- Use active voice\n- Mention key features or benefits\n- Keep under 200 characters for marketplace display\n\n**Examples**:\n- ✅ \"Generates comprehensive test suites from code analysis and coverage reports\"\n- ✅ \"Integrates with Jira for automatic issue tracking and sprint management\"\n- ❌ \"A plugin that helps you do testing stuff\"\n- ❌ \"This is a very long description that goes on and on about every single feature...\"\n\n### Metadata Fields\n\n#### author\n\n**Type**: Object\n**Fields**: name (required), email (optional), url (optional)\n\n```json\n{\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"jane@example.com\",\n \"url\": \"https://janedeveloper.com\"\n }\n}\n```\n\n**Alternative format** (string only):\n```json\n{\n \"author\": \"Jane Developer (https://janedeveloper.com)\"\n}\n```\n\n**Use cases**:\n- Credit and attribution\n- Contact for support or questions\n- Marketplace display\n- Community recognition\n\n#### homepage\n\n**Type**: String (URL)\n**Example**: `\"https://docs.example.com/plugins/my-plugin\"`\n\nLink to plugin documentation or landing page.\n\n**Should point to**:\n- Plugin documentation site\n- Project homepage\n- Detailed usage guide\n- Installation instructions\n\n**Not for**:\n- Source code (use `repository` field)\n- Issue tracker (include in documentation)\n- Personal websites (use `author.url`)\n\n#### repository\n\n**Type**: String (URL) or Object\n**Example**: `\"https://github.com/user/plugin-name\"`\n\nSource code repository location.\n\n**String format**:\n```json\n{\n \"repository\": \"https://github.com/user/plugin-name\"\n}\n```\n\n**Object format** (detailed):\n```json\n{\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/user/plugin-name.git\",\n \"directory\": \"packages/plugin-name\"\n }\n}\n```\n\n**Use cases**:\n- Source code access\n- Issue reporting\n- Community contributions\n- Transparency and trust\n\n#### license\n\n**Type**: String\n**Format**: SPDX identifier\n**Example**: `\"MIT\"`\n\nSoftware license identifier.\n\n**Common licenses**:\n- `\"MIT\"` - Permissive, popular choice\n- `\"Apache-2.0\"` - Permissive with patent grant\n- `\"GPL-3.0\"` - Copyleft\n- `\"BSD-3-Clause\"` - Permissive\n- `\"ISC\"` - Permissive, similar to MIT\n- `\"UNLICENSED\"` - Proprietary, not open source\n\n**Full list**: https://spdx.org/licenses/\n\n**Multiple licenses**:\n```json\n{\n \"license\": \"(MIT OR Apache-2.0)\"\n}\n```\n\n#### keywords\n\n**Type**: Array of strings\n**Example**: `[\"testing\", \"automation\", \"ci-cd\", \"quality-assurance\"]`\n\nTags for plugin discovery and categorization.\n\n**Best practices**:\n- Use 5-10 keywords\n- Include functionality categories\n- Add technology names\n- Use common search terms\n- Avoid duplicating plugin name\n\n**Categories to consider**:\n- Functionality: `testing`, `debugging`, `documentation`, `deployment`\n- Technologies: `typescript`, `python`, `docker`, `aws`\n- Workflows: `ci-cd`, `code-review`, `git-workflow`\n- Domains: `web-development`, `data-science`, `devops`\n\n### Component Path Fields\n\n#### commands\n\n**Type**: String or Array of strings\n**Default**: `[\"./commands\"]`\n**Example**: `\"./cli-commands\"`\n\nAdditional directories or files containing command definitions.\n\n**Single path**:\n```json\n{\n \"commands\": \"./custom-commands\"\n}\n```\n\n**Multiple paths**:\n```json\n{\n \"commands\": [\n \"./commands\",\n \"./admin-commands\",\n \"./experimental-commands\"\n ]\n}\n```\n\n**Behavior**: Supplements default `commands/` directory (does not replace)\n\n**Use cases**:\n- Organizing commands by category\n- Separating stable from experimental commands\n- Loading commands from shared locations\n\n#### agents\n\n**Type**: String or Array of strings\n**Default**: `[\"./agents\"]`\n**Example**: `\"./specialized-agents\"`\n\nAdditional directories or files containing agent definitions.\n\n**Format**: Same as `commands` field\n\n**Use cases**:\n- Grouping agents by specialization\n- Separating general-purpose from task-specific agents\n- Loading agents from plugin dependencies\n\n#### hooks\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `\"./hooks/hooks.json\"`\n\nHook configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"hooks\": \"./config/hooks.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 30\n }\n ]\n }\n ]\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Inline configuration (< 50 lines)\n- Complex plugins: External JSON file\n- Multiple hook sets: Separate files for different contexts\n\n#### mcpServers\n\n**Type**: String (path to JSON file) or Object (inline configuration)\n**Default**: `./.mcp.json`\n\nMCP server configuration location or inline definition.\n\n**File path**:\n```json\n{\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Inline configuration**:\n```json\n{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\"\n }\n }\n }\n}\n```\n\n**Use cases**:\n- Simple plugins: Single inline server (< 20 lines)\n- Complex plugins: External `.mcp.json` file\n- Multiple servers: Always use external file\n\n## Path Resolution\n\n### Relative Path Rules\n\nAll paths in component fields must follow these rules:\n\n1. **Must be relative**: No absolute paths\n2. **Must start with `./`**: Indicates relative to plugin root\n3. **Cannot use `../`**: No parent directory navigation\n4. **Forward slashes only**: Even on Windows\n\n**Examples**:\n- ✅ `\"./commands\"`\n- ✅ `\"./src/commands\"`\n- ✅ `\"./configs/hooks.json\"`\n- ❌ `\"/Users/name/plugin/commands\"`\n- ❌ `\"commands\"` (missing `./`)\n- ❌ `\"../shared/commands\"`\n- ❌ `\".\\\\commands\"` (backslash)\n\n### Resolution Order\n\nWhen Claude Code loads components:\n\n1. **Default directories**: Scans standard locations first\n - `./commands/`\n - `./agents/`\n - `./skills/`\n - `./hooks/hooks.json`\n - `./.mcp.json`\n\n2. **Custom paths**: Scans paths specified in manifest\n - Paths from `commands` field\n - Paths from `agents` field\n - Files from `hooks` and `mcpServers` fields\n\n3. **Merge behavior**: Components from all locations load\n - No overwriting\n - All discovered components register\n - Name conflicts cause errors\n\n## Validation\n\n### Manifest Validation\n\nClaude Code validates the manifest on plugin load:\n\n**Syntax validation**:\n- Valid JSON format\n- No syntax errors\n- Correct field types\n\n**Field validation**:\n- `name` field present and valid format\n- `version` follows semantic versioning (if present)\n- Paths are relative with `./` prefix\n- URLs are valid (if present)\n\n**Component validation**:\n- Referenced paths exist\n- Hook and MCP configurations are valid\n- No circular dependencies\n\n### Common Validation Errors\n\n**Invalid name format**:\n```json\n{\n \"name\": \"My Plugin\" // ❌ Contains spaces\n}\n```\nFix: Use kebab-case\n```json\n{\n \"name\": \"my-plugin\" // ✅\n}\n```\n\n**Absolute path**:\n```json\n{\n \"commands\": \"/Users/name/commands\" // ❌ Absolute path\n}\n```\nFix: Use relative path\n```json\n{\n \"commands\": \"./commands\" // ✅\n}\n```\n\n**Missing ./ prefix**:\n```json\n{\n \"hooks\": \"hooks/hooks.json\" // ❌ No ./\n}\n```\nFix: Add ./ prefix\n```json\n{\n \"hooks\": \"./hooks/hooks.json\" // ✅\n}\n```\n\n**Invalid version**:\n```json\n{\n \"version\": \"1.0\" // ❌ Not semantic versioning\n}\n```\nFix: Use MAJOR.MINOR.PATCH\n```json\n{\n \"version\": \"1.0.0\" // ✅\n}\n```\n\n## Minimal vs. Complete Examples\n\n### Minimal Plugin\n\nBare minimum for a working plugin:\n\n```json\n{\n \"name\": \"hello-world\"\n}\n```\n\nRelies entirely on default directory discovery.\n\n### Recommended Plugin\n\nGood metadata for distribution:\n\n```json\n{\n \"name\": \"code-review-assistant\",\n \"version\": \"1.0.0\",\n \"description\": \"Automates code review with style checks and suggestions\",\n \"author\": {\n \"name\": \"Jane Developer\",\n \"email\": \"jane@example.com\"\n },\n \"homepage\": \"https://docs.example.com/code-review\",\n \"repository\": \"https://github.com/janedev/code-review-assistant\",\n \"license\": \"MIT\",\n \"keywords\": [\"code-review\", \"automation\", \"quality\", \"ci-cd\"]\n}\n```\n\n### Complete Plugin\n\nFull configuration with all features:\n\n```json\n{\n \"name\": \"enterprise-devops\",\n \"version\": \"2.3.1\",\n \"description\": \"Comprehensive DevOps automation for enterprise CI/CD pipelines\",\n \"author\": {\n \"name\": \"DevOps Team\",\n \"email\": \"devops@company.com\",\n \"url\": \"https://company.com/devops\"\n },\n \"homepage\": \"https://docs.company.com/plugins/devops\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/company/devops-plugin.git\"\n },\n \"license\": \"Apache-2.0\",\n \"keywords\": [\n \"devops\",\n \"ci-cd\",\n \"automation\",\n \"kubernetes\",\n \"docker\",\n \"deployment\"\n ],\n \"commands\": [\n \"./commands\",\n \"./admin-commands\"\n ],\n \"agents\": \"./specialized-agents\",\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n## Best Practices\n\n### Metadata\n\n1. **Always include version**: Track changes and updates\n2. **Write clear descriptions**: Help users understand plugin purpose\n3. **Provide contact information**: Enable user support\n4. **Link to documentation**: Reduce support burden\n5. **Choose appropriate license**: Match project goals\n\n### Paths\n\n1. **Use defaults when possible**: Minimize configuration\n2. **Organize logically**: Group related components\n3. **Document custom paths**: Explain why non-standard layout used\n4. **Test path resolution**: Verify on multiple systems\n\n### Maintenance\n\n1. **Bump version on changes**: Follow semantic versioning\n2. **Update keywords**: Reflect new functionality\n3. **Keep description current**: Match actual capabilities\n4. **Maintain changelog**: Track version history\n5. **Update repository links**: Keep URLs current\n\n### Distribution\n\n1. **Complete metadata before publishing**: All fields filled\n2. **Test on clean install**: Verify plugin works without dev environment\n3. **Validate manifest**: Use validation tools\n4. **Include README**: Document installation and usage\n5. **Specify license file**: Include LICENSE file in plugin root\n","isInternal":false,"tokens":3074,"sizeBytes":12061},{"name":"SKILL.md","path":"plugins/plugin-dev/skills/plugin-structure/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-structure/SKILL.md","title":"Plugin Structure","category":"anthropic-skill","format":"markdown","content":"---\nname: Plugin Structure\ndescription: This skill should be used when the user asks to \"create a plugin\", \"scaffold a plugin\", \"understand plugin structure\", \"organize plugin components\", \"set up plugin.json\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"add commands/agents/skills/hooks\", \"configure auto-discovery\", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.\nversion: 0.1.0\n---\n\n# Plugin Structure for Claude Code\n\n## Overview\n\nClaude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.\n\n**Key concepts:**\n- Conventional directory layout for automatic discovery\n- Manifest-driven configuration in `.claude-plugin/plugin.json`\n- Component-based organization (commands, agents, skills, hooks)\n- Portable path references using `${CLAUDE_PLUGIN_ROOT}`\n- Explicit vs. auto-discovered component loading\n\n## Directory Structure\n\nEvery Claude Code plugin follows this organizational pattern:\n\n```\nplugin-name/\n├── .claude-plugin/\n│ └── plugin.json # Required: Plugin manifest\n├── commands/ # Slash commands (.md files)\n├── agents/ # Subagent definitions (.md files)\n├── skills/ # Agent skills (subdirectories)\n│ └── skill-name/\n│ └── SKILL.md # Required for each skill\n├── hooks/\n│ └── hooks.json # Event handler configuration\n├── .mcp.json # MCP server definitions\n└── scripts/ # Helper scripts and utilities\n```\n\n**Critical rules:**\n\n1. **Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory\n2. **Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`\n3. **Optional components**: Only create directories for components the plugin actually uses\n4. **Naming convention**: Use kebab-case for all directory and file names\n\n## Plugin Manifest (plugin.json)\n\nThe manifest defines plugin metadata and configuration. Located at `.claude-plugin/plugin.json`:\n\n### Required Fields\n\n```json\n{\n \"name\": \"plugin-name\"\n}\n```\n\n**Name requirements:**\n- Use kebab-case format (lowercase with hyphens)\n- Must be unique across installed plugins\n- No spaces or special characters\n- Example: `code-review-assistant`, `test-runner`, `api-docs`\n\n### Recommended Metadata\n\n```json\n{\n \"name\": \"plugin-name\",\n \"version\": \"1.0.0\",\n \"description\": \"Brief explanation of plugin purpose\",\n \"author\": {\n \"name\": \"Author Name\",\n \"email\": \"author@example.com\",\n \"url\": \"https://example.com\"\n },\n \"homepage\": \"https://docs.example.com\",\n \"repository\": \"https://github.com/user/plugin-name\",\n \"license\": \"MIT\",\n \"keywords\": [\"testing\", \"automation\", \"ci-cd\"]\n}\n```\n\n**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)\n**Keywords**: Use for plugin discovery and categorization\n\n### Component Path Configuration\n\nSpecify custom paths for components (supplements default directories):\n\n```json\n{\n \"name\": \"plugin-name\",\n \"commands\": \"./custom-commands\",\n \"agents\": [\"./agents\", \"./specialized-agents\"],\n \"hooks\": \"./config/hooks.json\",\n \"mcpServers\": \"./.mcp.json\"\n}\n```\n\n**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.\n\n**Path rules:**\n- Must be relative to plugin root\n- Must start with `./`\n- Cannot use absolute paths\n- Support arrays for multiple locations\n\n## Component Organization\n\n### Commands\n\n**Location**: `commands/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `commands/` load automatically\n\n**Example structure**:\n```\ncommands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**File format**:\n```markdown\n---\nname: command-name\ndescription: Command description\n---\n\nCommand implementation instructions...\n```\n\n**Usage**: Commands integrate as native slash commands in Claude Code\n\n### Agents\n\n**Location**: `agents/` directory\n**Format**: Markdown files with YAML frontmatter\n**Auto-discovery**: All `.md` files in `agents/` load automatically\n\n**Example structure**:\n```\nagents/\n├── code-reviewer.md\n├── test-generator.md\n└── refactorer.md\n```\n\n**File format**:\n```markdown\n---\ndescription: Agent role and expertise\ncapabilities:\n - Specific task 1\n - Specific task 2\n---\n\nDetailed agent instructions and knowledge...\n```\n\n**Usage**: Users can invoke agents manually, or Claude Code selects them automatically based on task context\n\n### Skills\n\n**Location**: `skills/` directory with subdirectories per skill\n**Format**: Each skill in its own directory with `SKILL.md` file\n**Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically\n\n**Example structure**:\n```\nskills/\n├── api-testing/\n│ ├── SKILL.md\n│ ├── scripts/\n│ │ └── test-runner.py\n│ └── references/\n│ └── api-spec.md\n└── database-migrations/\n ├── SKILL.md\n └── examples/\n └── migration-template.sql\n```\n\n**SKILL.md format**:\n```markdown\n---\nname: Skill Name\ndescription: When to use this skill\nversion: 1.0.0\n---\n\nSkill instructions and guidance...\n```\n\n**Supporting files**: Skills can include scripts, references, examples, or assets in subdirectories\n\n**Usage**: Claude Code autonomously activates skills based on task context matching the description\n\n### Hooks\n\n**Location**: `hooks/hooks.json` or inline in `plugin.json`\n**Format**: JSON configuration defining event handlers\n**Registration**: Hooks register automatically when plugin enables\n\n**Example structure**:\n```\nhooks/\n├── hooks.json # Hook configuration\n└── scripts/\n ├── validate.sh # Hook script\n └── check-style.sh # Hook script\n```\n\n**Configuration format**:\n```json\n{\n \"PreToolUse\": [{\n \"matcher\": \"Write|Edit\",\n \"hooks\": [{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh\",\n \"timeout\": 30\n }]\n }]\n}\n```\n\n**Available events**: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification\n\n**Usage**: Hooks execute automatically in response to Claude Code events\n\n### MCP Servers\n\n**Location**: `.mcp.json` at plugin root or inline in `plugin.json`\n**Format**: JSON configuration for MCP server definitions\n**Auto-start**: Servers start automatically when plugin enables\n\n**Example format**:\n```json\n{\n \"mcpServers\": {\n \"server-name\": {\n \"command\": \"node\",\n \"args\": [\"${CLAUDE_PLUGIN_ROOT}/servers/server.js\"],\n \"env\": {\n \"API_KEY\": \"${API_KEY}\"\n }\n }\n }\n}\n```\n\n**Usage**: MCP servers integrate seamlessly with Claude Code's tool system\n\n## Portable Path References\n\n### ${CLAUDE_PLUGIN_ROOT}\n\nUse `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path references:\n\n```json\n{\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh\"\n}\n```\n\n**Why it matters**: Plugins install in different locations depending on:\n- User installation method (marketplace, local, npm)\n- Operating system conventions\n- User preferences\n\n**Where to use it**:\n- Hook command paths\n- MCP server command arguments\n- Script execution references\n- Resource file paths\n\n**Never use**:\n- Hardcoded absolute paths (`/Users/name/plugins/...`)\n- Relative paths from working directory (`./scripts/...` in commands)\n- Home directory shortcuts (`~/plugins/...`)\n\n### Path Resolution Rules\n\n**In manifest JSON fields** (hooks, MCP servers):\n```json\n\"command\": \"${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh\"\n```\n\n**In component files** (commands, agents, skills):\n```markdown\nReference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py\n```\n\n**In executed scripts**:\n```bash\n#!/bin/bash\n# ${CLAUDE_PLUGIN_ROOT} available as environment variable\nsource \"${CLAUDE_PLUGIN_ROOT}/lib/common.sh\"\n```\n\n## File Naming Conventions\n\n### Component Files\n\n**Commands**: Use kebab-case `.md` files\n- `code-review.md` → `/code-review`\n- `run-tests.md` → `/run-tests`\n- `api-docs.md` → `/api-docs`\n\n**Agents**: Use kebab-case `.md` files describing role\n- `test-generator.md`\n- `code-reviewer.md`\n- `performance-analyzer.md`\n\n**Skills**: Use kebab-case directory names\n- `api-testing/`\n- `database-migrations/`\n- `error-handling/`\n\n### Supporting Files\n\n**Scripts**: Use descriptive kebab-case names with appropriate extensions\n- `validate-input.sh`\n- `generate-report.py`\n- `process-data.js`\n\n**Documentation**: Use kebab-case markdown files\n- `api-reference.md`\n- `migration-guide.md`\n- `best-practices.md`\n\n**Configuration**: Use standard names\n- `hooks.json`\n- `.mcp.json`\n- `plugin.json`\n\n## Auto-Discovery Mechanism\n\nClaude Code automatically discovers and loads components:\n\n1. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables\n2. **Commands**: Scans `commands/` directory for `.md` files\n3. **Agents**: Scans `agents/` directory for `.md` files\n4. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`\n5. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest\n6. **MCP servers**: Loads configuration from `.mcp.json` or manifest\n\n**Discovery timing**:\n- Plugin installation: Components register with Claude Code\n- Plugin enable: Components become available for use\n- No restart required: Changes take effect on next Claude Code session\n\n**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories\n\n## Best Practices\n\n### Organization\n\n1. **Logical grouping**: Group related components together\n - Put test-related commands, agents, and skills together\n - Create subdirectories in `scripts/` for different purposes\n\n2. **Minimal manifest**: Keep `plugin.json` lean\n - Only specify custom paths when necessary\n - Rely on auto-discovery for standard layouts\n - Use inline configuration only for simple cases\n\n3. **Documentation**: Include README files\n - Plugin root: Overall purpose and usage\n - Component directories: Specific guidance\n - Script directories: Usage and requirements\n\n### Naming\n\n1. **Consistency**: Use consistent naming across components\n - If command is `test-runner`, name related agent `test-runner-agent`\n - Match skill directory names to their purpose\n\n2. **Clarity**: Use descriptive names that indicate purpose\n - Good: `api-integration-testing/`, `code-quality-checker.md`\n - Avoid: `utils/`, `misc.md`, `temp.sh`\n\n3. **Length**: Balance brevity with clarity\n - Commands: 2-3 words (`review-pr`, `run-ci`)\n - Agents: Describe role clearly (`code-reviewer`, `test-generator`)\n - Skills: Topic-focused (`error-handling`, `api-design`)\n\n### Portability\n\n1. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths\n2. **Test on multiple systems**: Verify on macOS, Linux, Windows\n3. **Document dependencies**: List required tools and versions\n4. **Avoid system-specific features**: Use portable bash/Python constructs\n\n### Maintenance\n\n1. **Version consistently**: Update version in plugin.json for releases\n2. **Deprecate gracefully**: Mark old components clearly before removal\n3. **Document breaking changes**: Note changes affecting existing users\n4. **Test thoroughly**: Verify all components work after changes\n\n## Common Patterns\n\n### Minimal Plugin\n\nSingle command with no dependencies:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json # Just name field\n└── commands/\n └── hello.md # Single command\n```\n\n### Full-Featured Plugin\n\nComplete plugin with all component types:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/ # User-facing commands\n├── agents/ # Specialized subagents\n├── skills/ # Auto-activating skills\n├── hooks/ # Event handlers\n│ ├── hooks.json\n│ └── scripts/\n├── .mcp.json # External integrations\n└── scripts/ # Shared utilities\n```\n\n### Skill-Focused Plugin\n\nPlugin providing only skills:\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n└── skills/\n ├── skill-one/\n │ └── SKILL.md\n └── skill-two/\n └── SKILL.md\n```\n\n## Troubleshooting\n\n**Component not loading**:\n- Verify file is in correct directory with correct extension\n- Check YAML frontmatter syntax (commands, agents, skills)\n- Ensure skill has `SKILL.md` (not `README.md` or other name)\n- Confirm plugin is enabled in Claude Code settings\n\n**Path resolution errors**:\n- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`\n- Verify paths are relative and start with `./` in manifest\n- Check that referenced files exist at specified paths\n- Test with `echo $CLAUDE_PLUGIN_ROOT` in hook scripts\n\n**Auto-discovery not working**:\n- Confirm directories are at plugin root (not in `.claude-plugin/`)\n- Check file naming follows conventions (kebab-case, correct extensions)\n- Verify custom paths in manifest are correct\n- Restart Claude Code to reload plugin configuration\n\n**Conflicts between plugins**:\n- Use unique, descriptive component names\n- Namespace commands with plugin name if needed\n- Document potential conflicts in plugin README\n- Consider command prefixes for related functionality\n\n---\n\nFor detailed examples and advanced patterns, see files in `references/` and `examples/` directories.\n","frontmatter":{"name":"Plugin Structure","description":"This skill should be used when the user asks to \"create a plugin\", \"scaffold a plugin\", \"understand plugin structure\", \"organize plugin components\", \"set up plugin.json\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"add commands/agents/skills/hooks\", \"configure auto-discovery\", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.","version":"0.1.0"},"isInternal":false,"tokens":3172,"sizeBytes":13796},{"name":"skill-creator-original.md","path":"plugins/plugin-dev/skills/skill-development/references/skill-creator-original.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/skill-development/references/skill-creator-original.md","title":"skill-creator","category":"anthropic-skill","format":"markdown","content":"---\nname: skill-creator\ndescription: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.\nlicense: Complete terms in LICENSE.txt\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Claude's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Claude from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\n**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. \"This skill should be used when...\" instead of \"Use this skill when...\").\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.\n\n- **When to include**: For documentation that Claude should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Claude produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Claude (Unlimited*)\n\n*Unlimited because scripts can be executed without reading into context window.\n\n## Skill Creation Process\n\nTo create a skill, follow the \"Skill Creation Process\" in order, skipping steps only if there is a clear reason why they are not applicable.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.\n\nUsage:\n\n```bash\nscripts/init_skill.py --path \n```\n\nThe script:\n\n- Creates the skill directory at the specified path\n- Generates a SKILL.md template with proper frontmatter and TODO placeholders\n- Creates example resource directories: `scripts/`, `references/`, and `assets/`\n- Adds example files in each directory that can be customized or deleted\n\nAfter initialization, customize or remove the generated SKILL.md and example files as needed.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAlso, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.\n\n#### Update SKILL.md\n\n**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., \"To accomplish X, do Y\" rather than \"You should do X\" or \"If you need to do X\"). This maintains consistency and clarity for AI consumption.\n\nTo complete SKILL.md, answer the following questions:\n\n1. What is the purpose of the skill, in a few sentences?\n2. When should the skill be used?\n3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.\n\n### Step 5: Packaging a Skill\n\nOnce the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:\n\n```bash\nscripts/package_skill.py \n```\n\nOptional output directory specification:\n\n```bash\nscripts/package_skill.py ./dist\n```\n\nThe packaging script will:\n\n1. **Validate** the skill automatically, checking:\n - YAML frontmatter format and required fields\n - Skill naming conventions and directory structure\n - Description completeness and quality\n - File organization and resource references\n\n2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.\n\nIf validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n","frontmatter":{"name":"skill-creator","description":"Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.","license":"Complete terms in LICENSE.txt"},"isInternal":false,"tokens":2355,"sizeBytes":11547},{"name":"SKILL.md","path":"plugins/plugin-dev/skills/skill-development/SKILL.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/skill-development/SKILL.md","title":"Skill Development","category":"anthropic-skill","format":"markdown","content":"---\nname: Skill Development\ndescription: This skill should be used when the user wants to \"create a skill\", \"add a skill to plugin\", \"write a new skill\", \"improve skill description\", \"organize skill content\", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.\nversion: 0.1.0\n---\n\n# Skill Development for Claude Code Plugins\n\nThis skill provides guidance for creating effective skills for Claude Code plugins.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Claude's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Claude from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\n**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. \"This skill should be used when...\" instead of \"Use this skill when...\").\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.\n\n- **When to include**: For documentation that Claude should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Claude produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Claude (Unlimited*)\n\n*Unlimited because scripts can be executed without reading into context window.\n\n## Skill Creation Process\n\nTo create a skill, follow the \"Skill Creation Process\" in order, skipping steps only if there is a clear reason why they are not applicable.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\n**For Claude Code plugins:** When building a hooks skill, the analysis shows:\n1. Developers repeatedly need to validate hooks.json and test hook scripts\n2. `scripts/validate-hook-schema.sh` and `scripts/test-hook.sh` utilities would be helpful\n3. `references/patterns.md` for detailed hook patterns to avoid bloating SKILL.md\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Create Skill Structure\n\nFor Claude Code plugins, create the skill directory structure:\n\n```bash\nmkdir -p plugin-name/skills/skill-name/{references,examples,scripts}\ntouch plugin-name/skills/skill-name/SKILL.md\n```\n\n**Note:** Unlike the generic skill-creator which uses `init_skill.py`, plugin skills are created directly in the plugin's `skills/` directory with a simpler manual structure.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-created or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAlso, delete any example files and directories not needed for the skill. Create only the directories you actually need (references/, examples/, scripts/).\n\n#### Update SKILL.md\n\n**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., \"To accomplish X, do Y\" rather than \"You should do X\" or \"If you need to do X\"). This maintains consistency and clarity for AI consumption.\n\n**Description (Frontmatter):** Use third-person format with specific trigger phrases:\n\n```yaml\n---\nname: Skill Name\ndescription: This skill should be used when the user asks to \"specific phrase 1\", \"specific phrase 2\", \"specific phrase 3\". Include exact phrases users would say that should trigger this skill. Be concrete and specific.\nversion: 0.1.0\n---\n```\n\n**Good description examples:**\n```yaml\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse hook\", \"validate tool use\", \"implement prompt-based hooks\", or mentions hook events (PreToolUse, PostToolUse, Stop).\n```\n\n**Bad description examples:**\n```yaml\ndescription: Use this skill when working with hooks. # Wrong person, vague\ndescription: Load when user needs hook help. # Not third person\ndescription: Provides hook guidance. # No trigger phrases\n```\n\nTo complete SKILL.md body, answer the following questions:\n\n1. What is the purpose of the skill, in a few sentences?\n2. When should the skill be used? (Include this in frontmatter description with specific triggers)\n3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.\n\n**Keep SKILL.md lean:** Target 1,500-2,000 words for the body. Move detailed content to references/:\n- Detailed patterns → `references/patterns.md`\n- Advanced techniques → `references/advanced.md`\n- Migration guides → `references/migration.md`\n- API references → `references/api-reference.md`\n\n**Reference resources in SKILL.md:**\n```markdown\n## Additional Resources\n\n### Reference Files\n\nFor detailed patterns and techniques, consult:\n- **`references/patterns.md`** - Common patterns\n- **`references/advanced.md`** - Advanced use cases\n\n### Example Files\n\nWorking examples in `examples/`:\n- **`example-script.sh`** - Working example\n```\n\n### Step 5: Validate and Test\n\n**For plugin skills, validation is different from generic skills:**\n\n1. **Check structure**: Skill directory in `plugin-name/skills/skill-name/`\n2. **Validate SKILL.md**: Has frontmatter with name and description\n3. **Check trigger phrases**: Description includes specific user queries\n4. **Verify writing style**: Body uses imperative/infinitive form, not second person\n5. **Test progressive disclosure**: SKILL.md is lean (~1,500-2,000 words), detailed content in references/\n6. **Check references**: All referenced files exist\n7. **Validate examples**: Examples are complete and correct\n8. **Test scripts**: Scripts are executable and work correctly\n\n**Use the skill-reviewer agent:**\n```\nAsk: \"Review my skill and check if it follows best practices\"\n```\n\nThe skill-reviewer agent will check description quality, content organization, and progressive disclosure.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n\n**Common improvements:**\n- Strengthen trigger phrases in description\n- Move long sections from SKILL.md to references/\n- Add missing examples or scripts\n- Clarify ambiguous instructions\n- Add edge case handling\n\n## Plugin-Specific Considerations\n\n### Skill Location in Plugins\n\nPlugin skills live in the plugin's `skills/` directory:\n\n```\nmy-plugin/\n├── .claude-plugin/\n│ └── plugin.json\n├── commands/\n├── agents/\n└── skills/\n └── my-skill/\n ├── SKILL.md\n ├── references/\n ├── examples/\n └── scripts/\n```\n\n### Auto-Discovery\n\nClaude Code automatically discovers skills:\n- Scans `skills/` directory\n- Finds subdirectories containing `SKILL.md`\n- Loads skill metadata (name + description) always\n- Loads SKILL.md body when skill triggers\n- Loads references/examples when needed\n\n### No Packaging Needed\n\nPlugin skills are distributed as part of the plugin, not as separate ZIP files. Users get skills when they install the plugin.\n\n### Testing in Plugins\n\nTest skills by installing plugin locally:\n\n```bash\n# Test with --plugin-dir\ncc --plugin-dir /path/to/plugin\n\n# Ask questions that should trigger the skill\n# Verify skill loads correctly\n```\n\n## Examples from Plugin-Dev\n\nStudy the skills in this plugin as examples of best practices:\n\n**hook-development skill:**\n- Excellent trigger phrases: \"create a hook\", \"add a PreToolUse hook\", etc.\n- Lean SKILL.md (1,651 words)\n- 3 references/ files for detailed content\n- 3 examples/ of working hooks\n- 3 scripts/ utilities\n\n**agent-development skill:**\n- Strong triggers: \"create an agent\", \"agent frontmatter\", etc.\n- Focused SKILL.md (1,438 words)\n- References include the AI generation prompt from Claude Code\n- Complete agent examples\n\n**plugin-settings skill:**\n- Specific triggers: \"plugin settings\", \".local.md files\", \"YAML frontmatter\"\n- References show real implementations (multi-agent-swarm, ralph-wiggum)\n- Working parsing scripts\n\nEach demonstrates progressive disclosure and strong triggering.\n\n## Progressive Disclosure in Practice\n\n### What Goes in SKILL.md\n\n**Include (always loaded when skill triggers):**\n- Core concepts and overview\n- Essential procedures and workflows\n- Quick reference tables\n- Pointers to references/examples/scripts\n- Most common use cases\n\n**Keep under 3,000 words, ideally 1,500-2,000 words**\n\n### What Goes in references/\n\n**Move to references/ (loaded as needed):**\n- Detailed patterns and advanced techniques\n- Comprehensive API documentation\n- Migration guides\n- Edge cases and troubleshooting\n- Extensive examples and walkthroughs\n\n**Each reference file can be large (2,000-5,000+ words)**\n\n### What Goes in examples/\n\n**Working code examples:**\n- Complete, runnable scripts\n- Configuration files\n- Template files\n- Real-world usage examples\n\n**Users can copy and adapt these directly**\n\n### What Goes in scripts/\n\n**Utility scripts:**\n- Validation tools\n- Testing helpers\n- Parsing utilities\n- Automation scripts\n\n**Should be executable and documented**\n\n## Writing Style Requirements\n\n### Imperative/Infinitive Form\n\nWrite using verb-first instructions, not second person:\n\n**Correct (imperative):**\n```\nTo create a hook, define the event type.\nConfigure the MCP server with authentication.\nValidate settings before use.\n```\n\n**Incorrect (second person):**\n```\nYou should create a hook by defining the event type.\nYou need to configure the MCP server.\nYou must validate settings before use.\n```\n\n### Third-Person in Description\n\nThe frontmatter description must use third person:\n\n**Correct:**\n```yaml\ndescription: This skill should be used when the user asks to \"create X\", \"configure Y\"...\n```\n\n**Incorrect:**\n```yaml\ndescription: Use this skill when you want to create X...\ndescription: Load this skill when user asks...\n```\n\n### Objective, Instructional Language\n\nFocus on what to do, not who should do it:\n\n**Correct:**\n```\nParse the frontmatter using sed.\nExtract fields with grep.\nValidate values before use.\n```\n\n**Incorrect:**\n```\nYou can parse the frontmatter...\nClaude should extract fields...\nThe user might validate values...\n```\n\n## Validation Checklist\n\nBefore finalizing a skill:\n\n**Structure:**\n- [ ] SKILL.md file exists with valid YAML frontmatter\n- [ ] Frontmatter has `name` and `description` fields\n- [ ] Markdown body is present and substantial\n- [ ] Referenced files actually exist\n\n**Description Quality:**\n- [ ] Uses third person (\"This skill should be used when...\")\n- [ ] Includes specific trigger phrases users would say\n- [ ] Lists concrete scenarios (\"create X\", \"configure Y\")\n- [ ] Not vague or generic\n\n**Content Quality:**\n- [ ] SKILL.md body uses imperative/infinitive form\n- [ ] Body is focused and lean (1,500-2,000 words ideal, <5k max)\n- [ ] Detailed content moved to references/\n- [ ] Examples are complete and working\n- [ ] Scripts are executable and documented\n\n**Progressive Disclosure:**\n- [ ] Core concepts in SKILL.md\n- [ ] Detailed docs in references/\n- [ ] Working code in examples/\n- [ ] Utilities in scripts/\n- [ ] SKILL.md references these resources\n\n**Testing:**\n- [ ] Skill triggers on expected user queries\n- [ ] Content is helpful for intended tasks\n- [ ] No duplicated information across files\n- [ ] References load when needed\n\n## Common Mistakes to Avoid\n\n### Mistake 1: Weak Trigger Description\n\n❌ **Bad:**\n```yaml\ndescription: Provides guidance for working with hooks.\n```\n\n**Why bad:** Vague, no specific trigger phrases, not third person\n\n✅ **Good:**\n```yaml\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse hook\", \"validate tool use\", or mentions hook events. Provides comprehensive hooks API guidance.\n```\n\n**Why good:** Third person, specific phrases, concrete scenarios\n\n### Mistake 2: Too Much in SKILL.md\n\n❌ **Bad:**\n```\nskill-name/\n└── SKILL.md (8,000 words - everything in one file)\n```\n\n**Why bad:** Bloats context when skill loads, detailed content always loaded\n\n✅ **Good:**\n```\nskill-name/\n├── SKILL.md (1,800 words - core essentials)\n└── references/\n ├── patterns.md (2,500 words)\n └── advanced.md (3,700 words)\n```\n\n**Why good:** Progressive disclosure, detailed content loaded only when needed\n\n### Mistake 3: Second Person Writing\n\n❌ **Bad:**\n```markdown\nYou should start by reading the configuration file.\nYou need to validate the input.\nYou can use the grep tool to search.\n```\n\n**Why bad:** Second person, not imperative form\n\n✅ **Good:**\n```markdown\nStart by reading the configuration file.\nValidate the input before processing.\nUse the grep tool to search for patterns.\n```\n\n**Why good:** Imperative form, direct instructions\n\n### Mistake 4: Missing Resource References\n\n❌ **Bad:**\n```markdown\n# SKILL.md\n\n[Core content]\n\n[No mention of references/ or examples/]\n```\n\n**Why bad:** Claude doesn't know references exist\n\n✅ **Good:**\n```markdown\n# SKILL.md\n\n[Core content]\n\n## Additional Resources\n\n### Reference Files\n- **`references/patterns.md`** - Detailed patterns\n- **`references/advanced.md`** - Advanced techniques\n\n### Examples\n- **`examples/script.sh`** - Working example\n```\n\n**Why good:** Claude knows where to find additional information\n\n## Quick Reference\n\n### Minimal Skill\n\n```\nskill-name/\n└── SKILL.md\n```\n\nGood for: Simple knowledge, no complex resources needed\n\n### Standard Skill (Recommended)\n\n```\nskill-name/\n├── SKILL.md\n├── references/\n│ └── detailed-guide.md\n└── examples/\n └── working-example.sh\n```\n\nGood for: Most plugin skills with detailed documentation\n\n### Complete Skill\n\n```\nskill-name/\n├── SKILL.md\n├── references/\n│ ├── patterns.md\n│ └── advanced.md\n├── examples/\n│ ├── example1.sh\n│ └── example2.json\n└── scripts/\n └── validate.sh\n```\n\nGood for: Complex domains with validation utilities\n\n## Best Practices Summary\n\n✅ **DO:**\n- Use third-person in description (\"This skill should be used when...\")\n- Include specific trigger phrases (\"create X\", \"configure Y\")\n- Keep SKILL.md lean (1,500-2,000 words)\n- Use progressive disclosure (move details to references/)\n- Write in imperative/infinitive form\n- Reference supporting files clearly\n- Provide working examples\n- Create utility scripts for common operations\n- Study plugin-dev's skills as templates\n\n❌ **DON'T:**\n- Use second person anywhere\n- Have vague trigger conditions\n- Put everything in SKILL.md (>3,000 words without references/)\n- Write in second person (\"You should...\")\n- Leave resources unreferenced\n- Include broken or incomplete examples\n- Skip validation\n\n## Additional Resources\n\n### Study These Skills\n\nPlugin-dev's skills demonstrate best practices:\n- `../hook-development/` - Progressive disclosure, utilities\n- `../agent-development/` - AI-assisted creation, references\n- `../mcp-integration/` - Comprehensive references\n- `../plugin-settings/` - Real-world examples\n- `../command-development/` - Clear critical concepts\n- `../plugin-structure/` - Good organization\n\n### Reference Files\n\nFor complete skill-creator methodology:\n- **`references/skill-creator-original.md`** - Full original skill-creator content\n\n## Implementation Workflow\n\nTo create a skill for your plugin:\n\n1. **Understand use cases**: Identify concrete examples of skill usage\n2. **Plan resources**: Determine what scripts/references/examples needed\n3. **Create structure**: `mkdir -p skills/skill-name/{references,examples,scripts}`\n4. **Write SKILL.md**:\n - Frontmatter with third-person description and trigger phrases\n - Lean body (1,500-2,000 words) in imperative form\n - Reference supporting files\n5. **Add resources**: Create references/, examples/, scripts/ as needed\n6. **Validate**: Check description, writing style, organization\n7. **Test**: Verify skill loads on expected triggers\n8. **Iterate**: Improve based on usage\n\nFocus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.\n","frontmatter":{"name":"Skill Development","description":"This skill should be used when the user wants to \"create a skill\", \"add a skill to plugin\", \"write a new skill\", \"improve skill description\", \"organize skill content\", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.","version":"0.1.0"},"isInternal":false,"tokens":5000,"sizeBytes":22827},{"name":"commit-push-pr.md","path":".claude/commands/commit-push-pr.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/.claude/commands/commit-push-pr.md","title":"Command: /commit-push-pr","category":"command-prompt","format":"markdown","content":"---\nallowed-tools: Bash(git checkout --branch:*), Bash(git add:*), Bash(git status:*), Bash(git push:*), Bash(git commit:*), Bash(gh pr create:*)\ndescription: Commit, push, and open a PR\n---\n\n## Context\n\n- Current git status: !`git status`\n- Current git diff (staged and unstaged changes): !`git diff HEAD`\n- Current branch: !`git branch --show-current`\n\n## Your task\n\nBased on the above changes:\n1. Create a new branch if on main\n2. Create a single commit with an appropriate message\n3. Push the branch to origin\n4. Create a pull request using `gh pr create`\n5. You have the capability to call multiple tools in a single response. You MUST do all of the above in a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls.\n","frontmatter":{"allowed-tools":"Bash(git checkout --branch:*), Bash(git add:*), Bash(git status:*), Bash(git push:*), Bash(git commit:*), Bash(gh pr create:*)","description":"Commit, push, and open a PR","allowedTools":["Bash(git","checkout","--branch:*),","Bash(git","add:*),","Bash(git","status:*),","Bash(git","push:*),","Bash(git","commit:*),","Bash(gh","pr","create:*)"]},"allowedTools":["Bash(git","checkout","--branch:*),","Bash(git","add:*),","Bash(git","status:*),","Bash(git","push:*),","Bash(git","commit:*),","Bash(gh","pr","create:*)"],"isInternal":false,"tokens":200,"sizeBytes":795},{"name":"dedupe.md","path":".claude/commands/dedupe.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/.claude/commands/dedupe.md","title":"Command: /dedupe","category":"command-prompt","format":"markdown","content":"---\nallowed-tools: Bash(./scripts/gh.sh:*), Bash(./scripts/comment-on-duplicates.sh:*)\ndescription: Find duplicate GitHub issues\n---\n\nFind up to 3 likely duplicate issues for a given GitHub issue.\n\nTo do this, follow these steps precisely:\n\n1. Use an agent to check if the Github issue (a) is closed, (b) does not need to be deduped (eg. because it is broad product feedback without a specific solution, or positive feedback), or (c) already has a duplicates comment that you made earlier. If so, do not proceed.\n2. Use an agent to view a Github issue, and ask the agent to return a summary of the issue\n3. Then, launch 5 parallel agents to search Github for duplicates of this issue, using diverse keywords and search approaches, using the summary from #1\n4. Next, feed the results from #1 and #2 into another agent, so that it can filter out false positives, that are likely not actually duplicates of the original issue. If there are no duplicates remaining, do not proceed.\n5. Finally, use the comment script to post duplicates:\n ```\n ./scripts/comment-on-duplicates.sh --potential-duplicates \n ```\n\nNotes (be sure to tell this to your agents, too):\n\n- Use `./scripts/gh.sh` to interact with Github, rather than web fetch or raw `gh`. Examples:\n - `./scripts/gh.sh issue view 123` — view an issue\n - `./scripts/gh.sh issue view 123 --comments` — view with comments\n - `./scripts/gh.sh issue list --state open --limit 20` — list issues\n - `./scripts/gh.sh search issues \"query\" --limit 10` — search for issues\n- Do not use other tools, beyond `./scripts/gh.sh` and the comment script (eg. don't use other MCP servers, file edit, etc.)\n- Make a todo list first\n","frontmatter":{"allowed-tools":"Bash(./scripts/gh.sh:*), Bash(./scripts/comment-on-duplicates.sh:*)","description":"Find duplicate GitHub issues","allowedTools":["Bash(./scripts/gh.sh:*),","Bash(./scripts/comment-on-duplicates.sh:*)"]},"allowedTools":["Bash(./scripts/gh.sh:*),","Bash(./scripts/comment-on-duplicates.sh:*)"],"isInternal":false,"tokens":428,"sizeBytes":1701},{"name":"triage-issue.md","path":".claude/commands/triage-issue.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/.claude/commands/triage-issue.md","title":"Command: /triage-issue","category":"command-prompt","format":"markdown","content":"---\nallowed-tools: Bash(./scripts/gh.sh:*),Bash(./scripts/edit-issue-labels.sh:*)\ndescription: Triage GitHub issues by analyzing and applying labels\n---\n\nYou're an issue triage assistant. Analyze the issue and manage labels.\n\nIMPORTANT: Don't post any comments or messages to the issue. Your only actions are adding or removing labels.\n\nContext:\n\n$ARGUMENTS\n\nTOOLS:\n- `./scripts/gh.sh` — wrapper for `gh` CLI. Only supports these subcommands and flags:\n - `./scripts/gh.sh label list` — fetch all available labels\n - `./scripts/gh.sh label list --limit 100` — fetch with limit\n - `./scripts/gh.sh issue view 123` — read issue title, body, and labels\n - `./scripts/gh.sh issue view 123 --comments` — read the conversation\n - `./scripts/gh.sh issue list --state open --limit 20` — list issues\n - `./scripts/gh.sh search issues \"query\"` — find similar or duplicate issues\n - `./scripts/gh.sh search issues \"query\" --limit 10` — search with limit\n- `./scripts/edit-issue-labels.sh --add-label LABEL --remove-label LABEL` — add or remove labels (issue number is read from the workflow event)\n\nTASK:\n\n1. Run `./scripts/gh.sh label list` to fetch the available labels. You may ONLY use labels from this list. Never invent new labels.\n2. Run `./scripts/gh.sh issue view ISSUE_NUMBER` to read the issue details.\n3. Run `./scripts/gh.sh issue view ISSUE_NUMBER --comments` to read the conversation.\n\n**If EVENT is \"issues\" (new issue):**\n\n4. First, check if this issue is actually about Claude Code.\n - Look for Claude Code signals in the issue BODY: a `Claude Code Version` field or `claude --version` output, references to the `claude` CLI command, terminal sessions, the VS Code/JetBrains extensions, `CLAUDE.md` files, `.claude/` directories, MCP servers, Cowork, Remote Control, or the web UI at claude.ai/code. If ANY such signal is present, this IS a Claude Code issue — proceed to step 5.\n - Only if NO Claude Code signals are present: check whether a different Anthropic product (claude.ai chat, Claude Desktop/Mobile apps, the raw Anthropic API/SDK, or account billing with no CLI involvement) is the *subject* of the complaint, not merely mentioned for context. If so, apply `invalid` and stop. If ambiguous, proceed to step 5 WITHOUT applying `invalid`.\n - The body text is authoritative. If a form dropdown (e.g. Platform) contradicts evidence in the body, trust the body — dropdowns are often mis-selected.\n\n5. Analyze and apply category labels:\n - Type (bug, enhancement, question, etc.)\n - Technical areas and platform\n - Check for duplicates with `./scripts/gh.sh search issues`. Only mark as duplicate of OPEN issues.\n\n6. Evaluate lifecycle labels:\n - `needs-repro` (bugs only, 7 days): Bug reports without clear steps to reproduce. A good repro has specific, followable steps that someone else could use to see the same issue.\n Do NOT apply if the user already provided error messages, logs, file paths, or a description of what they did. Don't require a specific format — narrative descriptions count.\n For model behavior issues (e.g. \"Claude does X when it should do Y\"), don't require traditional repro steps — examples and patterns are sufficient.\n - `needs-info` (bugs only, 7 days): The issue needs something from the community before it can progress — e.g. error messages, versions, environment details, or answers to follow-up questions. Don't apply to questions or enhancements.\n Do NOT apply if the user already provided version, environment, and error details. If the issue just needs engineering investigation, that's not `needs-info`.\n\n Issues with these labels are automatically closed after the timeout if there's no response.\n The goal is to avoid issues lingering without a clear next step.\n\n7. Apply all selected labels:\n `./scripts/edit-issue-labels.sh --add-label \"label1\" --add-label \"label2\"`\n\n**If EVENT is \"issue_comment\" (comment on existing issue):**\n\n4. Evaluate lifecycle labels based on the full conversation:\n - If the issue has `stale` or `autoclose`, remove the label — a new human comment means the issue is still active:\n `./scripts/edit-issue-labels.sh --remove-label \"stale\" --remove-label \"autoclose\"`\n - If the issue has `needs-repro` or `needs-info` and the missing information has now been provided, remove the label:\n `./scripts/edit-issue-labels.sh --remove-label \"needs-repro\"`\n - If the issue doesn't have lifecycle labels but clearly needs them (e.g., a maintainer asked for repro steps or more details), add the appropriate label.\n - Comments like \"+1\", \"me too\", \"same here\", or emoji reactions are NOT the missing information. Only remove `needs-repro` or `needs-info` when substantive details are actually provided.\n - Do NOT add or remove category labels (bug, enhancement, etc.) on comment events.\n\nGUIDELINES:\n- ONLY use labels from `./scripts/gh.sh label list` — never create or guess label names\n- DO NOT post any comments to the issue\n- Be conservative with lifecycle labels — only apply when clearly warranted\n- Only apply lifecycle labels (`needs-repro`, `needs-info`) to bugs — never to questions or enhancements\n- When in doubt, don't apply a lifecycle label — false positives are worse than missing labels\n- On new issues (EVENT \"issues\"), always apply exactly one of `bug`, `enhancement`, `question`, `invalid`, or `duplicate`. If unsure, pick the closest fit — an imperfect category label is better than none.\n- On comment events, it's okay to make no changes if nothing applies.\n","frontmatter":{"allowed-tools":"Bash(./scripts/gh.sh:*),Bash(./scripts/edit-issue-labels.sh:*)","description":"Triage GitHub issues by analyzing and applying labels","allowedTools":["Bash(./scripts/gh.sh:*),Bash(./scripts/edit-issue-labels.sh:*)"]},"allowedTools":["Bash(./scripts/gh.sh:*),Bash(./scripts/edit-issue-labels.sh:*)"],"isInternal":false,"tokens":1306,"sizeBytes":5550},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/.claude-plugin/marketplace.json","title":"claude-code-plugins","category":"marketplace","format":"json","content":"{\n \"$schema\": \"https://json.schemastore.org/claude-code-marketplace.json\",\n \"name\": \"claude-code-plugins\",\n \"version\": \"1.0.0\",\n \"description\": \"Bundled plugins for Claude Code including Agent SDK development tools, PR review toolkit, and commit workflows\",\n \"owner\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"plugins\": [\n {\n \"name\": \"agent-sdk-dev\",\n \"description\": \"Development kit for working with the Claude Agent SDK\",\n \"source\": \"./plugins/agent-sdk-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"claude-opus-4-5-migration\",\n \"description\": \"Migrate your code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"William Hu\",\n \"email\": \"whu@anthropic.com\"\n },\n \"source\": \"./plugins/claude-opus-4-5-migration\",\n \"category\": \"development\"\n },\n {\n \"name\": \"code-review\",\n \"description\": \"Automated code review for pull requests using multiple specialized agents with confidence-based scoring to filter false positives\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Boris Cherny\",\n \"email\": \"boris@anthropic.com\"\n },\n \"source\": \"./plugins/code-review\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"commit-commands\",\n \"description\": \"Commands for git commit workflows including commit, push, and PR creation\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"source\": \"./plugins/commit-commands\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"explanatory-output-style\",\n \"description\": \"Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Dickson Tsai\",\n \"email\": \"dickson@anthropic.com\"\n },\n \"source\": \"./plugins/explanatory-output-style\",\n \"category\": \"learning\"\n },\n {\n \"name\": \"feature-dev\",\n \"description\": \"Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Siddharth Bidasaria\",\n \"email\": \"sbidasaria@anthropic.com\"\n },\n \"source\": \"./plugins/feature-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"frontend-design\",\n \"description\": \"Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics.\",\n \"version\": \"1.1.0\",\n \"author\": {\n \"name\": \"Prithvi Rajasekaran & Alexander Bricken\",\n \"email\": \"prithvi@anthropic.com\"\n },\n \"source\": \"./plugins/frontend-design\",\n \"category\": \"development\"\n },\n {\n \"name\": \"hookify\",\n \"description\": \"Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. Define rules via simple markdown files.\",\n \"version\": \"0.1.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/hookify\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"learning-output-style\",\n \"description\": \"Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style)\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Boris Cherny\",\n \"email\": \"boris@anthropic.com\"\n },\n \"source\": \"./plugins/learning-output-style\",\n \"category\": \"learning\"\n },\n {\n \"name\": \"plugin-dev\",\n \"description\": \"Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.\",\n \"version\": \"0.1.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/plugin-dev\",\n \"category\": \"development\"\n },\n {\n \"name\": \"pr-review-toolkit\",\n \"description\": \"Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Anthropic\",\n \"email\": \"support@anthropic.com\"\n },\n \"source\": \"./plugins/pr-review-toolkit\",\n \"category\": \"productivity\"\n },\n {\n \"name\": \"ralph-wiggum\",\n \"description\": \"Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly, seeing its previous work, until completion.\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"Daisy Hollman\",\n \"email\": \"daisy@anthropic.com\"\n },\n \"source\": \"./plugins/ralph-wiggum\",\n \"category\": \"development\"\n },\n {\n \"name\": \"security-guidance\",\n \"description\": \"Security reminder hook that warns about potential security issues when editing files, including command injection, XSS, and unsafe code patterns\",\n \"version\": \"1.0.0\",\n \"author\": {\n \"name\": \"David Dworken\",\n \"email\": \"dworken@anthropic.com\"\n },\n \"source\": \"./plugins/security-guidance\",\n \"category\": \"security\"\n }\n ]\n}\n","frontmatter":{"$schema":"https://json.schemastore.org/claude-code-marketplace.json","name":"claude-code-plugins","version":"1.0.0","description":"Bundled plugins for Claude Code including Agent SDK development tools, PR review toolkit, and commit workflows","owner":{"name":"Anthropic","email":"support@anthropic.com"},"plugins":[{"name":"agent-sdk-dev","description":"Development kit for working with the Claude Agent SDK","source":"./plugins/agent-sdk-dev","category":"development"},{"name":"claude-opus-4-5-migration","description":"Migrate your code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5.","version":"1.0.0","author":{"name":"William Hu","email":"whu@anthropic.com"},"source":"./plugins/claude-opus-4-5-migration","category":"development"},{"name":"code-review","description":"Automated code review for pull requests using multiple specialized agents with confidence-based scoring to filter false positives","version":"1.0.0","author":{"name":"Boris Cherny","email":"boris@anthropic.com"},"source":"./plugins/code-review","category":"productivity"},{"name":"commit-commands","description":"Commands for git commit workflows including commit, push, and PR creation","version":"1.0.0","author":{"name":"Anthropic","email":"support@anthropic.com"},"source":"./plugins/commit-commands","category":"productivity"},{"name":"explanatory-output-style","description":"Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)","version":"1.0.0","author":{"name":"Dickson Tsai","email":"dickson@anthropic.com"},"source":"./plugins/explanatory-output-style","category":"learning"},{"name":"feature-dev","description":"Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review","version":"1.0.0","author":{"name":"Siddharth Bidasaria","email":"sbidasaria@anthropic.com"},"source":"./plugins/feature-dev","category":"development"},{"name":"frontend-design","description":"Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics.","version":"1.1.0","author":{"name":"Prithvi Rajasekaran & Alexander Bricken","email":"prithvi@anthropic.com"},"source":"./plugins/frontend-design","category":"development"},{"name":"hookify","description":"Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. Define rules via simple markdown files.","version":"0.1.0","author":{"name":"Daisy Hollman","email":"daisy@anthropic.com"},"source":"./plugins/hookify","category":"productivity"},{"name":"learning-output-style","description":"Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style)","version":"1.0.0","author":{"name":"Boris Cherny","email":"boris@anthropic.com"},"source":"./plugins/learning-output-style","category":"learning"},{"name":"plugin-dev","description":"Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.","version":"0.1.0","author":{"name":"Daisy Hollman","email":"daisy@anthropic.com"},"source":"./plugins/plugin-dev","category":"development"},{"name":"pr-review-toolkit","description":"Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification","version":"1.0.0","author":{"name":"Anthropic","email":"support@anthropic.com"},"source":"./plugins/pr-review-toolkit","category":"productivity"},{"name":"ralph-wiggum","description":"Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly, seeing its previous work, until completion.","version":"1.0.0","author":{"name":"Daisy Hollman","email":"daisy@anthropic.com"},"source":"./plugins/ralph-wiggum","category":"development"},{"name":"security-guidance","description":"Security reminder hook that warns about potential security issues when editing files, including command injection, XSS, and unsafe code patterns","version":"1.0.0","author":{"name":"David Dworken","email":"dworken@anthropic.com"},"source":"./plugins/security-guidance","category":"security"}]},"isInternal":false,"tokens":1365,"sizeBytes":5468},{"name":"plugin.json","path":"mods/agents-md/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/mods/agents-md/.claude-plugin/plugin.json","title":"agents-md","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"agents-md","version":"0.1.0","description":"AGENTS.md as project instructions, by one option. Under claude-md-or-agents-md a project with no instruction files of its own gets its AGENTS.md files instead: a prompt.context hook asks $.fs.ancestors for every AGENTS.md and .claude/AGENTS.md from the filesystem root down to the working directory and hands them to the engine as project instruction files, which it renders, announces and withholds from agents exactly as it does CLAUDE.md, skipping any file the engine already loaded by import or link; a tool.call hook on Read attaches the ones under the project root as the engine attaches a nested CLAUDE.md. Under claude-md-and-agents-md every AGENTS.md is loaded beside CLAUDE.md. Under managed-only the project's and the person's instruction files are dropped and the organization's managed ones kept. Under claude-md the engine's walk stands alone. claude-md-or-agents-md is the default.","author":{"name":"Anthropic"},"userConfig":{"instructionFiles":{"type":"string","title":"Project instructions","description":"\"claude-md\": CLAUDE.md only, loaded by the engine as today. \"claude-md-or-agents-md\" (default): a project with no CLAUDE.md of its own gets its AGENTS.md files instead, loaded exactly where and how CLAUDE.md would be. \"claude-md-and-agents-md\": AGENTS.md files are loaded beside CLAUDE.md (a file CLAUDE.md already imports or links to is not loaded twice). \"managed-only\": the project's and your own instruction files are dropped; the organization's managed CLAUDE.md and memory stay.","required":false,"default":"claude-md-or-agents-md","options":["claude-md","claude-md-or-agents-md","claude-md-and-agents-md","managed-only"]}}},"isInternal":false,"tokens":457,"sizeBytes":1851},{"name":"plugin.json","path":"mods/diff/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/mods/diff/.claude-plugin/plugin.json","title":"diff","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"diff","version":"0.1.0","description":"The diff pane as a plugin: /diff opens the session's uncommitted changes beside the transcript, file by file with their hunks, refreshed as Claude edits and runs commands; the first edit opens it where the terminal is wide enough, and a file's ask button rides its hunks on the next prompt.","author":{"name":"Anthropic"}},"isInternal":false,"tokens":103,"sizeBytes":397},{"name":"plugin.json","path":"mods/sec-default/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/mods/sec-default/.claude-plugin/plugin.json","title":"sec-default","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"sec-default","version":"0.1.0","description":"Security default for organizations: seated outermost, it keeps the organization's classic hooks, prompt content, settings, tool policy and pinned environment out of reach of the plugins a person installs, and adds no policy of its own; one managed option, allowManagedModsOnly, limits mods to the organization's.","author":{"name":"Anthropic"}},"isInternal":false,"tokens":102,"sizeBytes":426},{"name":"plugin.json","path":"mods/telemetry/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/mods/telemetry/.claude-plugin/plugin.json","title":"telemetry","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"telemetry","version":"0.1.0","description":"Plugin analytics: hooks $.telemetry's two events, so a plugin logs an event or marks a feature's use as a first-party row, sent in batches with the session's own credential.","author":{"name":"Anthropic"},"types":"./types/index.d.ts"},"isInternal":false,"tokens":90,"sizeBytes":318},{"name":"plugin.json","path":"plugins/agent-sdk-dev/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/agent-sdk-dev/.claude-plugin/plugin.json","title":"agent-sdk-dev","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"agent-sdk-dev","description":"Claude Agent SDK Development Plugin","version":"1.0.0","author":{"name":"Ashwin Bhat","email":"ashwin@anthropic.com"}},"isInternal":false,"tokens":63,"sizeBytes":190},{"name":"README.md","path":"plugins/agent-sdk-dev/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/agent-sdk-dev/README.md","title":"agent-sdk-dev Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1366,"sizeBytes":6397},{"name":"plugin.json","path":"plugins/claude-opus-4-5-migration/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/claude-opus-4-5-migration/.claude-plugin/plugin.json","title":"claude-opus-4-5-migration","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"claude-opus-4-5-migration","version":"1.0.0","description":"Migrate your code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5.","author":{"name":"William Hu","email":"whu@anthropic.com"}},"isInternal":false,"tokens":88,"sizeBytes":234},{"name":"README.md","path":"plugins/claude-opus-4-5-migration/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/claude-opus-4-5-migration/README.md","title":"claude-opus-4-5-migration Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":185,"sizeBytes":707},{"name":"plugin.json","path":"plugins/code-review/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/code-review/.claude-plugin/plugin.json","title":"code-review","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"code-review","description":"Automated code review for pull requests using multiple specialized agents with confidence-based scoring","version":"1.0.0","author":{"name":"Boris Cherny","email":"boris@anthropic.com"}},"isInternal":false,"tokens":71,"sizeBytes":257},{"name":"README.md","path":"plugins/code-review/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/code-review/README.md","title":"code-review Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1755,"sizeBytes":7703},{"name":"plugin.json","path":"plugins/commit-commands/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/commit-commands/.claude-plugin/plugin.json","title":"commit-commands","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"commit-commands","description":"Streamline your git workflow with simple commands for committing, pushing, and creating pull requests","version":"1.0.0","author":{"name":"Anthropic","email":"support@anthropic.com"}},"isInternal":false,"tokens":71,"sizeBytes":258},{"name":"README.md","path":"plugins/commit-commands/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/commit-commands/README.md","title":"commit-commands Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1338,"sizeBytes":5908},{"name":"plugin.json","path":"plugins/explanatory-output-style/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/explanatory-output-style/.claude-plugin/plugin.json","title":"explanatory-output-style","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"explanatory-output-style","version":"1.0.0","description":"Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)","author":{"name":"Dickson Tsai","email":"dickson@anthropic.com"}},"isInternal":false,"tokens":81,"sizeBytes":293},{"name":"README.md","path":"plugins/explanatory-output-style/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/explanatory-output-style/README.md","title":"explanatory-output-style Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":475,"sizeBytes":2470},{"name":"plugin.json","path":"plugins/feature-dev/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/feature-dev/.claude-plugin/plugin.json","title":"feature-dev","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"feature-dev","version":"1.0.0","description":"Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review","author":{"name":"Sid Bidasaria","email":"sbidasaria@anthropic.com"}},"isInternal":false,"tokens":76,"sizeBytes":291},{"name":"README.md","path":"plugins/feature-dev/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/feature-dev/README.md","title":"feature-dev Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":2519,"sizeBytes":11697},{"name":"plugin.json","path":"plugins/frontend-design/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/frontend-design/.claude-plugin/plugin.json","title":"frontend-design","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"frontend-design","version":"1.1.0","description":"Frontend design skill for UI/UX implementation","author":{"name":"Prithvi Rajasekaran, Alexander Bricken","email":"prithvi@anthropic.com, alexander@anthropic.com"}},"isInternal":false,"tokens":80,"sizeBytes":256},{"name":"README.md","path":"plugins/frontend-design/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/frontend-design/README.md","title":"frontend-design Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":210,"sizeBytes":977},{"name":"plugin.json","path":"plugins/hookify/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/hookify/.claude-plugin/plugin.json","title":"hookify","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"hookify","version":"0.1.0","description":"Easily create hooks to prevent unwanted behaviors by analyzing conversation patterns","author":{"name":"Daisy Hollman","email":"daisy@anthropic.com"}},"isInternal":false,"tokens":68,"sizeBytes":234},{"name":"README.md","path":"plugins/hookify/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/hookify/README.md","title":"hookify Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1893,"sizeBytes":7710},{"name":"plugin.json","path":"plugins/learning-output-style/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/learning-output-style/.claude-plugin/plugin.json","title":"learning-output-style","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"learning-output-style","version":"1.0.0","description":"Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style)","author":{"name":"Boris Cherny","email":"boris@anthropic.com"}},"isInternal":false,"tokens":79,"sizeBytes":296},{"name":"README.md","path":"plugins/learning-output-style/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/learning-output-style/README.md","title":"learning-output-style Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":838,"sizeBytes":4687},{"name":"README.md","path":"plugins/plugin-dev/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/README.md","title":"plugin-dev Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":3134,"sizeBytes":14592},{"name":"README.md","path":"plugins/plugin-dev/skills/command-development/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/command-development/README.md","title":"command-development Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1728,"sizeBytes":7651},{"name":"README.md","path":"plugins/plugin-dev/skills/hook-development/scripts/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/hook-development/scripts/README.md","title":"scripts Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":903,"sizeBytes":3677},{"name":"README.md","path":"plugins/plugin-dev/skills/plugin-structure/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/plugin-dev/skills/plugin-structure/README.md","title":"plugin-structure Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":678,"sizeBytes":3210},{"name":"plugin.json","path":"plugins/pr-review-toolkit/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/pr-review-toolkit/.claude-plugin/plugin.json","title":"pr-review-toolkit","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"pr-review-toolkit","version":"1.0.0","description":"Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification","author":{"name":"Daisy","email":"daisy@anthropic.com"}},"isInternal":false,"tokens":80,"sizeBytes":282},{"name":"README.md","path":"plugins/pr-review-toolkit/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/pr-review-toolkit/README.md","title":"pr-review-toolkit Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1730,"sizeBytes":7528},{"name":"plugin.json","path":"plugins/ralph-wiggum/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/ralph-wiggum/.claude-plugin/plugin.json","title":"ralph-wiggum","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"ralph-wiggum","version":"1.0.0","description":"Implementation of the Ralph Wiggum technique - continuous self-referential AI loops for interactive iterative development. Run Claude in a while-true loop with the same prompt until task completion.","author":{"name":"Daisy Hollman","email":"daisy@anthropic.com"}},"isInternal":false,"tokens":95,"sizeBytes":353},{"name":"README.md","path":"plugins/ralph-wiggum/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/ralph-wiggum/README.md","title":"ralph-wiggum Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1240,"sizeBytes":5201},{"name":"README.md","path":"plugins/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/README.md","title":"plugins Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1427,"sizeBytes":6530},{"name":"plugin.json","path":"plugins/security-guidance/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/security-guidance/.claude-plugin/plugin.json","title":"security-guidance","category":"plugin-manifest","format":"json","content":"","frontmatter":{"name":"security-guidance","version":"2.0.0","description":"Security review for Claude-generated code. Pattern-based warnings on edits, LLM-powered diff review on Stop, and an agentic commit reviewer that catches injection, XSS, SSRF, hardcoded secrets, and 25+ other vulnerability classes.","author":{"name":"David Dworken","email":"dworken@anthropic.com"},"homepage":"https://github.com/anthropics/claude-code/tree/main/plugins/security-guidance"},"isInternal":false,"tokens":128,"sizeBytes":487},{"name":"README.md","path":"plugins/security-guidance/README.md","rawUrl":"https://raw.githubusercontent.com/anthropics/claude-code/HEAD/plugins/security-guidance/README.md","title":"security-guidance Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1767,"sizeBytes":7219}],"systemPromptSnippet":"\n\n# CLAUDE.md\n\nGuidance for Claude Code and other coding agents working in this repository.\n\n## Security hardening for GitHub Actions\n\nWorkflow jobs in this repository that call Claude run with three protections.\nKeep them when you add or edit a workflow.\n\n1. **Egress-firewall runner.** The job has `runs-on: ubuntu-24.04-firewall`,\n a GitHub-hosted runner that filters the job's outbound network traffic. Do\n not move a job that calls Claude to another runner.\n2. **Network allow list.** `.github/egress-firewall.yaml` lists the hosts\n those jobs may reach, besides any that GitHub's firewall allows by default.\n Keep `mode: enforce`, which is what makes the firewall block the rest. Follow\n that file's header when you add a host.\n3. **Auto permission mode.** Every step that runs the Claude Code action\n (`uses: anthropics/claude-code-action`, or a local action with a\n `claude_args` input) passes `--permission-mode auto` in `claude_args`. A tool\n call that needs permission and that the allowed tools do not cover then runs\n only if Claude Code's safety review passes it. Allow only the tools the job\n needs, and keep any `--disallowedTools` list a step has. Use `claude-opus-4-6`\n or a newer model: on an older one Claude Code falls back to its default\n permission mode.\n\n`claude.yml` answers `@claude` mentions. The Claude Code action sets\n`--permission-mode acceptEdits` for those, and the `--permission-mode auto` in\nthe workflow's `claude_args`, which comes after it, replaces it.\n\n`.github/workflows/workflow-hardening.yml` fails when a job that runs the Claude\nCode action or mentions `ANTHROPIC_FEDERATION_RULE_ID` breaks protection 1 or 3,\nor when the allow list is missing, empty, not `mode: enforce`, or names a host\nwith `*`. It cannot see a job that calls Claude another way, so check new\nworkflows by hand too. If a job cannot meet protection 1 or 3, add it with the\nreason to the matching exemption table in\n`.github/scripts/check_workflow_hardening.py`. A job in `EXEMPT_FROM_AUTO_MODE`\nmust set no permission mode at all. Do not skip or weaken the check.\n\nKeep each workflow's `permissions:` block minimal, and never print tokens or\nenvironment variables in workflow logs.\n\n\n# Effort Parameter (Beta)\n\n**Add effort set to `\"high\"` during migration.** This is the default configuration for best performance with Opus 4.5.\n\n## Overview\n\nEffort controls how eagerly Claude spends tokens. It affects all tokens: thinking, text responses, and function calls.\n\n| Effort | Use Case |\n|--------|----------|\n| `high` | Best performance, deep reasoning (default) |\n| `medium` | Balance of cost/latency vs. performance |\n| `low` | Simple, high-volume queries; significant token savings |\n\n## Implementation\n\nRequires beta flag `effort-2025-11-24` in API calls.\n\n**Python SDK:**\n```python\nresponse = client.messages.create(\n model=\"claude-opus-4-5-20251101\",\n max_tokens=1024,\n betas=[\"effort-2025-11-24\"],\n output_config={\n \"effort\": \"high\" # or \"medium\" or \"low\"\n },\n messages=[...]\n)\n```\n\n**TypeScript SDK:**\n```typescript\nconst response = await client.messages.create({\n model: \"claude-opus-4-5-20251101\",\n max_tokens: 1024,\n betas: [\"effort-2025-11-24\"],\n output_config: {\n effort: \"high\" // or \"medium\" or \"low\"\n },\n messages: [...]\n});\n```\n\n**Raw API:**\n```json\n{\n \"model\": \"claude-opus-4-5-20251101\",\n \"max_tokens\": 1024,\n \"anthropic-beta\": \"effort-2025-11-24\",\n \"output_config\": {\n \"effort\": \"high\"\n },\n \"messages\": [...]\n}\n```\n\n## Effort vs. Thinking Budget\n\nEffort is independent of thinking budget:\n\n- High effort + no thinking = more tokens, but no thinking tokens\n- High effort + 32k thinking = more tokens, but thinking capped at 32k\n\n## Recommendations\n\n1. First determine effort level, then set thinking budget\n2. Best performance: high effort + high thinking budget\n3. Cost/latency optimization: medium effort\n4. Simple high-volume queries: low effort\n\n\n# Prompt Snippets for Opus 4.5\n\nOnly apply these snippets if the user explicitly requests them or reports a specific issue. By default, the migration should only update model strings.\n\n## 1. Tool Overtriggering\n\n**Problem**: Prompts designed to reduce undertriggering on previous models may cause Opus 4.5 to overtrigger.\n\n**When to add**: User reports tools being called too frequently or unnecessarily.\n\n**Solution**: Replace aggressive language with normal phrasing.\n\n| Before | After |\n|--------|-------|\n| `CRITICAL: You MUST use this tool when...` | `Use this tool when...` |\n| `ALWAYS call the search function before...` | `Call the search function before...` |\n| `You are REQUIRED to...` | `You should...` |\n| `NEVER skip this step` | `Don't skip this step` |\n\n## 2. Over-Engineering Prevention\n\n**Problem**: Opus 4.5 may create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**When to add**: User reports unwanted files, excessive abstraction, or unrequested features.\n\n**Snippet to add to system prompt**:\n\n```\n- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.\n- Don't add features, refactor code, or make \"improvements\" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.\n- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.\n- Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.\n```\n\n## 3. Code Exploration\n\n**Problem**: Opus 4.5 may propose solutions without reading code or make assumptions about unread files.\n\n**When to add**: User reports the model proposing fixes without inspecting relevant code.\n\n**Snippet to add to system prompt**:\n\n```\nALWAYS read and understand relevant files before proposing code edits. Do not speculate about code you have not inspected. If the user references a specific file/path, you MUST open and inspect it before explaining or proposing fixes. Be rigorous and persistent in searching code for key facts. Thoroughly review the style, conventions, and abstractions of the codebase before implementing new features or abstractions.\n```\n\n## 4. Frontend Design Quality\n\n**Problem**: Default frontend outputs may look generic (\"AI slop\" aesthetic).\n\n**When to add**: User requests improved frontend design quality or reports generic-looking outputs.\n\n**Snippet to add to system prompt**:\n\n```xml\n\nYou tend to converge toward generic, \"on distribution\" outputs. In frontend design, this creates what users call the \"AI slop\" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight.\n\nFocus on:\n- Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.\n- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.\n- Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.\n- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.\n\nAvoid generic AI-generated aesthetics:\n- Overused font families (Inter, Roboto, Arial, system fonts)\n- Clichéd color schemes (particularly purple gradients on white backgrounds)\n- Predictable layouts and component patterns\n- Cookie-cutter design that lacks context-specific character\n\nInterpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!\n\n```\n\n## 5. Thinking Sensitivity\n\n**Problem**: When extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants.\n\nExtended thinking is not enabled by default. It is only enabled if the API request contains a `thinking` parameter:\n```json\n\"thinking\": {\n \"type\": \"enabled\",\n \"budget_tokens\": 10000\n}\n```\n\n**When to apply**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in their request).\n\n**Solution**: Replace \"think\" with alternative words.\n\n| Before | After |\n|--------|-------|\n| `think about` | `consider` |\n| `think through` | `evaluate` |\n| `I think` | `I believe` |\n| `think carefully` | `consider carefully` |\n| `thinking` | `reasoning` / `considering` |\n\n## Usage Guidelines\n\n1. **Integrate thoughtfully** - Don't just append snippets; weave them into the existing prompt structure\n2. **Use XML tags** - Wrap additions in descriptive tags (e.g., ``, ``) that match or complement existing prompt structure\n3. **Match prompt style** - If the prompt is concise, trim the snippet; if verbose, keep full detail\n4. **Place logically** - Put coding snippets near other coding instructions, tool guidance near tool definitions, etc.\n5. **Preserve existing content** - Insert snippets without removing functional content\n6. **Summarize changes** - After migration, list all model string updates and prompt modifications made\n\n\n---\nname: claude-opus-4-5-migration\ndescription: Migrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5. Use when the user wants to update their codebase, prompts, or API calls to use Opus 4.5. Handles model string updates and prompt adjustments for known Opus 4.5 behavioral differences. Does NOT migrate Haiku 4.5.\n---\n\n# Opus 4.5 Migration Guide\n\nOne-shot migration from Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5.\n\n## Migration Workflow\n\n1. Search codebase for model strings and API calls\n2. Update model strings to Opus 4.5 (see platform-specific strings below)\n3. Remove unsupported beta headers\n4. Add effort parameter set to `\"high\"` (see `references/effort.md`)\n5. Summarize all changes made\n6. Tell the user: \"If you encounter any issues with Opus 4.5, let me know and I can help adjust your prompts.\"\n\n## Model String Updates\n\nIdentify which platform the codebase uses, then replace model strings accordingly.\n\n### Unsupported Beta Headers\n\nRemove the `context-1m-2025-08-07` beta header if present—it is not yet supported with Opus 4.5. Leave a comment noting this:\n\n```python\n# Note: 1M context beta (context-1m-2025-08-07) not yet supported with Opus 4.5\n```\n\n### Target Model Strings (Opus 4.5)\n\n| Platform | Opus 4.5 Model String |\n|----------|----------------------|\n| Anthropic API (1P) | `claude-opus-4-5-20251101` |\n| AWS Bedrock | `anthropic.claude-opus-4-5-20251101-v1:0` |\n| Google Vertex AI | `claude-opus-4-5@20251101` |\n| Azure AI Foundry | `claude-opus-4-5-20251101` |\n\n### Source Model Strings to Replace\n\n| Source Model | Anthropic API (1P) | AWS Bedrock | Google Vertex AI |\n|--------------|-------------------|-------------|------------------|\n| Sonnet 4.0 | `claude-sonnet-4-20250514` | `anthropic.claude-sonnet-4-20250514-v1:0` | `claude-sonnet-4@20250514` |\n| Sonnet 4.5 | `claude-sonnet-4-5-20250929` | `anthropic.claude-sonnet-4-5-20250929-v1:0` | `claude-sonnet-4-5@20250929` |\n| Opus 4.1 | `claude-opus-4-1-20250422` | `anthropic.claude-opus-4-1-20250422-v1:0` | `claude-opus-4-1@20250422` |\n\n**Do NOT migrate**: Any Haiku models (e.g., `claude-haiku-4-5-20251001`).\n\n## Prompt Adjustments\n\nOpus 4.5 has known behavioral differences from previous models. **Only apply these fixes if the user explicitly requests them or reports a specific issue.** By default, just update model strings.\n\n**Integration guidelines**: When adding snippets, don't just append them to prompts. Integrate them thoughtfully:\n- Use XML tags (e.g., ``, ``) to organize additions\n- Match the style and structure of the existing prompt\n- Place snippets in logical locations (e.g., coding guidelines near other coding instructions)\n- If the prompt already uses XML tags, add new content within appropriate existing tags or create consistent new ones\n\n### 1. Tool Overtriggering\n\nOpus 4.5 is more responsive to system prompts. Aggressive language that prevented undertriggering on previous models may now cause overtriggering.\n\n**Apply if**: User reports tools being called too frequently or unnecessarily.\n\n**Find and soften**:\n- `CRITICAL:` → remove or soften\n- `You MUST...` → `You should...`\n- `ALWAYS do X` → `Do X`\n- `NEVER skip...` → `Don't skip...`\n- `REQUIRED` → remove or soften\n\nOnly apply to tool-triggering instructions. Leave other uses of emphasis alone.\n\n### 2. Over-Engineering Prevention\n\nOpus 4.5 tends to create extra files, add unnecessary abstractions, or build unrequested flexibility.\n\n**Apply if**: User reports unwanted files, excessive abstraction, or unrequested features. Add the snippet from `references/prompt-snippets.md`.\n\n### 3. Code Exploration\n\nOpus 4.5 can be overly conservative about exploring code, proposing solutions without reading files.\n\n**Apply if**: User reports the model proposing fixes without inspecting relevant code. Add the snippet from `references/prompt-snippets.md`.\n\n### 4. Frontend Design\n\n**Apply if**: User requests improved frontend design quality or reports generic-looking outputs.\n\nAdd the frontend aesthetics snippet from `references/prompt-snippets.md`.\n\n### 5. Thinking Sensitivity\n\nWhen extended thinking is not enabled (the default), Opus 4.5 is particularly sensitive to the word \"think\" and its variants. Extended thinking is enabled only if the API request contains a `thinking` parameter.\n\n**Apply if**: User reports issues related to \"thinking\" while extended thinking is not enabled (no `thinking` parameter in request).\n\nReplace \"think\" with alternatives like \"consider,\" \"believe,\" or \"evaluate.\"\n\n## Reference\n\nSee `references/prompt-snippets.md` for the full text of each snippet to add.\n\nSee `references/effort.md` for configuring the effort parameter (only if user requests it).\n\n\n---\nname: frontend-design\ndescription: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.\nlicense: Complete terms in LICENSE.txt\n---\n\n# Frontend Design\n\nApproach this as the design lead at a design studio known for giving every client a distinct visual identity that is not mistaken for anyone else's. This client has already rejected proposals that felt cliché or templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take aesthetic risk if justified.\n\n## Ground your designs in the subject matter\n\nIf the brief does not identify what the product or subject matter is, identify it yourself before designing, and confirm with the client. You can come up with one concrete subject, the design's audience, and the design's primary job, as a proposal. If there's any information in your memory about the client's preferences or context about what they're building, use that as a hint. The subject's industry, subject matter, materials, and vernacular are where distinctive visual choices come from — a design for a toy for girls aged 8–11 will be very aesthetically different from a dashboard for financial analysts. Build with the brief's real content and subject matter throughout.\n\n## Design principles\n\nFor web designs, the hero is the first thing viewers will see. Open with the most characteristic thing in the subject's world, in the form that is most appropriate: a headline, an image, an animation, a live demo, an interactive moment, or other treatments. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the default treatment, so only use it if that's truly the best option.\n\nTypography carries the personality of the page. You don't need a different typeface for display or headline text and body content: use one family or two, and if two, make them clearly distinct.\n\nChoose your typefaces deliberately, not the default families you would reach for on any other project, and set a clear type scale following the default guidance of The Elements of Typographic Style with intentional weights, widths, and spacing. When type is used as a headline or visual element, use the type treatment itself as an active part of the design, not a neutral delivery vehicle for the content.\n\nDefault to line lengths of less than 80 characters. Serif typefaces can have slightly longer line lengths; give serif body text slightly more line-height than a sans-serif.\n\nAvoid these default typographic treatments; they are the commonest tells of a generated page:\n- Accenting just a single word or phrase in a headline, like putting one word in italic/bold or a different color.\n- Using all caps for labels.\n- Adding unnecessary typographic labels above content.\n\nVisual structure is information. Structural devices like outlines, borders, numbering, eyebrows, dividers, labels, etc., encode useful information about the content rather than decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence — like a stepped process or a timeline. Before adding numbered markers, check the content really is a sequence.\n\nUse non-user-triggered motion sparingly and deliberately, only to draw attention. A single orchestrated moment — one page-load sequence or one reveal — lands better than scattered effects; fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as AI-generated. Motion that answers a person's action (opening, expanding, confirming) is welcome when it shows what changed.\n\nConsider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy and placeholder content. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.\n\n## Process: plan, review against the brief, build, critique\n\nFor calibration, AI-generated design right now clusters around some traits:\n1. a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta or warm-clay accent (often near #D97757 — Anthropic's own Claude-interaction accent, so on a user's brief it reads as a tell);\n2. a near-black background with a single bright acid-green or vermilion accent;\n3. a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns;\n4. the SaaS-card kit: content chopped into identical rounded cards, one border-radius on everything regardless of hierarchy, the same soft grey shadow (rgba(0,0,0,.1)) under each, and gradient washes as decoration;\n5. template chrome that appears whatever the subject: a tracked-out ALL-CAPS eyebrow label above every heading; meta strings joined with middle dots ('A · B · C'); labels built as 'WORD — fragment' with a spaced em dash; tinted near-black (#0B0B0B, #111) standing in for black; a monospace face for small data labels; a '→' appended to link and button text.\n\nAll traits are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. As with a hired human designer, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.\n\nWork in two passes. First, brainstorm a short design plan based on the client's design brief: create a compact token system with color, type, layout, and principles.\n- Color: describe the core base palette as 4–6 named hex values.\n- Type: the typefaces and their roles.\n- Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Include alignment guidance; should the content be left aligned, center aligned, justified?\n- Principles: the high-level guidance for what makes this page unique.\n\nThen review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan.\n\nWhen writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and an element-based selector like .cta). This can happen often with padding/margin between sections.\n\n## Restraint and self-critique\n\nSpend your boldness in one place. Let one element be the memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected, visually accessible, harmonious color palettes. Critique your own work as you build, taking screenshots to review if your environment supports it — a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creatives have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.\n\n## More on writing in design\n\nWords appear in a design for one reason: to make it easier to understand and use. They are design content, not decoration. Bring the same intentionality and minimalism to copywriting that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.\n\nWrite from the end user's perspective. Name things by what users will understand in simple language, not by how the system is built. A user manages notifications, not webhook config. Describe what something is or does in plain terms rather than selling it. Being specific and legible to new users is always better than being clever.\n\nUse active voice as default. A CTA says exactly what happens when it is used: \"Save changes,\" not \"Submit.\" An action keeps the same name through the whole flow, so the button that says \"Publish\" produces a toast that says \"Published.\" The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.\n\nTreat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.\n\nKeep the tone conversational: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each written element do exactly one job.\n\n\n---\nname: Writing Hookify Rules\ndescription: This skill should be used when the user asks to \"create a hookify rule\", \"write a hook rule\", \"configure hookify\", \"add a hookify rule\", or needs guidance on hookify rule syntax and patterns.\nversion: 0.1.0\n---\n\n# Writing Hookify Rules\n\n## Overview\n\nHookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to show when those patterns match. Rules are stored in `.claude/hookify.{rule-name}.local.md` files.\n\n## Rule File Format\n\n### Basic Structure\n\n```markdown\n---\nname: rule-identifier\nenabled: true\nevent: bash|file|stop|prompt|all\npattern: regex-pattern-here\n---\n\nMessage to show Claude when this rule triggers.\nCan include markdown formatting, warnings, suggestions, etc.\n```\n\n### Frontmatter Fields\n\n**name** (required): Unique identifier for the rule\n- Use kebab-case: `warn-dangerous-rm`, `block-console-log`\n- Be descriptive and action-oriented\n- Start with verb: warn, prevent, block, require, check\n\n**enabled** (required): Boolean to activate/deactivate\n- `true`: Rule is active\n- `false`: Rule is disabled (won't trigger)\n- Can toggle without deleting rule\n\n**event** (required): Which hook event to trigger on\n- `bash`: Bash tool commands\n- `file`: Edit, Write, MultiEdit tools\n- `stop`: When agent wants to stop\n- `prompt`: When user submits a prompt\n- `all`: All events\n\n**action** (optional): What to do when rule matches\n- `warn`: Show message but allow operation (default)\n- `block`: Prevent operation (PreToolUse) or stop session (Stop events)\n- If omitted, defaults to `warn`\n\n**pattern** (simple format): Regex pattern to match\n- Used for simple single-condition rules\n- Matches against command (bash) or new_text (file)\n- Python regex syntax\n\n**Example:**\n```yaml\nevent: bash\npattern: rm\\s+-rf\n```\n\n### Advanced Format (Multiple Conditions)\n\nFor complex rules with multiple conditions:\n\n```markdown\n---\nname: warn-env-file-edits\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.env$\n - field: new_text\n operator: contains\n pattern: API_KEY\n---\n\nYou're adding an API key to a .env file. Ensure this file is in .gitignore!\n```\n\n**Condition fields:**\n- `field`: Which field to check\n - For bash: `command`\n - For file: `file_path`, `new_text`, `old_text`, `content`\n- `operator`: How to match\n - `regex_match`: Regex pattern matching\n - `contains`: Substring check\n - `equals`: Exact match\n - `not_contains`: Substring must NOT be present\n - `starts_with`: Prefix check\n - `ends_with`: Suffix check\n- `pattern`: Pattern or string to match\n\n**All conditions must match for rule to trigger.**\n\n## Message Body\n\nThe markdown content after frontmatter is shown to Claude when the rule triggers.\n\n**Good messages:**\n- Explain what was detected\n- Explain why it's problematic\n- Suggest alternatives or best practices\n- Use formatting for clarity (bold, lists, etc.)\n\n**Example:**\n```markdown\n⚠️ **Console.log detected!**\n\nYou're adding console.log to production code.\n\n**Why this matters:**\n- Debug logs shouldn't ship to production\n- Console.log can expose sensitive data\n- Impacts browser performance\n\n**Alternatives:**\n- Use a proper logging library\n- Remove before committing\n- Use conditional debug builds\n```\n\n## Event Type Guide\n\n### bash Events\n\nMatch Bash command patterns:\n\n```markdown\n---\nevent: bash\npattern: sudo\\s+|rm\\s+-rf|chmod\\s+777\n---\n\nDangerous command detected!\n```\n\n**Common patterns:**\n- Dangerous commands: `rm\\s+-rf`, `dd\\s+if=`, `mkfs`\n- Privilege escalation: `sudo\\s+`, `su\\s+`\n- Permission issues: `chmod\\s+777`, `chown\\s+root`\n\n### file Events\n\nMatch Edit/Write/MultiEdit operations:\n\n```markdown\n---\nevent: file\npattern: console\\.log\\(|eval\\(|innerHTML\\s*=\n---\n\nPotentially problematic code pattern detected!\n```\n\n**Match on different fields:**\n```markdown\n---\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.tsx?$\n - field: new_text\n operator: regex_match\n pattern: console\\.log\\(\n---\n\nConsole.log in TypeScript file!\n```\n\n**Common patterns:**\n- Debug code: `console\\.log\\(`, `debugger`, `print\\(`\n- Security risks: `eval\\(`, `innerHTML\\s*=`, `dangerouslySetInnerHTML`\n- Sensitive files: `\\.env$`, `credentials`, `\\.pem$`\n- Generated files: `node_modules/`, `dist/`, `build/`\n\n### stop Events\n\nMatch when agent wants to stop (completion checks):\n\n```markdown\n---\nevent: stop\npattern: .*\n---\n\nBefore stopping, verify:\n- [ ] Tests were run\n- [ ] Build succeeded\n- [ ] Documentation updated\n```\n\n**Use for:**\n- Reminders about required steps\n- Completion checklists\n- Process enforcement\n\n### prompt Events\n\nMatch user prompt content (advanced):\n\n```markdown\n---\nevent: prompt\nconditions:\n - field: user_prompt\n operator: contains\n pattern: deploy to production\n---\n\nProduction deployment checklist:\n- [ ] Tests passing?\n- [ ] Reviewed by team?\n- [ ] Monitoring ready?\n```\n\n## Pattern Writing Tips\n\n### Regex Basics\n\n**Literal characters:** Most characters match themselves\n- `rm` matches \"rm\"\n- `console.log` matches \"console.log\"\n\n**Special characters need escaping:**\n- `.` (any char) → `\\.` (literal dot)\n- `(` `)` → `\\(` `\\)` (literal parens)\n- `[` `]` → `\\[` `\\]` (literal brackets)\n\n**Common metacharacters:**\n- `\\s` - whitespace (space, tab, newline)\n- `\\d` - digit (0-9)\n- `\\w` - word character (a-z, A-Z, 0-9, _)\n- `.` - any character\n- `+` - one or more\n- `*` - zero or more\n- `?` - zero or one\n- `|` - OR\n\n**Examples:**\n```\nrm\\s+-rf Matches: rm -rf, rm -rf\nconsole\\.log\\( Matches: console.log(\n(eval|exec)\\( Matches: eval( or exec(\nchmod\\s+777 Matches: chmod 777, chmod 777\nAPI_KEY\\s*= Matches: API_KEY=, API_KEY =\n```\n\n### Testing Patterns\n\nTest regex patterns before using:\n\n```bash\npython3 -c \"import re; print(re.search(r'your_pattern', 'test text'))\"\n```\n\nOr use online regex testers (regex101.com with Python flavor).\n\n### Common Pitfalls\n\n**Too broad:**\n```yaml\npattern: log # Matches \"log\", \"login\", \"dialog\", \"catalog\"\n```\nBetter: `console\\.log\\(|logger\\.`\n\n**Too specific:**\n```yaml\npattern: rm -rf /tmp # Only matches exact path\n```\nBetter: `rm\\s+-rf`\n\n**Escaping issues:**\n- YAML quoted strings: `\"pattern\"` requires double backslashes `\\\\s`\n- YAML unquoted: `pattern: \\s` works as-is\n- **Recommendation**: Use unquoted patterns in YAML\n\n## File Organization\n\n**Location:** All rules in `.claude/` directory\n**Naming:** `.claude/hookify.{descriptive-name}.local.md`\n**Gitignore:** Add `.claude/*.local.md` to `.gitignore`\n\n**Good names:**\n- `hookify.dangerous-rm.local.md`\n- `hookify.console-log.local.md`\n- `hookify.require-tests.local.md`\n- `hookify.sensitive-files.local.md`\n\n**Bad names:**\n- `hookify.rule1.local.md` (not descriptive)\n- `hookify.md` (missing .local)\n- `danger.local.md` (missing hookify prefix)\n\n## Workflow\n\n### Creating a Rule\n\n1. Identify unwanted behavior\n2. Determine which tool is involved (Bash, Edit, etc.)\n3. Choose event type (bash, file, stop, etc.)\n4. Write regex pattern\n5. Create `.claude/hookify.{name}.local.md` file in project root\n6. Test immediately - rules are read dynamically on next tool use\n\n### Refining a Rule\n\n1. Edit the `.local.md` file\n2. Adjust pattern or message\n3. Test immediately - changes take effect on next tool use\n\n### Disabling a Rule\n\n**Temporary:** Set `enabled: false` in frontmatter\n**Permanent:** Delete the `.local.md` file\n\n## Examples\n\nSee `${CLAUDE_PLUGIN_ROOT}/examples/` for complete examples:\n- `dangerous-rm.local.md` - Block dangerous rm commands\n- `console-log-warning.local.md` - Warn about console.log\n- `sensitive-files-warning.local.md` - Warn about editing .env files\n\n## Quick Reference\n\n**Minimum viable rule:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: bash\npattern: dangerous_command\n---\n\nWarning message here\n```\n\n**Rule with conditions:**\n```markdown\n---\nname: my-rule\nenabled: true\nevent: file\nconditions:\n - field: file_path\n operator: regex_match\n pattern: \\.ts$\n - field: new_text\n operator: contains\n pattern: any\n---\n\nWarning message\n```\n\n**Event types:**\n- `bash` - Bash commands\n- `file` - File edits\n- `stop` - Completion checks\n- `prompt` - User input\n- `all` - All events\n\n**Field options:**\n- Bash: `command`\n- File: `file_path`, `new_text`, `old_text`, `content`\n- Prompt: `user_prompt`\n\n**Operators:**\n- `regex_match`, `contains`, `equals`, `not_contains`, `starts_with`, `ends_with`\n\n\n# AI-Assisted Agent Generation Template\n\nUse this template to generate agents using Claude with the agent creation system prompt.\n\n## Usage Pattern\n\n### Step 1: Describe Your Agent Need\n\nThink about:\n- What task should the agent handle?\n- When should it be triggered?\n- Should it be proactive or reactive?\n- What are the key responsibilities?\n\n### Step 2: Use the Generation Prompt\n\nSend this to Claude (with the agent-creation-system-prompt loaded):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nReturn ONLY the JSON object, no other text.\n```\n\n**Replace [YOUR DESCRIPTION] with your agent requirements.**\n\n### Step 3: Claude Returns JSON\n\nClaude will return:\n\n```json\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are... **Your Core Responsibilities:**...\"\n}\n```\n\n### Step 4: Convert to Agent File\n\nCreate `agents/[identifier].md`:\n\n```markdown\n---\nname: [identifier from JSON]\ndescription: [whenToUse from JSON]\nmodel: inherit\ncolor: [choose: blue/cyan/green/yellow/magenta/red]\ntools: [\"Read\", \"Write\", \"Grep\"] # Optional: restrict tools\n---\n\n[systemPrompt from JSON]\n```\n\n## Example 1: Code Review Agent\n\n**Your request:**\n```\nI need an agent that reviews code changes for quality issues, security vulnerabilities, and adherence to best practices. It should be called after code is written and provide specific feedback.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"code-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\\n\\n\\nContext: User just implemented a new feature\\nuser: \\\"I've added the authentication feature\\\"\\nassistant: \\\"Great! Let me review the code quality.\\\"\\n\\nCode was written, trigger code-quality-reviewer agent for review.\\n\\nassistant: \\\"I'll use the code-quality-reviewer agent to analyze the changes.\\\"\\n\\n\\n\\nContext: User explicitly requests review\\nuser: \\\"Can you review my code for issues?\\\"\\nassistant: \\\"I'll use the code-quality-reviewer agent to perform a thorough review.\\\"\\n\\nExplicit review request triggers the agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer specializing in identifying issues in software implementations.\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues (readability, maintainability, performance)\\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\\n3. Check adherence to project best practices and coding standards\\n4. Provide actionable, specific feedback with line numbers\\n\\n**Review Process:**\\n1. Read the code changes using available tools\\n2. Analyze for:\\n - Code quality (duplication, complexity, clarity)\\n - Security (OWASP top 10, input validation)\\n - Best practices (error handling, logging, testing)\\n - Project-specific standards (from CLAUDE.md)\\n3. Identify issues with severity (critical/major/minor)\\n4. Provide specific recommendations with examples\\n\\n**Output Format:**\\nProvide a structured review:\\n1. Summary (2-3 sentences)\\n2. Critical Issues (must fix)\\n3. Major Issues (should fix)\\n4. Minor Issues (nice to fix)\\n5. Positive observations\\n6. Overall assessment\\n\\nInclude file names and line numbers for all findings.\"\n}\n```\n\n**You create:**\n\nFile: `agents/code-quality-reviewer.md`\n\n```markdown\n---\nname: code-quality-reviewer\ndescription: Use this agent when the user has written code and needs quality review, or explicitly asks to review code changes. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the authentication feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode was written, trigger code-quality-reviewer agent for review.\n\nassistant: \"I'll use the code-quality-reviewer agent to analyze the changes.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-quality-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, performance)\n2. Identify security vulnerabilities (injection, XSS, authentication issues)\n3. Check adherence to project best practices and coding standards\n4. Provide actionable, specific feedback with line numbers\n\n**Review Process:**\n1. Read the code changes using available tools\n2. Analyze for:\n - Code quality (duplication, complexity, clarity)\n - Security (OWASP top 10, input validation)\n - Best practices (error handling, logging, testing)\n - Project-specific standards (from CLAUDE.md)\n3. Identify issues with severity (critical/major/minor)\n4. Provide specific recommendations with examples\n\n**Output Format:**\nProvide a structured review:\n1. Summary (2-3 sentences)\n2. Critical Issues (must fix)\n3. Major Issues (should fix)\n4. Minor Issues (nice to fix)\n5. Positive observations\n6. Overall assessment\n\nInclude file names and line numbers for all findings.\n```\n\n## Example 2: Test Generation Agent\n\n**Your request:**\n```\nCreate an agent that generates unit tests for code. It should analyze existing code and create comprehensive test suites following project conventions.\n```\n\n**Claude generates:**\n```json\n{\n \"identifier\": \"test-generator\",\n \"whenToUse\": \"Use this agent when the user asks to generate tests, needs test coverage, or has written code that needs testing. Examples:\\n\\n\\nContext: User wrote new functions without tests\\nuser: \\\"I've implemented the user authentication functions\\\"\\nassistant: \\\"Great! Let me generate tests for these functions.\\\"\\n\\nNew code without tests, proactively trigger test-generator.\\n\\nassistant: \\\"I'll use the test-generator agent to create comprehensive tests.\\\"\\n\",\n \"systemPrompt\": \"You are an expert test engineer specializing in creating comprehensive unit tests...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code to understand behavior\\n2. Generate test cases covering happy paths and edge cases\\n3. Follow project testing conventions\\n4. Ensure high code coverage\\n\\n**Test Generation Process:**\\n1. Read target code\\n2. Identify testable units (functions, classes, methods)\\n3. Design test cases (inputs, expected outputs, edge cases)\\n4. Generate tests following project patterns\\n5. Add assertions and error cases\\n\\n**Output Format:**\\nGenerate complete test files with:\\n- Test suite structure\\n- Setup/teardown if needed\\n- Descriptive test names\\n- Comprehensive assertions\"\n}\n```\n\n**You create:** `agents/test-generator.md` with the structure above.\n\n## Example 3: Documentation Agent\n\n**Your request:**\n```\nBuild an agent that writes and updates API documentation. It should analyze code and generate clear, comprehensive docs.\n```\n\n**Result:** Agent file with identifier `api-docs-writer`, appropriate examples, and system prompt for documentation generation.\n\n## Tips for Effective Agent Generation\n\n### Be Specific in Your Request\n\n**Vague:**\n```\n\"I need an agent that helps with code\"\n```\n\n**Specific:**\n```\n\"I need an agent that reviews pull requests for type safety issues in TypeScript, checking for proper type annotations, avoiding 'any', and ensuring correct generic usage\"\n```\n\n### Include Triggering Preferences\n\nTell Claude when the agent should activate:\n\n```\n\"Create an agent that generates tests. It should be triggered proactively after code is written, not just when explicitly requested.\"\n```\n\n### Mention Project Context\n\n```\n\"Create a code review agent. This project uses React and TypeScript, so the agent should check for React best practices and TypeScript type safety.\"\n```\n\n### Define Output Expectations\n\n```\n\"Create an agent that analyzes performance. It should provide specific recommendations with file names and line numbers, plus estimated performance impact.\"\n```\n\n## Validation After Generation\n\nAlways validate generated agents:\n\n```bash\n# Validate structure\n./scripts/validate-agent.sh agents/your-agent.md\n\n# Check triggering works\n# Test with scenarios from examples\n```\n\n## Iterating on Generated Agents\n\nIf generated agent needs improvement:\n\n1. Identify what's missing or wrong\n2. Manually edit the agent file\n3. Focus on:\n - Better examples in description\n - More specific system prompt\n - Clearer process steps\n - Better output format definition\n4. Re-validate\n5. Test again\n\n## Advantages of AI-Assisted Generation\n\n- **Comprehensive**: Claude includes edge cases and quality checks\n- **Consistent**: Follows proven patterns\n- **Fast**: Seconds vs manual writing\n- **Examples**: Auto-generates triggering examples\n- **Complete**: Provides full system prompt structure\n\n## When to Edit Manually\n\nEdit generated agents when:\n- Need very specific project patterns\n- Require custom tool combinations\n- Want unique persona or style\n- Integrating with existing agents\n- Need precise triggering conditions\n\nStart with generation, then refine manually for best results.\n\n\n# Complete Agent Examples\n\nFull, production-ready agent examples for common use cases. Use these as templates for your own agents.\n\n## Example 1: Code Review Agent\n\n**File:** `agents/code-reviewer.md`\n\n```markdown\n---\nname: code-reviewer\ndescription: Use this agent when the user has written code and needs quality review, security analysis, or best practices validation. Examples:\n\n\nContext: User just implemented a new feature\nuser: \"I've added the payment processing feature\"\nassistant: \"Great! Let me review the implementation.\"\n\nCode written for payment processing (security-critical). Proactively trigger\ncode-reviewer agent to check for security issues and best practices.\n\nassistant: \"I'll use the code-reviewer agent to analyze the payment code.\"\n\n\n\nContext: User explicitly requests code review\nuser: \"Can you review my code for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a comprehensive review.\"\n\nExplicit code review request triggers the agent.\n\n\n\n\nContext: Before committing code\nuser: \"I'm ready to commit these changes\"\nassistant: \"Let me review them first.\"\n\nBefore commit, proactively review code quality.\n\nassistant: \"I'll use the code-reviewer agent to validate the changes.\"\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert code quality reviewer specializing in identifying issues, security vulnerabilities, and opportunities for improvement in software implementations.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues (readability, maintainability, complexity)\n2. Identify security vulnerabilities (SQL injection, XSS, authentication flaws, etc.)\n3. Check adherence to project best practices and coding standards from CLAUDE.md\n4. Provide specific, actionable feedback with file and line number references\n5. Recognize and commend good practices\n\n**Code Review Process:**\n1. **Gather Context**: Use Glob to find recently modified files (git diff, git status)\n2. **Read Code**: Use Read tool to examine changed files\n3. **Analyze Quality**:\n - Check for code duplication (DRY principle)\n - Assess complexity and readability\n - Verify error handling\n - Check for proper logging\n4. **Security Analysis**:\n - Scan for injection vulnerabilities (SQL, command, XSS)\n - Check authentication and authorization\n - Verify input validation and sanitization\n - Look for hardcoded secrets or credentials\n5. **Best Practices**:\n - Follow project-specific standards from CLAUDE.md\n - Check naming conventions\n - Verify test coverage\n - Assess documentation\n6. **Categorize Issues**: Group by severity (critical/major/minor)\n7. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every issue includes file path and line number (e.g., `src/auth.ts:42`)\n- Issues categorized by severity with clear criteria\n- Recommendations are specific and actionable (not vague)\n- Include code examples in recommendations when helpful\n- Balance criticism with recognition of good practices\n\n**Output Format:**\n## Code Review Summary\n[2-3 sentence overview of changes and overall quality]\n\n## Critical Issues (Must Fix)\n- `src/file.ts:42` - [Issue description] - [Why critical] - [How to fix]\n\n## Major Issues (Should Fix)\n- `src/file.ts:15` - [Issue description] - [Impact] - [Recommendation]\n\n## Minor Issues (Consider Fixing)\n- `src/file.ts:88` - [Issue description] - [Suggestion]\n\n## Positive Observations\n- [Good practice 1]\n- [Good practice 2]\n\n## Overall Assessment\n[Final verdict and recommendations]\n\n**Edge Cases:**\n- No issues found: Provide positive validation, mention what was checked\n- Too many issues (>20): Group by type, prioritize top 10 critical/major\n- Unclear code intent: Note ambiguity and request clarification\n- Missing context (no CLAUDE.md): Apply general best practices\n- Large changeset: Focus on most impactful files first\n```\n\n## Example 2: Test Generator Agent\n\n**File:** `agents/test-generator.md`\n\n```markdown\n---\nname: test-generator\ndescription: Use this agent when the user has written code without tests, explicitly asks for test generation, or needs test coverage improvement. Examples:\n\n\nContext: User implemented functions without tests\nuser: \"I've added the data validation functions\"\nassistant: \"Let me generate tests for these.\"\n\nNew code without tests. Proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly requests tests\nuser: \"Generate unit tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: green\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n---\n\nYou are an expert test engineer specializing in creating comprehensive, maintainable unit tests that ensure code correctness and reliability.\n\n**Your Core Responsibilities:**\n1. Generate high-quality unit tests with excellent coverage\n2. Follow project testing conventions and patterns\n3. Include happy path, edge cases, and error scenarios\n4. Ensure tests are maintainable and clear\n\n**Test Generation Process:**\n1. **Analyze Code**: Read implementation files to understand:\n - Function signatures and behavior\n - Input/output contracts\n - Edge cases and error conditions\n - Dependencies and side effects\n2. **Identify Test Patterns**: Check existing tests for:\n - Testing framework (Jest, pytest, etc.)\n - File organization (test/ directory, *.test.ts, etc.)\n - Naming conventions\n - Setup/teardown patterns\n3. **Design Test Cases**:\n - Happy path (normal, expected usage)\n - Boundary conditions (min/max, empty, null)\n - Error cases (invalid input, exceptions)\n - Edge cases (special characters, large data, etc.)\n4. **Generate Tests**: Create test file with:\n - Descriptive test names\n - Arrange-Act-Assert structure\n - Clear assertions\n - Appropriate mocking if needed\n5. **Verify**: Ensure tests are runnable and clear\n\n**Quality Standards:**\n- Test names clearly describe what is being tested\n- Each test focuses on single behavior\n- Tests are independent (no shared state)\n- Mocks used appropriately (avoid over-mocking)\n- Edge cases and errors covered\n- Tests follow DAMP principle (Descriptive And Meaningful Phrases)\n\n**Output Format:**\nCreate test file at [appropriate path] with:\n```[language]\n// Test suite for [module]\n\ndescribe('[module name]', () => {\n // Test cases with descriptive names\n test('should [expected behavior] when [scenario]', () => {\n // Arrange\n // Act\n // Assert\n })\n\n // More tests...\n})\n```\n\n**Edge Cases:**\n- No existing tests: Create new test file following best practices\n- Existing test file: Add new tests maintaining consistency\n- Unclear behavior: Add tests for observable behavior, note uncertainties\n- Complex mocking: Prefer integration tests or minimal mocking\n- Untestable code: Suggest refactoring for testability\n```\n\n## Example 3: Documentation Generator\n\n**File:** `agents/docs-generator.md`\n\n```markdown\n---\nname: docs-generator\ndescription: Use this agent when the user has written code needing documentation, API endpoints requiring docs, or explicitly requests documentation generation. Examples:\n\n\nContext: User implemented new public API\nuser: \"I've added the user management API endpoints\"\nassistant: \"Let me document these endpoints.\"\n\nNew public API needs documentation. Proactively trigger docs-generator.\n\nassistant: \"I'll use the docs-generator agent to create API documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Generate docs for this module\"\nassistant: \"I'll use the docs-generator agent to create comprehensive documentation.\"\n\nExplicit documentation request triggers the agent.\n\n\n\nmodel: inherit\ncolor: cyan\ntools: [\"Read\", \"Write\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert technical writer specializing in creating clear, comprehensive documentation for software projects.\n\n**Your Core Responsibilities:**\n1. Generate accurate, clear documentation from code\n2. Follow project documentation standards\n3. Include examples and usage patterns\n4. Ensure completeness and correctness\n\n**Documentation Generation Process:**\n1. **Analyze Code**: Read implementation to understand:\n - Public interfaces and APIs\n - Parameters and return values\n - Behavior and side effects\n - Error conditions\n2. **Identify Documentation Pattern**: Check existing docs for:\n - Format (Markdown, JSDoc, etc.)\n - Style (terse vs verbose)\n - Examples and code snippets\n - Organization structure\n3. **Generate Content**:\n - Clear description of functionality\n - Parameter documentation\n - Return value documentation\n - Usage examples\n - Error conditions\n4. **Format**: Follow project conventions\n5. **Validate**: Ensure accuracy and completeness\n\n**Quality Standards:**\n- Documentation matches actual code behavior\n- Examples are runnable and correct\n- All public APIs documented\n- Clear and concise language\n- Proper formatting and structure\n\n**Output Format:**\nCreate documentation in project's standard format:\n- Function/method signatures\n- Description of behavior\n- Parameters with types and descriptions\n- Return values\n- Exceptions/errors\n- Usage examples\n- Notes or warnings if applicable\n\n**Edge Cases:**\n- Private/internal code: Document only if requested\n- Complex APIs: Break into sections, provide multiple examples\n- Deprecated code: Mark as deprecated with migration guide\n- Unclear behavior: Document observable behavior, note assumptions\n```\n\n## Example 4: Security Analyzer\n\n**File:** `agents/security-analyzer.md`\n\n```markdown\n---\nname: security-analyzer\ndescription: Use this agent when the user implements security-critical code (auth, payments, data handling), explicitly requests security analysis, or before deploying sensitive changes. Examples:\n\n\nContext: User implemented authentication logic\nuser: \"I've added JWT token validation\"\nassistant: \"Let me check the security.\"\n\nAuthentication code is security-critical. Proactively trigger security-analyzer.\n\nassistant: \"I'll use the security-analyzer agent to review for security vulnerabilities.\"\n\n\n\nContext: User requests security check\nuser: \"Check my code for security issues\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nExplicit security review request triggers the agent.\n\n\n\nmodel: inherit\ncolor: red\ntools: [\"Read\", \"Grep\", \"Glob\"]\n---\n\nYou are an expert security analyst specializing in identifying vulnerabilities and security issues in software implementations.\n\n**Your Core Responsibilities:**\n1. Identify security vulnerabilities (OWASP Top 10 and beyond)\n2. Analyze authentication and authorization logic\n3. Check input validation and sanitization\n4. Verify secure data handling and storage\n5. Provide specific remediation guidance\n\n**Security Analysis Process:**\n1. **Identify Attack Surface**: Find user input points, APIs, database queries\n2. **Check Common Vulnerabilities**:\n - Injection (SQL, command, XSS, etc.)\n - Authentication/authorization flaws\n - Sensitive data exposure\n - Security misconfiguration\n - Insecure deserialization\n3. **Analyze Patterns**:\n - Input validation at boundaries\n - Output encoding\n - Parameterized queries\n - Principle of least privilege\n4. **Assess Risk**: Categorize by severity and exploitability\n5. **Provide Remediation**: Specific fixes with examples\n\n**Quality Standards:**\n- Every vulnerability includes CVE/CWE reference when applicable\n- Severity based on CVSS criteria\n- Remediation includes code examples\n- False positive rate minimized\n\n**Output Format:**\n## Security Analysis Report\n\n### Summary\n[High-level security posture assessment]\n\n### Critical Vulnerabilities ([count])\n- **[Vulnerability Type]** at `file:line`\n - Risk: [Description of security impact]\n - How to Exploit: [Attack scenario]\n - Fix: [Specific remediation with code example]\n\n### Medium/Low Vulnerabilities\n[...]\n\n### Security Best Practices Recommendations\n[...]\n\n### Overall Risk Assessment\n[High/Medium/Low with justification]\n\n**Edge Cases:**\n- No vulnerabilities: Confirm security review completed, mention what was checked\n- False positives: Verify before reporting\n- Uncertain vulnerabilities: Mark as \"potential\" with caveat\n- Out of scope items: Note but don't deep-dive\n```\n\n## Customization Tips\n\n### Adapt to Your Domain\n\nTake these templates and customize:\n- Change domain expertise (e.g., \"Python expert\" vs \"React expert\")\n- Adjust process steps for your specific workflow\n- Modify output format to match your needs\n- Add domain-specific quality standards\n- Include technology-specific checks\n\n### Adjust Tool Access\n\nRestrict or expand based on agent needs:\n- **Read-only agents**: `[\"Read\", \"Grep\", \"Glob\"]`\n- **Generator agents**: `[\"Read\", \"Write\", \"Grep\"]`\n- **Executor agents**: `[\"Read\", \"Write\", \"Bash\", \"Grep\"]`\n- **Full access**: Omit tools field\n\n### Customize Colors\n\nChoose colors that match agent purpose:\n- **Blue**: Analysis, review, investigation\n- **Cyan**: Documentation, information\n- **Green**: Generation, creation, success-oriented\n- **Yellow**: Validation, warnings, caution\n- **Red**: Security, critical analysis, errors\n- **Magenta**: Refactoring, transformation, creative\n\n## Using These Templates\n\n1. Copy template that matches your use case\n2. Replace placeholders with your specifics\n3. Customize process steps for your domain\n4. Adjust examples to your triggering scenarios\n5. Validate with `scripts/validate-agent.sh`\n6. Test triggering with real scenarios\n7. Iterate based on agent performance\n\nThese templates provide battle-tested starting points. Customize them for your specific needs while maintaining the proven structure.\n\n\n# Agent Creation System Prompt\n\nThis is the exact system prompt used by Claude Code's agent generation feature, refined through extensive production use.\n\n## The Prompt\n\n```\nYou are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.\n\n**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.\n\nWhen a user describes what they want an agent to do, you will:\n\n1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.\n\n2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.\n\n3. **Architect Comprehensive Instructions**: Develop a system prompt that:\n - Establishes clear behavioral boundaries and operational parameters\n - Provides specific methodologies and best practices for task execution\n - Anticipates edge cases and provides guidance for handling them\n - Incorporates any specific requirements or preferences mentioned by the user\n - Defines output format expectations when relevant\n - Aligns with project-specific coding standards and patterns from CLAUDE.md\n\n4. **Optimize for Performance**: Include:\n - Decision-making frameworks appropriate to the domain\n - Quality control mechanisms and self-verification steps\n - Efficient workflow patterns\n - Clear escalation or fallback strategies\n\n5. **Create Identifier**: Design a concise, descriptive identifier that:\n - Uses lowercase letters, numbers, and hyphens only\n - Is typically 2-4 words joined by hyphens\n - Clearly indicates the agent's primary function\n - Is memorable and easy to type\n - Avoids generic terms like \"helper\" or \"assistant\"\n\n6. **Example agent descriptions**:\n - In the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.\n - Examples should be of the form:\n \n Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.\n user: \"Please write a function that checks if a number is prime\"\n assistant: \"Here is the relevant function: \"\n \n \n Since a logical chunk of code was written and the task was completed, now use the code-review agent to review the code.\n \n assistant: \"Now let me use the code-reviewer agent to review the code\"\n \n - If the user mentioned or implied that the agent should be used proactively, you should include examples of this.\n - NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.\n\nYour output must be a valid JSON object with exactly these fields:\n{\n \"identifier\": \"A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')\",\n \"whenToUse\": \"A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.\",\n \"systemPrompt\": \"The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness\"\n}\n\nKey principles for your system prompts:\n- Be specific rather than generic - avoid vague instructions\n- Include concrete examples when they would clarify behavior\n- Balance comprehensiveness with clarity - every instruction should add value\n- Ensure the agent has enough context to handle variations of the core task\n- Make the agent proactive in seeking clarification when needed\n- Build in quality assurance and self-correction mechanisms\n\nRemember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.\n```\n\n## Usage Pattern\n\nUse this prompt to generate agent configurations:\n\n```markdown\n**User input:** \"I need an agent that reviews pull requests for code quality issues\"\n\n**You send to Claude with the system prompt above:**\nCreate an agent configuration based on this request: \"I need an agent that reviews pull requests for code quality issues\"\n\n**Claude returns JSON:**\n{\n \"identifier\": \"pr-quality-reviewer\",\n \"whenToUse\": \"Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\\n\\n\\nContext: User has created a PR and wants quality review\\nuser: \\\"Can you review PR #123 for code quality?\\\"\\nassistant: \\\"I'll use the pr-quality-reviewer agent to analyze the PR.\\\"\\n\\nPR review request triggers the pr-quality-reviewer agent.\\n\\n\",\n \"systemPrompt\": \"You are an expert code quality reviewer...\\n\\n**Your Core Responsibilities:**\\n1. Analyze code changes for quality issues\\n2. Check adherence to best practices\\n...\"\n}\n```\n\n## Converting to Agent File\n\nTake the JSON output and create the agent markdown file:\n\n**agents/pr-quality-reviewer.md:**\n```markdown\n---\nname: pr-quality-reviewer\ndescription: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Examples:\n\n\nContext: User has created a PR and wants quality review\nuser: \"Can you review PR #123 for code quality?\"\nassistant: \"I'll use the pr-quality-reviewer agent to analyze the PR.\"\n\nPR review request triggers the pr-quality-reviewer agent.\n\n\n\nmodel: inherit\ncolor: blue\n---\n\nYou are an expert code quality reviewer...\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n...\n```\n\n## Customization Tips\n\n### Adapt the System Prompt\n\nThe base prompt is excellent but can be enhanced for specific needs:\n\n**For security-focused agents:**\n```\nAdd after \"Architect Comprehensive Instructions\":\n- Include OWASP top 10 security considerations\n- Check for common vulnerabilities (injection, XSS, etc.)\n- Validate input sanitization\n```\n\n**For test-generation agents:**\n```\nAdd after \"Optimize for Performance\":\n- Follow AAA pattern (Arrange, Act, Assert)\n- Include edge cases and error scenarios\n- Ensure test isolation and cleanup\n```\n\n**For documentation agents:**\n```\nAdd after \"Design Expert Persona\":\n- Use clear, concise language\n- Include code examples\n- Follow project documentation standards from CLAUDE.md\n```\n\n## Best Practices from Internal Implementation\n\n### 1. Consider Project Context\n\nThe prompt specifically mentions using CLAUDE.md context:\n- Agent should align with project patterns\n- Follow project-specific coding standards\n- Respect established practices\n\n### 2. Proactive Agent Design\n\nInclude examples showing proactive usage:\n```\n\nContext: After writing code, agent should review proactively\nuser: \"Please write a function...\"\nassistant: \"[Writes function]\"\n\nCode written, now use review agent proactively.\n\nassistant: \"Now let me review this code with the code-reviewer agent\"\n\n```\n\n### 3. Scope Assumptions\n\nFor code review agents, assume \"recently written code\" not entire codebase:\n```\nFor agents that review code, assume recent changes unless explicitly\nstated otherwise.\n```\n\n### 4. Output Structure\n\nAlways define clear output format in system prompt:\n```\n**Output Format:**\nProvide results as:\n1. Summary (2-3 sentences)\n2. Detailed findings (bullet points)\n3. Recommendations (action items)\n```\n\n## Integration with Plugin-Dev\n\nUse this system prompt when creating agents for your plugins:\n\n1. Take user request for agent functionality\n2. Feed to Claude with this system prompt\n3. Get JSON output (identifier, whenToUse, systemPrompt)\n4. Convert to agent markdown file with frontmatter\n5. Validate with agent validation rules\n6. Test triggering conditions\n7. Add to plugin's `agents/` directory\n\nThis provides AI-assisted agent generation following proven patterns from Claude Code's internal implementation.\n\n\n# System Prompt Design Patterns\n\nComplete guide to writing effective agent system prompts that enable autonomous, high-quality operation.\n\n## Core Structure\n\nEvery agent system prompt should follow this proven structure:\n\n```markdown\nYou are [specific role] specializing in [specific domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility - the main task]\n2. [Secondary responsibility - supporting task]\n3. [Additional responsibilities as needed]\n\n**[Task Name] Process:**\n1. [First concrete step]\n2. [Second concrete step]\n3. [Continue with clear steps]\n[...]\n\n**Quality Standards:**\n- [Standard 1 with specifics]\n- [Standard 2 with specifics]\n- [Standard 3 with specifics]\n\n**Output Format:**\nProvide results structured as:\n- [Component 1]\n- [Component 2]\n- [Include specific formatting requirements]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [Specific handling approach]\n- [Edge case 2]: [Specific handling approach]\n```\n\n## Pattern 1: Analysis Agents\n\nFor agents that analyze code, PRs, or documentation:\n\n```markdown\nYou are an expert [domain] analyzer specializing in [specific analysis type].\n\n**Your Core Responsibilities:**\n1. Thoroughly analyze [what] for [specific issues]\n2. Identify [patterns/problems/opportunities]\n3. Provide actionable recommendations\n\n**Analysis Process:**\n1. **Gather Context**: Read [what] using available tools\n2. **Initial Scan**: Identify obvious [issues/patterns]\n3. **Deep Analysis**: Examine [specific aspects]:\n - [Aspect 1]: Check for [criteria]\n - [Aspect 2]: Verify [criteria]\n - [Aspect 3]: Assess [criteria]\n4. **Synthesize Findings**: Group related issues\n5. **Prioritize**: Rank by [severity/impact/urgency]\n6. **Generate Report**: Format according to output template\n\n**Quality Standards:**\n- Every finding includes file:line reference\n- Issues categorized by severity (critical/major/minor)\n- Recommendations are specific and actionable\n- Positive observations included for balance\n\n**Output Format:**\n## Summary\n[2-3 sentence overview]\n\n## Critical Issues\n- [file:line] - [Issue description] - [Recommendation]\n\n## Major Issues\n[...]\n\n## Minor Issues\n[...]\n\n## Recommendations\n[...]\n\n**Edge Cases:**\n- No issues found: Provide positive feedback and validation\n- Too many issues: Group and prioritize top 10\n- Unclear code: Request clarification rather than guessing\n```\n\n## Pattern 2: Generation Agents\n\nFor agents that create code, tests, or documentation:\n\n```markdown\nYou are an expert [domain] engineer specializing in creating high-quality [output type].\n\n**Your Core Responsibilities:**\n1. Generate [what] that meets [quality standards]\n2. Follow [specific conventions/patterns]\n3. Ensure [correctness/completeness/clarity]\n\n**Generation Process:**\n1. **Understand Requirements**: Analyze what needs to be created\n2. **Gather Context**: Read existing [code/docs/tests] for patterns\n3. **Design Structure**: Plan [architecture/organization/flow]\n4. **Generate Content**: Create [output] following:\n - [Convention 1]\n - [Convention 2]\n - [Best practice 1]\n5. **Validate**: Verify [correctness/completeness]\n6. **Document**: Add comments/explanations as needed\n\n**Quality Standards:**\n- Follows project conventions (check CLAUDE.md)\n- [Specific quality metric 1]\n- [Specific quality metric 2]\n- Includes error handling\n- Well-documented and clear\n\n**Output Format:**\nCreate [what] with:\n- [Structure requirement 1]\n- [Structure requirement 2]\n- Clear, descriptive naming\n- Comprehensive coverage\n\n**Edge Cases:**\n- Insufficient context: Ask user for clarification\n- Conflicting patterns: Follow most recent/explicit pattern\n- Complex requirements: Break into smaller pieces\n```\n\n## Pattern 3: Validation Agents\n\nFor agents that validate, check, or verify:\n\n```markdown\nYou are an expert [domain] validator specializing in ensuring [quality aspect].\n\n**Your Core Responsibilities:**\n1. Validate [what] against [criteria]\n2. Identify violations and issues\n3. Provide clear pass/fail determination\n\n**Validation Process:**\n1. **Load Criteria**: Understand validation requirements\n2. **Scan Target**: Read [what] needs validation\n3. **Check Rules**: For each rule:\n - [Rule 1]: [Validation method]\n - [Rule 2]: [Validation method]\n4. **Collect Violations**: Document each failure with details\n5. **Assess Severity**: Categorize issues\n6. **Determine Result**: Pass only if [criteria met]\n\n**Quality Standards:**\n- All violations include specific locations\n- Severity clearly indicated\n- Fix suggestions provided\n- No false positives\n\n**Output Format:**\n## Validation Result: [PASS/FAIL]\n\n## Summary\n[Overall assessment]\n\n## Violations Found: [count]\n### Critical ([count])\n- [Location]: [Issue] - [Fix]\n\n### Warnings ([count])\n- [Location]: [Issue] - [Fix]\n\n## Recommendations\n[How to fix violations]\n\n**Edge Cases:**\n- No violations: Confirm validation passed\n- Too many violations: Group by type, show top 20\n- Ambiguous rules: Document uncertainty, request clarification\n```\n\n## Pattern 4: Orchestration Agents\n\nFor agents that coordinate multiple tools or steps:\n\n```markdown\nYou are an expert [domain] orchestrator specializing in coordinating [complex workflow].\n\n**Your Core Responsibilities:**\n1. Coordinate [multi-step process]\n2. Manage [resources/tools/dependencies]\n3. Ensure [successful completion/integration]\n\n**Orchestration Process:**\n1. **Plan**: Understand full workflow and dependencies\n2. **Prepare**: Set up prerequisites\n3. **Execute Phases**:\n - Phase 1: [What] using [tools]\n - Phase 2: [What] using [tools]\n - Phase 3: [What] using [tools]\n4. **Monitor**: Track progress and handle failures\n5. **Verify**: Confirm successful completion\n6. **Report**: Provide comprehensive summary\n\n**Quality Standards:**\n- Each phase completes successfully\n- Errors handled gracefully\n- Progress reported to user\n- Final state verified\n\n**Output Format:**\n## Workflow Execution Report\n\n### Completed Phases\n- [Phase]: [Result]\n\n### Results\n- [Output 1]\n- [Output 2]\n\n### Next Steps\n[If applicable]\n\n**Edge Cases:**\n- Phase failure: Attempt retry, then report and stop\n- Missing dependencies: Request from user\n- Timeout: Report partial completion\n```\n\n## Writing Style Guidelines\n\n### Tone and Voice\n\n**Use second person (addressing the agent):**\n```\n✅ You are responsible for...\n✅ You will analyze...\n✅ Your process should...\n\n❌ The agent is responsible for...\n❌ This agent will analyze...\n❌ I will analyze...\n```\n\n### Clarity and Specificity\n\n**Be specific, not vague:**\n```\n✅ Check for SQL injection by examining all database queries for parameterization\n❌ Look for security issues\n\n✅ Provide file:line references for each finding\n❌ Show where issues are\n\n✅ Categorize as critical (security), major (bugs), or minor (style)\n❌ Rate the severity of issues\n```\n\n### Actionable Instructions\n\n**Give concrete steps:**\n```\n✅ Read the file using the Read tool, then search for patterns using Grep\n❌ Analyze the code\n\n✅ Generate test file at test/path/to/file.test.ts\n❌ Create tests\n```\n\n## Common Pitfalls\n\n### ❌ Vague Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Help the user with their code\n2. Provide assistance\n3. Be helpful\n```\n\n**Why bad:** Not specific enough to guide behavior.\n\n### ✅ Specific Responsibilities\n\n```markdown\n**Your Core Responsibilities:**\n1. Analyze TypeScript code for type safety issues\n2. Identify missing type annotations and improper 'any' usage\n3. Recommend specific type improvements with examples\n```\n\n### ❌ Missing Process Steps\n\n```markdown\nAnalyze the code and provide feedback.\n```\n\n**Why bad:** Agent doesn't know HOW to analyze.\n\n### ✅ Clear Process\n\n```markdown\n**Analysis Process:**\n1. Read code files using Read tool\n2. Scan for type annotations on all functions\n3. Check for 'any' type usage\n4. Verify generic type parameters\n5. List findings with file:line references\n```\n\n### ❌ Undefined Output\n\n```markdown\nProvide a report.\n```\n\n**Why bad:** Agent doesn't know what format to use.\n\n### ✅ Defined Output Format\n\n```markdown\n**Output Format:**\n## Type Safety Report\n\n### Summary\n[Overview of findings]\n\n### Issues Found\n- `file.ts:42` - Missing return type on `processData`\n- `utils.ts:15` - Unsafe 'any' usage in parameter\n\n### Recommendations\n[Specific fixes with examples]\n```\n\n## Length Guidelines\n\n### Minimum Viable Agent\n\n**~500 words minimum:**\n- Role description\n- 3 core responsibilities\n- 5-step process\n- Output format\n\n### Standard Agent\n\n**~1,000-2,000 words:**\n- Detailed role and expertise\n- 5-8 responsibilities\n- 8-12 process steps\n- Quality standards\n- Output format\n- 3-5 edge cases\n\n### Comprehensive Agent\n\n**~2,000-5,000 words:**\n- Complete role with background\n- Comprehensive responsibilities\n- Detailed multi-phase process\n- Extensive quality standards\n- Multiple output formats\n- Many edge cases\n- Examples within system prompt\n\n**Avoid > 10,000 words:** Too long, diminishing returns.\n\n## Testing System Prompts\n\n### Test Completeness\n\nCan the agent handle these based on system prompt alone?\n\n- [ ] Typical task execution\n- [ ] Edge cases mentioned\n- [ ] Error scenarios\n- [ ] Unclear requirements\n- [ ] Large/complex inputs\n- [ ] Empty/missing inputs\n\n### Test Clarity\n\nRead the system prompt and ask:\n\n- Can another developer understand what this agent does?\n- Are process steps clear and actionable?\n- Is output format unambiguous?\n- Are quality standards measurable?\n\n### Iterate Based on Results\n\nAfter testing agent:\n1. Identify where it struggled\n2. Add missing guidance to system prompt\n3. Clarify ambiguous instructions\n4. Add process steps for edge cases\n5. Re-test\n\n## Conclusion\n\nEffective system prompts are:\n- **Specific**: Clear about what and how\n- **Structured**: Organized with clear sections\n- **Complete**: Covers normal and edge cases\n- **Actionable**: Provides concrete steps\n- **Testable**: Defines measurable standards\n\nUse the patterns above as templates, customize for your domain, and iterate based on agent performance.\n\n\n# Agent Triggering Examples: Best Practices\n\nComplete guide to writing effective `` blocks in agent descriptions for reliable triggering.\n\n## Example Block Format\n\nThe standard format for triggering examples:\n\n```markdown\n\nContext: [Describe the situation - what led to this interaction]\nuser: \"[Exact user message or request]\"\nassistant: \"[How Claude should respond before triggering]\"\n\n[Explanation of why this agent should be triggered in this scenario]\n\nassistant: \"[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']\"\n\n```\n\n## Anatomy of a Good Example\n\n### Context\n\n**Purpose:** Set the scene - what happened before the user's message\n\n**Good contexts:**\n```\nContext: User just implemented a new authentication feature\nContext: User has created a PR and wants it reviewed\nContext: User is debugging a test failure\nContext: After writing several functions without documentation\n```\n\n**Bad contexts:**\n```\nContext: User needs help (too vague)\nContext: Normal usage (not specific)\n```\n\n### User Message\n\n**Purpose:** Show the exact phrasing that should trigger the agent\n\n**Good user messages:**\n```\nuser: \"I've added the OAuth flow, can you check it?\"\nuser: \"Review PR #123\"\nuser: \"Why is this test failing?\"\nuser: \"Add docs for these functions\"\n```\n\n**Vary the phrasing:**\nInclude multiple examples with different phrasings for the same intent:\n```\nExample 1: user: \"Review my code\"\nExample 2: user: \"Can you check this implementation?\"\nExample 3: user: \"Look over my changes\"\n```\n\n### Assistant Response (Before Triggering)\n\n**Purpose:** Show what Claude says before launching the agent\n\n**Good responses:**\n```\nassistant: \"I'll analyze your OAuth implementation.\"\nassistant: \"Let me review that PR for you.\"\nassistant: \"I'll investigate the test failure.\"\n```\n\n**Proactive example:**\n```\nassistant: \"Great! Now let me review the code quality.\"\n\nCode was just written, proactively trigger review agent.\n\n```\n\n### Commentary\n\n**Purpose:** Explain the reasoning - WHY this agent should trigger\n\n**Good commentary:**\n```\n\nUser explicitly requested code review, trigger the code-reviewer agent.\n\n\n\nAfter code implementation, proactively use review agent to check quality.\n\n\n\nPR analysis request matches pr-analyzer agent's expertise.\n\n```\n\n**Include decision logic:**\n```\n\nUser wrote tests (Test tool used). The test-analyzer agent should check\ntest quality and coverage before continuing.\n\n```\n\n### Assistant Response (Triggering)\n\n**Purpose:** Show how Claude invokes the agent\n\n**Standard pattern:**\n```\nassistant: \"I'll use the [agent-name] agent to [what it will do].\"\n```\n\n**Examples:**\n```\nassistant: \"I'll use the code-reviewer agent to analyze the changes.\"\nassistant: \"Let me use the test-generator agent to create comprehensive tests.\"\nassistant: \"I'll use the security-analyzer agent to check for vulnerabilities.\"\n```\n\n## Example Types\n\n### Type 1: Explicit Request\n\nUser directly asks for what the agent does:\n\n```markdown\n\nContext: User explicitly requests security analysis\nuser: \"Check my code for security vulnerabilities\"\nassistant: \"I'll use the security-analyzer agent to perform a thorough security review.\"\n\nDirect security analysis request triggers the security-analyzer agent.\n\n\n```\n\n### Type 2: Proactive Triggering\n\nAgent triggers after relevant work without explicit request:\n\n```markdown\n\nContext: User just implemented database queries\nuser: \"I've added the user search functionality\"\nassistant: \"Great! Let me review it for security.\"\n\nDatabase code written. Proactively trigger security-analyzer to check\nfor SQL injection and other database security issues.\n\nassistant: \"I'll use the security-analyzer agent to check the database code.\"\n\n```\n\n### Type 3: Implicit Request\n\nUser implies need without stating it directly:\n\n```markdown\n\nContext: User mentions code is hard to understand\nuser: \"This code is confusing and hard to follow\"\nassistant: \"I can help improve the code clarity.\"\n\nUser indicates complexity issues. Trigger code-simplifier agent to refactor\nfor better readability.\n\nassistant: \"I'll use the code-simplifier agent to suggest improvements.\"\n\n```\n\n### Type 4: Tool Usage Pattern\n\nAgent triggers based on prior tool usage:\n\n```markdown\n\nContext: User made multiple edits to test files\nuser: \"I've updated all the tests\"\nassistant: \"Great! Let me verify test quality.\"\n\nMultiple Edit tools used on test files. Proactively trigger test-quality-analyzer\nto ensure tests follow best practices.\n\nassistant: \"I'll use the test-quality-analyzer agent to review the tests.\"\n\n```\n\n## Multiple Examples Strategy\n\n### Cover Different Phrasings\n\n```markdown\n\nuser: \"Review my code\"\n[...]\n\n\n\nuser: \"Can you check my implementation?\"\n[...]\n\n\n\nuser: \"Look over these changes\"\n[...]\n\n```\n\n### Cover Proactive and Reactive\n\n```markdown\n\nContext: User explicitly requests review\nuser: \"Review my code for issues\"\n[...]\n\n\n\nContext: After user writes code\nuser: \"I've implemented the feature\"\nassistant: \"Great! Now let me review it.\"\n\nCode written, proactively review.\n\n[...]\n\n```\n\n### Cover Edge Cases\n\n```markdown\n\nContext: Typical usage\nuser: \"Check my PR\"\n[...]\n\n\n\nContext: Large PR that needs thorough analysis\nuser: \"This is a big PR, can you do a deep review?\"\n[...]\n\nLarge PR mentioned, use thorough analysis mode.\n\n\n```\n\n## Common Mistakes\n\n### ❌ Missing Context\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent.\"\n\n```\n\n**Why bad:** No context about what led to this request.\n\n### ✅ With Context\n\n```markdown\n\nContext: User just finished implementing authentication\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to analyze the auth implementation.\"\n\nAuth code written, review for security and best practices.\n\n\n```\n\n### ❌ No Commentary\n\n```markdown\n\nContext: User requests review\nuser: \"Check my changes\"\nassistant: \"I'll use the reviewer agent.\"\n\n```\n\n**Why bad:** Doesn't explain WHY agent triggers.\n\n### ✅ With Commentary\n\n```markdown\n\nContext: User requests review after making changes\nuser: \"Check my changes\"\nassistant: \"I'll use the code-reviewer agent to analyze the modifications.\"\n\nCode review request triggers agent to check quality, security, and adherence to standards.\n\n\n```\n\n### ❌ Agent Responds Directly\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I found the following issues: [lists issues]\"\n\n```\n\n**Why bad:** Shows agent's output, not triggering.\n\n### ✅ Shows Triggering\n\n```markdown\n\nuser: \"Review my code\"\nassistant: \"I'll use the code-reviewer agent to perform the review.\"\n\nReview request triggers the agent.\n\n\n```\n\n## How Many Examples?\n\n### Minimum: 2 Examples\n\nCover at least:\n1. Explicit request\n2. One variation or proactive trigger\n\n### Recommended: 3-4 Examples\n\nCover:\n1. Explicit request (direct ask)\n2. Implicit request (user implies need)\n3. Proactive trigger (after relevant work)\n4. Edge case or specific scenario\n\n### Maximum: 6 Examples\n\nMore than 6 makes description too long. Focus on most important scenarios.\n\n## Template Library\n\n### Code Review Agent\n\n```markdown\n\nContext: User just implemented a new feature\nuser: \"I've added the user registration feature\"\nassistant: \"Great! Let me review the code quality.\"\n\nCode written, proactively trigger code-reviewer agent.\n\nassistant: \"I'll use the code-reviewer agent to analyze the implementation.\"\n\n\n\nContext: User explicitly requests review\nuser: \"Can you review my changes for issues?\"\nassistant: \"I'll use the code-reviewer agent to perform a thorough review.\"\n\nExplicit review request triggers the agent.\n\n\n```\n\n### Test Generation Agent\n\n```markdown\n\nContext: User implemented functions without tests\nuser: \"I've added the data processing functions\"\nassistant: \"Great! Let me generate tests for these.\"\n\nNew code without tests, proactively trigger test-generator agent.\n\nassistant: \"I'll use the test-generator agent to create comprehensive tests.\"\n\n\n\nContext: User explicitly asks for tests\nuser: \"Generate tests for my code\"\nassistant: \"I'll use the test-generator agent to create a complete test suite.\"\n\nDirect test generation request triggers the agent.\n\n\n```\n\n### Documentation Agent\n\n```markdown\n\nContext: User added new API endpoints\nuser: \"I've implemented the REST API endpoints\"\nassistant: \"I'll document these endpoints.\"\n\nNew API code, proactively generate documentation.\n\nassistant: \"I'll use the api-docs-writer agent to create comprehensive documentation.\"\n\n\n\nContext: User requests documentation\nuser: \"Write docs for this API\"\nassistant: \"I'll use the api-docs-writer agent to generate clear documentation.\"\n\nDocumentation request triggers the agent.\n\n\n```\n\n### Validation Agent\n\n```markdown\n\nContext: User ready to commit changes\nuser: \"I'm ready to commit this code\"\nassistant: \"Let me validate it first.\"\n\nBefore commit, proactively validate with validation-agent.\n\nassistant: \"I'll use the code-validator agent to check for issues.\"\n\n\n\nContext: User asks for validation\nuser: \"Validate my implementation\"\nassistant: \"I'll use the code-validator agent to verify correctness.\"\n\nExplicit validation request triggers the agent.\n\n\n```\n\n## Debugging Triggering Issues\n\n### Agent Not Triggering\n\n**Check:**\n1. Examples include relevant keywords from user message\n2. Context matches actual usage scenarios\n3. Commentary explains triggering logic clearly\n4. Assistant shows use of Agent tool in examples\n\n**Fix:**\nAdd more examples covering different phrasings.\n\n### Agent Triggers Too Often\n\n**Check:**\n1. Examples are too broad or generic\n2. Triggering conditions overlap with other agents\n3. Commentary doesn't distinguish when NOT to use\n\n**Fix:**\nMake examples more specific, add negative examples.\n\n### Agent Triggers in Wrong Scenarios\n\n**Check:**\n1. Examples don't match actual intended use\n2. Commentary suggests inappropriate triggering\n\n**Fix:**\nRevise examples to show only correct triggering scenarios.\n\n## Best Practices Summary\n\n✅ **DO:**\n- Include 2-4 concrete, specific examples\n- Show both explicit and proactive triggering\n- Provide clear context for each example\n- Explain reasoning in commentary\n- Vary user message phrasing\n- Show Claude using Agent tool\n\n❌ **DON'T:**\n- Use generic, vague examples\n- Omit context or commentary\n- Show only one type of triggering\n- Skip the agent invocation step\n- Make examples too similar\n- Forget to explain why agent triggers\n\n## Conclusion\n\nWell-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.\n\n\n---\nname: Agent Development\ndescription: This skill should be used when the user asks to \"create an agent\", \"add an agent\", \"write a subagent\", \"agent frontmatter\", \"when to use description\", \"agent examples\", \"agent tools\", \"agent colors\", \"autonomous agent\", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.\nversion: 0.1.0\n---\n\n# Agent Development for Claude Code Plugins\n\n## Overview\n\nAgents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.\n\n**Key concepts:**\n- Agents are FOR autonomous work, commands are FOR user-initiated actions\n- Markdown file format with YAML frontmatter\n- Triggering via description field with examples\n- System prompt defines agent behavior\n- Model and color customization\n\n## Agent File Structure\n\n### Complete Format\n\n```markdown\n---\nname: agent-identifier\ndescription: Use this agent when [triggering conditions]. Examples:\n\n\nContext: [Situation description]\nuser: \"[User request]\"\nassistant: \"[How assistant should respond and use this agent]\"\n\n[Why this agent should be triggered]\n\n\n\n\n[Additional example...]\n\n\nmodel: inherit\ncolor: blue\ntools: [\"Read\", \"Write\", \"Grep\"]\n---\n\nYou are [agent role description]...\n\n**Your Core Responsibilities:**\n1. [Responsibility 1]\n2. [Responsibility 2]\n\n**Analysis Process:**\n[Step-by-step workflow]\n\n**Output Format:**\n[What to return]\n```\n\n## Frontmatter Fields\n\n### name (required)\n\nAgent identifier used for namespacing and invocation.\n\n**Format:** lowercase, numbers, hyphens only\n**Length:** 3-50 characters\n**Pattern:** Must start and end with alphanumeric\n\n**Good examples:**\n- `code-reviewer`\n- `test-generator`\n- `api-docs-writer`\n- `security-analyzer`\n\n**Bad examples:**\n- `helper` (too generic)\n- `-agent-` (starts/ends with hyphen)\n- `my_agent` (underscores not allowed)\n- `ag` (too short, < 3 chars)\n\n### description (required)\n\nDefines when Claude should trigger this agent. **This is the most critical field.**\n\n**Must include:**\n1. Triggering conditions (\"Use this agent when...\")\n2. Multiple `` blocks showing usage\n3. Context, user request, and assistant response in each example\n4. `` explaining why agent triggers\n\n**Format:**\n```\nUse this agent when [conditions]. Examples:\n\n\nContext: [Scenario description]\nuser: \"[What user says]\"\nassistant: \"[How Claude should respond]\"\n\n[Why this agent is appropriate]\n\n\n\n[More examples...]\n```\n\n**Best practices:**\n- Include 2-4 concrete examples\n- Show proactive and reactive triggering\n- Cover different phrasings of same intent\n- Explain reasoning in commentary\n- Be specific about when NOT to use the agent\n\n### model (required)\n\nWhich model the agent should use.\n\n**Options:**\n- `inherit` - Use same model as parent (recommended)\n- `sonnet` - Claude Sonnet (balanced)\n- `opus` - Claude Opus (most capable, expensive)\n- `haiku` - Claude Haiku (fast, cheap)\n\n**Recommendation:** Use `inherit` unless agent needs specific model capabilities.\n\n### color (required)\n\nVisual identifier for agent in UI.\n\n**Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`\n\n**Guidelines:**\n- Choose distinct colors for different agents in same plugin\n- Use consistent colors for similar agent types\n- Blue/cyan: Analysis, review\n- Green: Success-oriented tasks\n- Yellow: Caution, validation\n- Red: Critical, security\n- Magenta: Creative, generation\n\n### tools (optional)\n\nRestrict agent to specific tools.\n\n**Format:** Array of tool names\n\n```yaml\ntools: [\"Read\", \"Write\", \"Grep\", \"Bash\"]\n```\n\n**Default:** If omitted, agent has access to all tools\n\n**Best practice:** Limit tools to minimum needed (principle of least privilege)\n\n**Common tool sets:**\n- Read-only analysis: `[\"Read\", \"Grep\", \"Glob\"]`\n- Code generation: `[\"Read\", \"Write\", \"Grep\"]`\n- Testing: `[\"Read\", \"Bash\", \"Grep\"]`\n- Full access: Omit field or use `[\"*\"]`\n\n## System Prompt Design\n\nThe markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.\n\n### Structure\n\n**Standard template:**\n```markdown\nYou are [role] specializing in [domain].\n\n**Your Core Responsibilities:**\n1. [Primary responsibility]\n2. [Secondary responsibility]\n3. [Additional responsibilities...]\n\n**Analysis Process:**\n1. [Step one]\n2. [Step two]\n3. [Step three]\n[...]\n\n**Quality Standards:**\n- [Standard 1]\n- [Standard 2]\n\n**Output Format:**\nProvide results in this format:\n- [What to include]\n- [How to structure]\n\n**Edge Cases:**\nHandle these situations:\n- [Edge case 1]: [How to handle]\n- [Edge case 2]: [How to handle]\n```\n\n### Best Practices\n\n✅ **DO:**\n- Write in second person (\"You are...\", \"You will...\")\n- Be specific about responsibilities\n- Provide step-by-step process\n- Define output format\n- Include quality standards\n- Address edge cases\n- Keep under 10,000 characters\n\n❌ **DON'T:**\n- Write in first person (\"I am...\", \"I will...\")\n- Be vague or generic\n- Omit process steps\n- Leave output format undefined\n- Skip quality guidance\n- Ignore error cases\n\n## Creating Agents\n\n### Method 1: AI-Assisted Generation\n\nUse this prompt pattern (extracted from Claude Code):\n\n```\nCreate an agent configuration based on this request: \"[YOUR DESCRIPTION]\"\n\nRequirements:\n1. Extract core intent and responsibilities\n2. Design expert persona for the domain\n3. Create comprehensive system prompt with:\n - Clear behavioral boundaries\n - Specific methodologies\n - Edge case handling\n - Output format\n4. Create identifier (lowercase, hyphens, 3-50 chars)\n5. Write description with triggering conditions\n6. Include 2-3 blocks showing when to use\n\nReturn JSON with:\n{\n \"identifier\": \"agent-name\",\n \"whenToUse\": \"Use this agent when... Examples: ...\",\n \"systemPrompt\": \"You are...\"\n}\n```\n\nThen convert to agent file format with frontmatter.\n\nSee `examples/agent-creation-prompt.md` for complete template.\n\n### Method 2: Manual Creation\n\n1. Choose agent identifier (3-50 chars, lowercase, hyphens)\n2. Write description with examples\n3. Select model (usually `inherit`)\n4. Choose color for visual identification\n5. Define tools (if restricting access)\n6. Write system prompt with structure above\n7. Save as `agents/agent-name.md`\n\n## Validation Rules\n\n### Identifier Validation\n\n```\n✅ Valid: code-reviewer, test-gen, api-analyzer-v2\n❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)\n```\n\n**Rules:**\n- 3-50 characters\n- Lowercase letters, numbers, hyphens only\n- Must start and end with alphanumeric\n- No underscores, spaces, or special characters\n\n### Description Validation\n\n**Length:** 10-5,000 characters\n**Must include:** Triggering conditions and examples\n**Best:** 200-1,000 characters with 2-4 examples\n\n### System Prompt Validation\n\n**Length:** 20-10,000 characters\n**Best:** 500-3,000 characters\n**Structure:** Clear responsibilities, process, output format\n\n## Agent Organization\n\n### Plugin Agents Directory\n\n```\nplugin-name/\n└── agents/\n ├── analyzer.md\n ├── reviewer.md\n └── generator.md\n```\n\nAll `.md` files in `agents/` are auto-discovered.\n\n### Namespacing\n\nAgents are namespaced automatically:\n- Single plugin: `agent-name`\n- With subdirectories: `plugin:subdir:agent-name`\n\n## Testing Agents\n\n### Test Triggering\n\nCreate test scenarios to verify agent triggers correctly:\n\n1. Write agent with specific triggering examples\n2. Use similar phrasing to examples in test\n3. Check Claude loads the agent\n4. Verify agent provides expected functionality\n\n### Test System Prompt\n\nEnsure system prompt is complete:\n\n1. Give agent typical task\n2. Check it follows process steps\n3. Verify output format is correct\n4. Test edge cases mentioned in prompt\n5. Confirm quality standards are met\n\n## Quick Reference\n\n### Minimal Agent\n\n```markdown\n---\nname: simple-agent\ndescription: Use this agent when... Examples: ...\nmodel: inherit\ncolor: blue\n---\n\nYou are an agent that [does X].\n\nProcess:\n1. [Step 1]\n2. [Step 2]\n\nOutput: [What to provide]\n```\n\n### Frontmatter Fields Summary\n\n| Field | Required | Format | Example |\n|-------|----------|--------|---------|\n| name | Yes | lowercase-hyphens | code-reviewer |\n| description | Yes | Text + examples | Use when... ... |\n| model | Yes | inherit/sonnet/opus/haiku | inherit |\n| color | Yes | Color name | blue |\n| tools | No | Array of tool names | [\"Read\", \"Grep\"] |\n\n### Best Practices\n\n**DO:**\n- ✅ Include 2-4 concrete examples in description\n- ✅ Write specific triggering conditions\n- ✅ Use `inherit` for model unless specific need\n- ✅ Choose appropriate tools (least privilege)\n- ✅ Write clear, structured system prompts\n- ✅ Test agent triggering thoroughly\n\n**DON'T:**\n- ❌ Use generic descriptions without examples\n- ❌ Omit triggering conditions\n- ❌ Give all agents same color\n- ❌ Grant unnecessary tool access\n- ❌ Write vague system prompts\n- ❌ Skip testing\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed guidance, consult:\n\n- **`references/system-prompt-design.md`** - Complete system prompt patterns\n- **`references/triggering-examples.md`** - Example formats and best practices\n- **`references/agent-creation-system-prompt.md`** - The exact prompt from Claude Code\n\n### Example Files\n\nWorking examples in `examples/`:\n\n- **`agent-creation-prompt.md`** - AI-assisted agent generation template\n- **`complete-agent-examples.md`** - Full agent examples for different use cases\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-agent.sh`** - Validate agent file structure\n- **`test-agent-trigger.sh`** - Test if agent triggers correctly\n\n## Implementation Workflow\n\nTo create an agent for a plugin:\n\n1. Define agent purpose and triggering conditions\n2. Choose creation method (AI-assisted or manual)\n3. Create `agents/agent-name.md` file\n4. Write frontmatter with all required fields\n5. Write system prompt following best practices\n6. Include 2-4 triggering examples in description\n7. Validate with `scripts/validate-agent.sh`\n8. Test triggering with real scenarios\n9. Document agent in plugin README\n\nFocus on clear triggering conditions and comprehensive system prompts for autonomous operation.\n\n\n# Plugin Command Examples\n\nPractical examples of commands designed for Claude Code plugins, demonstrating plugin-specific patterns and features.\n\n## Table of Contents\n\n1. [Simple Plugin Command](#1-simple-plugin-command)\n2. [Script-Based Analysis](#2-script-based-analysis)\n3. [Template-Based Generation](#3-template-based-generation)\n4. [Multi-Script Workflow](#4-multi-script-workflow)\n5. [Configuration-Driven Deployment](#5-configuration-driven-deployment)\n6. [Agent Integration](#6-agent-integration)\n7. [Skill Integration](#7-skill-integration)\n8. [Multi-Component Workflow](#8-multi-component-workflow)\n9. [Validated Input Command](#9-validated-input-command)\n10. [Environment-Aware Command](#10-environment-aware-command)\n\n---\n\n## 1. Simple Plugin Command\n\n**Use case:** Basic command that uses plugin script\n\n**File:** `commands/analyze.md`\n\n```markdown\n---\ndescription: Analyze code quality using plugin tools\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nAnalyze @$1 using plugin's quality checker:\n\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/quality-check.js $1`\n\nReview the analysis output and provide:\n1. Summary of findings\n2. Priority issues to address\n3. Suggested improvements\n4. Code quality score interpretation\n```\n\n**Key features:**\n- Uses `${CLAUDE_PLUGIN_ROOT}` for portable path\n- Combines file reference with script execution\n- Simple single-purpose command\n\n---\n\n## 2. Script-Based Analysis\n\n**Use case:** Run comprehensive analysis using multiple plugin scripts\n\n**File:** `commands/full-audit.md`\n\n```markdown\n---\ndescription: Complete code audit using plugin suite\nargument-hint: [directory]\nallowed-tools: Bash(*)\nmodel: sonnet\n---\n\nRunning complete audit on $1:\n\n**Security scan:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh $1`\n\n**Performance analysis:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-analyze.sh $1`\n\n**Best practices check:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/best-practices.sh $1`\n\nAnalyze all results and create comprehensive report including:\n- Critical issues requiring immediate attention\n- Performance optimization opportunities\n- Security vulnerabilities and fixes\n- Overall health score and recommendations\n```\n\n**Key features:**\n- Multiple script executions\n- Organized output sections\n- Comprehensive workflow\n- Clear reporting structure\n\n---\n\n## 3. Template-Based Generation\n\n**Use case:** Generate documentation following plugin template\n\n**File:** `commands/gen-api-docs.md`\n\n```markdown\n---\ndescription: Generate API documentation from template\nargument-hint: [api-file]\n---\n\nTemplate structure: @${CLAUDE_PLUGIN_ROOT}/templates/api-documentation.md\n\nAPI implementation: @$1\n\nGenerate complete API documentation following the template format above.\n\nEnsure documentation includes:\n- Endpoint descriptions with HTTP methods\n- Request/response schemas\n- Authentication requirements\n- Error codes and handling\n- Usage examples with curl commands\n- Rate limiting information\n\nFormat output as markdown suitable for README or docs site.\n```\n\n**Key features:**\n- Uses plugin template\n- Combines template with source file\n- Standardized output format\n- Clear documentation structure\n\n---\n\n## 4. Multi-Script Workflow\n\n**Use case:** Orchestrate build, test, and deploy workflow\n\n**File:** `commands/release.md`\n\n```markdown\n---\ndescription: Execute complete release workflow\nargument-hint: [version]\nallowed-tools: Bash(*), Read\n---\n\nExecuting release workflow for version $1:\n\n**Step 1 - Pre-release validation:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-release-check.sh $1`\n\n**Step 2 - Build artifacts:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build-release.sh $1`\n\n**Step 3 - Run test suite:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh`\n\n**Step 4 - Package release:**\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh $1`\n\nReview all step outputs and report:\n1. Any failures or warnings\n2. Build artifacts location\n3. Test results summary\n4. Next steps for deployment\n5. Rollback plan if needed\n```\n\n**Key features:**\n- Multi-step workflow\n- Sequential script execution\n- Clear step numbering\n- Comprehensive reporting\n\n---\n\n## 5. Configuration-Driven Deployment\n\n**Use case:** Deploy using environment-specific plugin configuration\n\n**File:** `commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nDeployment configuration for $1: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nCurrent git state: !`git rev-parse --short HEAD`\n\nBuild info: !`cat package.json | grep -E '(name|version)'`\n\nExecute deployment to $1 environment using configuration above.\n\nDeployment checklist:\n1. Validate configuration settings\n2. Build application for $1\n3. Run pre-deployment tests\n4. Deploy to target environment\n5. Run smoke tests\n6. Verify deployment success\n7. Update deployment log\n\nReport deployment status and any issues encountered.\n```\n\n**Key features:**\n- Environment-specific configuration\n- Dynamic config file loading\n- Pre-deployment validation\n- Structured checklist\n\n---\n\n## 6. Agent Integration\n\n**Use case:** Command that launches plugin agent for complex task\n\n**File:** `commands/deep-review.md`\n\n```markdown\n---\ndescription: Deep code review using plugin agent\nargument-hint: [file-or-directory]\n---\n\nInitiate comprehensive code review of @$1 using the code-reviewer agent.\n\nThe agent will perform:\n1. **Static analysis** - Check for code smells and anti-patterns\n2. **Security audit** - Identify potential vulnerabilities\n3. **Performance review** - Find optimization opportunities\n4. **Best practices** - Ensure code follows standards\n5. **Documentation check** - Verify adequate documentation\n\nThe agent has access to:\n- Plugin's linting rules: ${CLAUDE_PLUGIN_ROOT}/config/lint-rules.json\n- Security checklist: ${CLAUDE_PLUGIN_ROOT}/checklists/security.md\n- Performance guidelines: ${CLAUDE_PLUGIN_ROOT}/docs/performance.md\n\nNote: This uses the Task tool to launch the plugin's code-reviewer agent for thorough analysis.\n```\n\n**Key features:**\n- Delegates to plugin agent\n- Documents agent capabilities\n- References plugin resources\n- Clear scope definition\n\n---\n\n## 7. Skill Integration\n\n**Use case:** Command that leverages plugin skill for specialized knowledge\n\n**File:** `commands/document-api.md`\n\n```markdown\n---\ndescription: Document API following plugin standards\nargument-hint: [api-file]\n---\n\nAPI source code: @$1\n\nGenerate API documentation following the plugin's API documentation standards.\n\nUse the api-documentation-standards skill to ensure:\n- **OpenAPI compliance** - Follow OpenAPI 3.0 specification\n- **Consistent formatting** - Use plugin's documentation style\n- **Complete coverage** - Document all endpoints and schemas\n- **Example quality** - Provide realistic usage examples\n- **Error documentation** - Cover all error scenarios\n\nThe skill provides:\n- Standard documentation templates\n- API documentation best practices\n- Common patterns for this codebase\n- Quality validation criteria\n\nGenerate production-ready API documentation.\n```\n\n**Key features:**\n- Invokes plugin skill by name\n- Documents skill purpose\n- Clear expectations\n- Leverages skill knowledge\n\n---\n\n## 8. Multi-Component Workflow\n\n**Use case:** Complex workflow using agents, skills, and scripts\n\n**File:** `commands/complete-review.md`\n\n```markdown\n---\ndescription: Comprehensive review using all plugin components\nargument-hint: [file-path]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget file: @$1\n\nExecute comprehensive review workflow:\n\n**Phase 1: Automated Analysis**\nRun plugin analyzer: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\n**Phase 2: Deep Review (Agent)**\nLaunch the code-quality-reviewer agent for detailed analysis.\nAgent will examine:\n- Code structure and organization\n- Error handling patterns\n- Testing coverage\n- Documentation quality\n\n**Phase 3: Standards Check (Skill)**\nUse the coding-standards skill to validate:\n- Naming conventions\n- Code formatting\n- Best practices adherence\n- Framework-specific patterns\n\n**Phase 4: Report Generation**\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nCompile all findings into comprehensive report following template.\n\n**Phase 5: Recommendations**\nGenerate prioritized action items:\n1. Critical issues (must fix)\n2. Important improvements (should fix)\n3. Nice-to-have enhancements (could fix)\n\nInclude specific file locations and suggested changes for each item.\n```\n\n**Key features:**\n- Multi-phase workflow\n- Combines scripts, agents, skills\n- Template-based reporting\n- Prioritized outputs\n\n---\n\n## 9. Validated Input Command\n\n**Use case:** Command with input validation and error handling\n\n**File:** `commands/build-env.md`\n\n```markdown\n---\ndescription: Build for specific environment with validation\nargument-hint: [environment]\nallowed-tools: Bash(*)\n---\n\nValidate environment argument: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" && echo \"VALID\" || echo \"INVALID\"`\n\nCheck build script exists: !`test -x ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh && echo \"EXISTS\" || echo \"MISSING\"`\n\nVerify configuration available: !`test -f ${CLAUDE_PLUGIN_ROOT}/config/$1.json && echo \"FOUND\" || echo \"NOT_FOUND\"`\n\nIf all validations pass:\n\n**Configuration:** @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\n**Execute build:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh $1 2>&1`\n\n**Validation results:** !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-build.sh $1 2>&1`\n\nReport build status and any issues.\n\nIf validations fail:\n- Explain which validation failed\n- Provide expected values/locations\n- Suggest corrective actions\n- Document troubleshooting steps\n```\n\n**Key features:**\n- Input validation\n- Resource existence checks\n- Error handling\n- Helpful error messages\n- Graceful failure handling\n\n---\n\n## 10. Environment-Aware Command\n\n**Use case:** Command that adapts behavior based on environment\n\n**File:** `commands/run-checks.md`\n\n```markdown\n---\ndescription: Run environment-appropriate checks\nargument-hint: [environment]\nallowed-tools: Bash(*), Read\n---\n\nEnvironment: $1\n\nLoad environment configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-checks.json\n\nDetermine check level: !`echo \"$1\" | grep -E \"^prod$\" && echo \"FULL\" || echo \"BASIC\"`\n\n**For production environment:**\n- Full test suite: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-full.sh`\n- Security scan: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh`\n- Performance audit: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-check.sh`\n- Compliance check: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/compliance.sh`\n\n**For non-production environments:**\n- Basic tests: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-basic.sh`\n- Quick lint: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh`\n\nAnalyze results based on environment requirements:\n\n**Production:** All checks must pass with zero critical issues\n**Staging:** No critical issues, warnings acceptable\n**Development:** Focus on blocking issues only\n\nReport status and recommend proceed/block decision.\n```\n\n**Key features:**\n- Environment-aware logic\n- Conditional execution\n- Different validation levels\n- Appropriate reporting per environment\n\n---\n\n## Common Patterns Summary\n\n### Pattern: Plugin Script Execution\n```markdown\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/script-name.js $1`\n```\nUse for: Running plugin-provided Node.js scripts\n\n### Pattern: Plugin Configuration Loading\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/config/config-name.json\n```\nUse for: Loading plugin configuration files\n\n### Pattern: Plugin Template Usage\n```markdown\n@${CLAUDE_PLUGIN_ROOT}/templates/template-name.md\n```\nUse for: Using plugin templates for generation\n\n### Pattern: Agent Invocation\n```markdown\nLaunch the [agent-name] agent for [task description].\n```\nUse for: Delegating complex tasks to plugin agents\n\n### Pattern: Skill Reference\n```markdown\nUse the [skill-name] skill to ensure [requirements].\n```\nUse for: Leveraging plugin skills for specialized knowledge\n\n### Pattern: Input Validation\n```markdown\nValidate input: !`echo \"$1\" | grep -E \"^pattern$\" && echo \"OK\" || echo \"ERROR\"`\n```\nUse for: Validating command arguments\n\n### Pattern: Resource Validation\n```markdown\nCheck exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/path/file && echo \"YES\" || echo \"NO\"`\n```\nUse for: Verifying required plugin files exist\n\n---\n\n## Development Tips\n\n### Testing Plugin Commands\n\n1. **Test with plugin installed:**\n ```bash\n cd /path/to/plugin\n claude /command-name args\n ```\n\n2. **Verify ${CLAUDE_PLUGIN_ROOT} expansion:**\n ```bash\n # Add debug output to command\n !`echo \"Plugin root: ${CLAUDE_PLUGIN_ROOT}\"`\n ```\n\n3. **Test across different working directories:**\n ```bash\n cd /tmp && claude /command-name\n cd /other/project && claude /command-name\n ```\n\n4. **Validate resource availability:**\n ```bash\n # Check all plugin resources exist\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/scripts/`\n !`ls -la ${CLAUDE_PLUGIN_ROOT}/config/`\n ```\n\n### Common Mistakes to Avoid\n\n1. **Using relative paths instead of ${CLAUDE_PLUGIN_ROOT}:**\n ```markdown\n # Wrong\n !`node ./scripts/analyze.js`\n\n # Correct\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n ```\n\n2. **Forgetting to allow required tools:**\n ```markdown\n # Missing allowed-tools\n !`bash script.sh` # Will fail without Bash permission\n\n # Correct\n ---\n allowed-tools: Bash(*)\n ---\n !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n ```\n\n3. **Not validating inputs:**\n ```markdown\n # Risky - no validation\n Deploy to $1 environment\n\n # Better - with validation\n Validate: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n Deploy to $1 environment (if valid)\n ```\n\n4. **Hardcoding plugin paths:**\n ```markdown\n # Wrong - breaks on different installations\n @/home/user/.claude/plugins/my-plugin/config.json\n\n # Correct - works everywhere\n @${CLAUDE_PLUGIN_ROOT}/config.json\n ```\n\n---\n\nFor detailed plugin-specific features, see `references/plugin-features-reference.md`.\nFor general command development, see main `SKILL.md`.\n\n\n# Simple Command Examples\n\nBasic slash command patterns for common use cases.\n\n**Important:** All examples below are written as instructions FOR Claude (agent consumption), not messages TO users. Commands tell Claude what to do, not tell users what will happen.\n\n## Example 1: Code Review Command\n\n**File:** `.claude/commands/review.md`\n\n```markdown\n---\ndescription: Review code for quality and issues\nallowed-tools: Read, Bash(git:*)\n---\n\nReview the code in this repository for:\n\n1. **Code Quality:**\n - Readability and maintainability\n - Consistent style and formatting\n - Appropriate abstraction levels\n\n2. **Potential Issues:**\n - Logic errors or bugs\n - Edge cases not handled\n - Performance concerns\n\n3. **Best Practices:**\n - Design patterns used correctly\n - Error handling present\n - Documentation adequate\n\nProvide specific feedback with file and line references.\n```\n\n**Usage:**\n```\n> /review\n```\n\n---\n\n## Example 2: Security Review Command\n\n**File:** `.claude/commands/security-review.md`\n\n```markdown\n---\ndescription: Review code for security vulnerabilities\nallowed-tools: Read, Grep\nmodel: sonnet\n---\n\nPerform comprehensive security review checking for:\n\n**Common Vulnerabilities:**\n- SQL injection risks\n- Cross-site scripting (XSS)\n- Authentication/authorization issues\n- Insecure data handling\n- Hardcoded secrets or credentials\n\n**Security Best Practices:**\n- Input validation present\n- Output encoding correct\n- Secure defaults used\n- Error messages safe\n- Logging appropriate (no sensitive data)\n\nFor each issue found:\n- File and line number\n- Severity (Critical/High/Medium/Low)\n- Description of vulnerability\n- Recommended fix\n\nPrioritize issues by severity.\n```\n\n**Usage:**\n```\n> /security-review\n```\n\n---\n\n## Example 3: Test Command with File Argument\n\n**File:** `.claude/commands/test-file.md`\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*), Bash(jest:*)\n---\n\nRun tests for $1:\n\nTest execution: !`npm test $1`\n\nAnalyze results:\n- Tests passed/failed\n- Code coverage\n- Performance issues\n- Flaky tests\n\nIf failures found, suggest fixes based on error messages.\n```\n\n**Usage:**\n```\n> /test-file src/utils/helpers.test.ts\n```\n\n---\n\n## Example 4: Documentation Generator\n\n**File:** `.claude/commands/document.md`\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1\n\nInclude:\n\n**Overview:**\n- Purpose and responsibility\n- Main functionality\n- Dependencies\n\n**API Documentation:**\n- Function/method signatures\n- Parameter descriptions with types\n- Return values with types\n- Exceptions/errors thrown\n\n**Usage Examples:**\n- Basic usage\n- Common patterns\n- Edge cases\n\n**Implementation Notes:**\n- Algorithm complexity\n- Performance considerations\n- Known limitations\n\nFormat as Markdown suitable for project documentation.\n```\n\n**Usage:**\n```\n> /document src/api/users.ts\n```\n\n---\n\n## Example 5: Git Status Summary\n\n**File:** `.claude/commands/git-status.md`\n\n```markdown\n---\ndescription: Summarize Git repository status\nallowed-tools: Bash(git:*)\n---\n\nRepository Status Summary:\n\n**Current Branch:** !`git branch --show-current`\n\n**Status:** !`git status --short`\n\n**Recent Commits:** !`git log --oneline -5`\n\n**Remote Status:** !`git fetch && git status -sb`\n\nProvide:\n- Summary of changes\n- Suggested next actions\n- Any warnings or issues\n```\n\n**Usage:**\n```\n> /git-status\n```\n\n---\n\n## Example 6: Deployment Command\n\n**File:** `.claude/commands/deploy.md`\n\n```markdown\n---\ndescription: Deploy to specified environment\nargument-hint: [environment] [version]\nallowed-tools: Bash(kubectl:*), Read\n---\n\nDeploy to $1 environment using version $2\n\n**Pre-deployment Checks:**\n1. Verify $1 configuration exists\n2. Check version $2 is valid\n3. Verify cluster accessibility: !`kubectl cluster-info`\n\n**Deployment Steps:**\n1. Update deployment manifest with version $2\n2. Apply configuration to $1\n3. Monitor rollout status\n4. Verify pod health\n5. Run smoke tests\n\n**Rollback Plan:**\nDocument current version for rollback if issues occur.\n\nProceed with deployment? (yes/no)\n```\n\n**Usage:**\n```\n> /deploy staging v1.2.3\n```\n\n---\n\n## Example 7: Comparison Command\n\n**File:** `.claude/commands/compare-files.md`\n\n```markdown\n---\ndescription: Compare two files\nargument-hint: [file1] [file2]\n---\n\nCompare @$1 with @$2\n\n**Analysis:**\n\n1. **Differences:**\n - Lines added\n - Lines removed\n - Lines modified\n\n2. **Functional Changes:**\n - Breaking changes\n - New features\n - Bug fixes\n - Refactoring\n\n3. **Impact:**\n - Affected components\n - Required updates elsewhere\n - Migration requirements\n\n4. **Recommendations:**\n - Code review focus areas\n - Testing requirements\n - Documentation updates needed\n\nPresent as structured comparison report.\n```\n\n**Usage:**\n```\n> /compare-files src/old-api.ts src/new-api.ts\n```\n\n---\n\n## Example 8: Quick Fix Command\n\n**File:** `.claude/commands/quick-fix.md`\n\n```markdown\n---\ndescription: Quick fix for common issues\nargument-hint: [issue-description]\nmodel: haiku\n---\n\nQuickly fix: $ARGUMENTS\n\n**Approach:**\n1. Identify the issue\n2. Find relevant code\n3. Propose fix\n4. Explain solution\n\nFocus on:\n- Simple, direct solution\n- Minimal changes\n- Following existing patterns\n- No breaking changes\n\nProvide code changes with file paths and line numbers.\n```\n\n**Usage:**\n```\n> /quick-fix button not responding to clicks\n> /quick-fix typo in error message\n```\n\n---\n\n## Example 9: Research Command\n\n**File:** `.claude/commands/research.md`\n\n```markdown\n---\ndescription: Research best practices for topic\nargument-hint: [topic]\nmodel: sonnet\n---\n\nResearch best practices for: $ARGUMENTS\n\n**Coverage:**\n\n1. **Current State:**\n - How we currently handle this\n - Existing implementations\n\n2. **Industry Standards:**\n - Common patterns\n - Recommended approaches\n - Tools and libraries\n\n3. **Comparison:**\n - Our approach vs standards\n - Gaps or improvements needed\n - Migration considerations\n\n4. **Recommendations:**\n - Concrete action items\n - Priority and effort estimates\n - Resources for implementation\n\nProvide actionable guidance based on research.\n```\n\n**Usage:**\n```\n> /research error handling in async operations\n> /research API authentication patterns\n```\n\n---\n\n## Example 10: Explain Code Command\n\n**File:** `.claude/commands/explain.md`\n\n```markdown\n---\ndescription: Explain how code works\nargument-hint: [file-or-function]\n---\n\nExplain @$1 in detail\n\n**Explanation Structure:**\n\n1. **Overview:**\n - What it does\n - Why it exists\n - How it fits in system\n\n2. **Step-by-Step:**\n - Line-by-line walkthrough\n - Key algorithms or logic\n - Important details\n\n3. **Inputs and Outputs:**\n - Parameters and types\n - Return values\n - Side effects\n\n4. **Edge Cases:**\n - Error handling\n - Special cases\n - Limitations\n\n5. **Usage Examples:**\n - How to call it\n - Common patterns\n - Integration points\n\nExplain at level appropriate for junior engineer.\n```\n\n**Usage:**\n```\n> /explain src/utils/cache.ts\n> /explain AuthService.login\n```\n\n---\n\n## Key Patterns\n\n### Pattern 1: Read-Only Analysis\n\n```markdown\n---\nallowed-tools: Read, Grep\n---\n\nAnalyze but don't modify...\n```\n\n**Use for:** Code review, documentation, analysis\n\n### Pattern 2: Git Operations\n\n```markdown\n---\nallowed-tools: Bash(git:*)\n---\n\n!`git status`\nAnalyze and suggest...\n```\n\n**Use for:** Repository status, commit analysis\n\n### Pattern 3: Single Argument\n\n```markdown\n---\nargument-hint: [target]\n---\n\nProcess $1...\n```\n\n**Use for:** File operations, targeted actions\n\n### Pattern 4: Multiple Arguments\n\n```markdown\n---\nargument-hint: [source] [target] [options]\n---\n\nProcess $1 to $2 with $3...\n```\n\n**Use for:** Workflows, deployments, comparisons\n\n### Pattern 5: Fast Execution\n\n```markdown\n---\nmodel: haiku\n---\n\nQuick simple task...\n```\n\n**Use for:** Simple, repetitive commands\n\n### Pattern 6: File Comparison\n\n```markdown\nCompare @$1 with @$2...\n```\n\n**Use for:** Diff analysis, migration planning\n\n### Pattern 7: Context Gathering\n\n```markdown\n---\nallowed-tools: Bash(git:*), Read\n---\n\nContext: !`git status`\nFiles: @file1 @file2\n\nAnalyze...\n```\n\n**Use for:** Informed decision making\n\n## Tips for Writing Simple Commands\n\n1. **Start basic:** Single responsibility, clear purpose\n2. **Add complexity gradually:** Start without frontmatter\n3. **Test incrementally:** Verify each feature works\n4. **Use descriptive names:** Command name should indicate purpose\n5. **Document arguments:** Always use argument-hint\n6. **Provide examples:** Show usage in comments\n7. **Handle errors:** Consider missing arguments or files\n\n\n# Advanced Workflow Patterns\n\nMulti-step command sequences and composition patterns for complex workflows.\n\n## Overview\n\nAdvanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks.\n\n## Multi-Step Command Patterns\n\n### Sequential Workflow Command\n\nCommands that guide users through multi-step processes:\n\n```markdown\n---\ndescription: Complete PR review workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read, Grep\n---\n\n# PR Review Workflow for #$1\n\n## Step 1: Fetch PR Details\n!`gh pr view $1 --json title,body,author,files`\n\n## Step 2: Review Files\nFiles changed: !`gh pr diff $1 --name-only`\n\nFor each file:\n- Check code quality\n- Verify tests exist\n- Review documentation\n\n## Step 3: Run Checks\nTest status: !`gh pr checks $1`\n\nVerify:\n- All tests passing\n- No merge conflicts\n- CI/CD successful\n\n## Step 4: Provide Feedback\n\nSummarize:\n- Issues found (critical/minor)\n- Suggestions for improvement\n- Approval recommendation\n\nWould you like to:\n1. Approve PR\n2. Request changes\n3. Leave comments only\n\nReply with your choice and I'll help complete the action.\n```\n\n**Key features:**\n- Numbered steps for clarity\n- Bash execution for context\n- Decision points for user input\n- Next action suggestions\n\n### State-Carrying Workflow\n\nCommands that maintain state between invocations:\n\n```markdown\n---\ndescription: Initialize deployment workflow\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment\n\nCreating deployment tracking file...\n\nCurrent branch: !`git branch --show-current`\nLatest commit: !`git log -1 --format=%H`\n\nDeployment state saved to `.claude/deployment-state.local.md`:\n\n\\`\\`\\`markdown\n---\ninitialized: true\nbranch: $(git branch --show-current)\ncommit: $(git log -1 --format=%H)\ntimestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)\nstatus: initialized\n---\n\n# Deployment Tracking\n\nBranch: $(git branch --show-current)\nStarted: $(date)\n\nNext steps:\n1. Run tests: /deploy-test\n2. Build: /deploy-build\n3. Deploy: /deploy-execute\n\\`\\`\\`\n\nState saved. Run `/deploy-test` to continue.\n```\n\n**Next command** (`/deploy-test`):\n```markdown\n---\ndescription: Run deployment tests\nallowed-tools: Read, Bash(npm:*)\n---\n\nReading deployment state from `.claude/deployment-state.local.md`...\n\nRunning tests: !`npm test`\n\nUpdating state to 'tested'...\n\nTests complete. Run `/deploy-build` to continue.\n```\n\n**Pattern benefits:**\n- Persistent state across commands\n- Clear workflow progression\n- Safety checkpoints\n- Resume capability\n\n### Conditional Workflow Branching\n\nCommands that adapt based on conditions:\n\n```markdown\n---\ndescription: Smart deployment workflow\nargument-hint: [environment]\nallowed-tools: Bash(git:*), Bash(npm:*), Read\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\nBranch: !`git branch --show-current`\nStatus: !`git status --short`\n\n**Checking conditions:**\n\n1. Branch status:\n - If main/master: Require approval\n - If feature branch: Warning about target\n - If hotfix: Fast-track process\n\n2. Tests:\n !`npm test`\n - If tests fail: STOP - fix tests first\n - If tests pass: Continue\n\n3. Environment:\n - If $1 = 'production': Extra validation\n - If $1 = 'staging': Standard process\n - If $1 = 'dev': Minimal checks\n\n**Workflow decision:**\nBased on above, proceeding with: [determined workflow]\n\n[Conditional steps based on environment and status]\n\nReady to deploy? (yes/no)\n```\n\n## Command Composition Patterns\n\n### Command Chaining\n\nCommands designed to work together:\n\n```markdown\n---\ndescription: Prepare for code review\n---\n\n# Prepare Code Review\n\nRunning preparation sequence:\n\n1. Format code: /format-code\n2. Run linter: /lint-code\n3. Run tests: /test-all\n4. Generate coverage: /coverage-report\n5. Create review summary: /review-summary\n\nThis is a meta-command. After completing each step above,\nI'll compile results and prepare comprehensive review materials.\n\nStarting sequence...\n```\n\n**Individual commands** are simple:\n- `/format-code` - Just formats\n- `/lint-code` - Just lints\n- `/test-all` - Just tests\n\n**Composition command** orchestrates them.\n\n### Pipeline Pattern\n\nCommands that process output from previous commands:\n\n```markdown\n---\ndescription: Analyze test failures\n---\n\n# Analyze Test Failures\n\n## Step 1: Get test results\n(Run /test-all first if not done)\n\nReading test output...\n\n## Step 2: Categorize failures\n- Flaky tests (random failures)\n- Consistent failures\n- New failures vs existing\n\n## Step 3: Prioritize\nRank by:\n- Impact (critical path vs edge case)\n- Frequency (always fails vs sometimes)\n- Effort (quick fix vs major work)\n\n## Step 4: Generate fix plan\nFor each failure:\n- Root cause hypothesis\n- Suggested fix approach\n- Estimated effort\n\nWould you like me to:\n1. Fix highest priority failure\n2. Generate detailed fix plans for all\n3. Create GitHub issues for each\n```\n\n### Parallel Execution Pattern\n\nCommands that coordinate multiple simultaneous operations:\n\n```markdown\n---\ndescription: Run comprehensive validation\nallowed-tools: Bash(*), Read\n---\n\n# Comprehensive Validation\n\nRunning validations in parallel...\n\nStarting:\n- Code quality checks\n- Security scanning\n- Dependency audit\n- Performance profiling\n\nThis will take 2-3 minutes. I'll monitor all processes\nand report when complete.\n\n[Poll each process and report progress]\n\nAll validations complete. Summary:\n- Quality: PASS (0 issues)\n- Security: WARN (2 minor issues)\n- Dependencies: PASS\n- Performance: PASS (baseline met)\n\nDetails:\n[Collated results from all checks]\n```\n\n## Workflow State Management\n\n### Using .local.md Files\n\nStore workflow state in plugin-specific files:\n\n```markdown\n.claude/plugin-name-workflow.local.md:\n\n---\nworkflow: deployment\nstage: testing\nstarted: 2025-01-15T10:30:00Z\nenvironment: staging\nbranch: feature/new-api\ncommit: abc123def\ntests_passed: false\nbuild_complete: false\n---\n\n# Deployment Workflow State\n\nCurrent stage: Testing\nStarted: 2025-01-15 10:30 UTC\n\nCompleted steps:\n- ✅ Validation\n- ✅ Branch check\n- ⏳ Testing (in progress)\n\nPending steps:\n- Build\n- Deploy\n- Smoke tests\n```\n\n**Reading state in commands:**\n\n```markdown\n---\ndescription: Continue deployment workflow\nallowed-tools: Read, Write\n---\n\nReading workflow state from .claude/plugin-name-workflow.local.md...\n\nCurrent stage: @.claude/plugin-name-workflow.local.md\n\n[Parse YAML frontmatter to determine next step]\n\nNext action based on state: [determined action]\n```\n\n### Workflow Recovery\n\nHandle interrupted workflows:\n\n```markdown\n---\ndescription: Resume deployment workflow\nallowed-tools: Read\n---\n\n# Resume Deployment\n\nChecking for interrupted workflow...\n\nState file: @.claude/plugin-name-workflow.local.md\n\n**Workflow found:**\n- Started: [timestamp]\n- Environment: [env]\n- Last completed: [step]\n\n**Recovery options:**\n1. Resume from last step\n2. Restart from beginning\n3. Abort and clean up\n\nWhich would you like? (1/2/3)\n```\n\n## Workflow Coordination Patterns\n\n### Cross-Command Communication\n\nCommands that signal each other:\n\n```markdown\n---\ndescription: Mark feature complete\nallowed-tools: Write\n---\n\n# Mark Feature Complete\n\nWriting completion marker...\n\nCreating: .claude/feature-complete.flag\n\nThis signals other commands that feature is ready for:\n- Integration testing (/integration-test will auto-detect)\n- Documentation generation (/docs-generate will include)\n- Release notes (/release-notes will add)\n\nFeature marked complete.\n```\n\n**Other commands check for flag:**\n\n```markdown\n---\ndescription: Generate release notes\nallowed-tools: Read, Bash(git:*)\n---\n\nChecking for completed features...\n\nif [ -f .claude/feature-complete.flag ]; then\n Feature ready for release notes\nfi\n\n[Include in release notes]\n```\n\n### Workflow Locking\n\nPrevent concurrent workflow execution:\n\n```markdown\n---\ndescription: Start deployment\nallowed-tools: Read, Write, Bash\n---\n\n# Start Deployment\n\nChecking for active deployments...\n\nif [ -f .claude/deployment.lock ]; then\n ERROR: Deployment already in progress\n Started: [timestamp from lock file]\n\n Cannot start concurrent deployment.\n Wait for completion or run /deployment-abort\n\n Exit.\nfi\n\nCreating deployment lock...\n\nDeployment started. Lock created.\n[Proceed with deployment]\n```\n\n**Lock cleanup:**\n\n```markdown\n---\ndescription: Complete deployment\nallowed-tools: Write, Bash\n---\n\nDeployment complete.\n\nRemoving deployment lock...\nrm .claude/deployment.lock\n\nReady for next deployment.\n```\n\n## Advanced Argument Handling\n\n### Optional Arguments with Defaults\n\n```markdown\n---\ndescription: Deploy with optional version\nargument-hint: [environment] [version]\n---\n\nEnvironment: ${1:-staging}\nVersion: ${2:-latest}\n\nDeploying ${2:-latest} to ${1:-staging}...\n\nNote: Using defaults for missing arguments:\n- Environment defaults to 'staging'\n- Version defaults to 'latest'\n```\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy to validated environment\nargument-hint: [environment]\n---\n\nEnvironment: $1\n\nValidating environment...\n\nvalid_envs=\"dev staging production\"\nif ! echo \"$valid_envs\" | grep -w \"$1\" > /dev/null; then\n ERROR: Invalid environment '$1'\n Valid options: dev, staging, production\n Exit.\nfi\n\nEnvironment validated. Proceeding...\n```\n\n### Argument Transformation\n\n```markdown\n---\ndescription: Deploy with shorthand\nargument-hint: [env-shorthand]\n---\n\nInput: $1\n\nExpanding shorthand:\n- d/dev → development\n- s/stg → staging\n- p/prod → production\n\ncase \"$1\" in\n d|dev) ENV=\"development\";;\n s|stg) ENV=\"staging\";;\n p|prod) ENV=\"production\";;\n *) ENV=\"$1\";;\nesac\n\nDeploying to: $ENV\n```\n\n## Error Handling in Workflows\n\n### Graceful Failure\n\n```markdown\n---\ndescription: Resilient deployment workflow\n---\n\n# Deployment Workflow\n\nRunning steps with error handling...\n\n## Step 1: Tests\n!`npm test`\n\nif [ $? -ne 0 ]; then\n ERROR: Tests failed\n\n Options:\n 1. Fix tests and retry\n 2. Skip tests (NOT recommended)\n 3. Abort deployment\n\n What would you like to do?\n\n [Wait for user input before continuing]\nfi\n\n## Step 2: Build\n[Continue only if Step 1 succeeded]\n```\n\n### Rollback on Failure\n\n```markdown\n---\ndescription: Deployment with rollback\n---\n\n# Deploy with Rollback\n\nSaving current state for rollback...\nPrevious version: !`current-version.sh`\n\nDeploying new version...\n\n!`deploy.sh`\n\nif [ $? -ne 0 ]; then\n DEPLOYMENT FAILED\n\n Initiating automatic rollback...\n !`rollback.sh`\n\n Rolled back to previous version.\n Check logs for failure details.\nfi\n\nDeployment complete.\n```\n\n### Checkpoint Recovery\n\n```markdown\n---\ndescription: Workflow with checkpoints\n---\n\n# Multi-Stage Deployment\n\n## Checkpoint 1: Validation\n!`validate.sh`\necho \"checkpoint:validation\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 2: Build\n!`build.sh`\necho \"checkpoint:build\" >> .claude/deployment-checkpoints.log\n\n## Checkpoint 3: Deploy\n!`deploy.sh`\necho \"checkpoint:deploy\" >> .claude/deployment-checkpoints.log\n\nIf any step fails, resume with:\n/deployment-resume [last-successful-checkpoint]\n```\n\n## Best Practices\n\n### Workflow Design\n\n1. **Clear progression**: Number steps, show current position\n2. **Explicit state**: Don't rely on implicit state\n3. **User control**: Provide decision points\n4. **Error recovery**: Handle failures gracefully\n5. **Progress indication**: Show what's done, what's pending\n\n### Command Composition\n\n1. **Single responsibility**: Each command does one thing well\n2. **Composable design**: Commands work together easily\n3. **Standard interfaces**: Consistent input/output formats\n4. **Loose coupling**: Commands don't depend on each other's internals\n\n### State Management\n\n1. **Persistent state**: Use .local.md files\n2. **Atomic updates**: Write complete state files atomically\n3. **State validation**: Check state file format/completeness\n4. **Cleanup**: Remove stale state files\n5. **Documentation**: Document state file formats\n\n### Error Handling\n\n1. **Fail fast**: Detect errors early\n2. **Clear messages**: Explain what went wrong\n3. **Recovery options**: Provide clear next steps\n4. **State preservation**: Keep state for recovery\n5. **Rollback capability**: Support undoing changes\n\n## Example: Complete Deployment Workflow\n\n### Initialize Command\n\n```markdown\n---\ndescription: Initialize deployment\nargument-hint: [environment]\nallowed-tools: Write, Bash(git:*)\n---\n\n# Initialize Deployment to $1\n\nCreating workflow state...\n\n\\`\\`\\`yaml\n---\nworkflow: deployment\nenvironment: $1\nbranch: !`git branch --show-current`\ncommit: !`git rev-parse HEAD`\nstage: initialized\ntimestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`\n---\n\\`\\`\\`\n\nWritten to .claude/deployment-state.local.md\n\nNext: Run /deployment-validate\n```\n\n### Validation Command\n\n```markdown\n---\ndescription: Validate deployment\nallowed-tools: Read, Bash\n---\n\nReading state: @.claude/deployment-state.local.md\n\nRunning validation...\n- Branch check: PASS\n- Tests: PASS\n- Build: PASS\n\nUpdating state to 'validated'...\n\nNext: Run /deployment-execute\n```\n\n### Execution Command\n\n```markdown\n---\ndescription: Execute deployment\nallowed-tools: Read, Bash, Write\n---\n\nReading state: @.claude/deployment-state.local.md\n\nExecuting deployment to [environment]...\n\n!`deploy.sh [environment]`\n\nDeployment complete.\nUpdating state to 'completed'...\n\nCleanup: /deployment-cleanup\n```\n\n### Cleanup Command\n\n```markdown\n---\ndescription: Clean up deployment\nallowed-tools: Bash\n---\n\nRemoving deployment state...\nrm .claude/deployment-state.local.md\n\nDeployment workflow complete.\n```\n\nThis complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.\n\n\n# Command Documentation Patterns\n\nStrategies for creating self-documenting, maintainable commands with excellent user experience.\n\n## Overview\n\nWell-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.\n\n## Self-Documenting Command Structure\n\n### Complete Command Template\n\n```markdown\n---\ndescription: Clear, actionable description under 60 chars\nargument-hint: [arg1] [arg2] [optional-arg]\nallowed-tools: Read, Bash(git:*)\nmodel: sonnet\n---\n\n\n\n# Command Implementation\n\n[Command prompt content here...]\n\n[Explain what will happen...]\n\n[Guide user through steps...]\n\n[Provide clear output...]\n```\n\n### Documentation Comment Sections\n\n**PURPOSE**: Why the command exists\n- Problem it solves\n- Use cases\n- When to use vs when not to use\n\n**USAGE**: Basic syntax\n- Command invocation pattern\n- Required vs optional arguments\n- Default values\n\n**ARGUMENTS**: Detailed argument documentation\n- Each argument described\n- Type information\n- Valid values/ranges\n- Defaults\n\n**EXAMPLES**: Concrete usage examples\n- Common use cases\n- Edge cases\n- Expected outputs\n\n**REQUIREMENTS**: Prerequisites\n- Dependencies\n- Permissions\n- Environmental setup\n\n**RELATED COMMANDS**: Connections\n- Similar commands\n- Complementary commands\n- Alternative approaches\n\n**TROUBLESHOOTING**: Common issues\n- Known problems\n- Solutions\n- Workarounds\n\n**CHANGELOG**: Version history\n- What changed when\n- Breaking changes highlighted\n- Migration guidance\n\n## In-Line Documentation Patterns\n\n### Commented Sections\n\n```markdown\n---\ndescription: Complex multi-step command\n---\n\n\n\n\nChecking prerequisites...\n- Git repository: !`git rev-parse --git-dir 2>/dev/null`\n- Branch exists: [validation logic]\n\n\n\n\nAnalyzing differences between $1 and $2...\n[Analysis logic...]\n\n\n\n\nBased on analysis, recommend:\n[Recommendations...]\n\n\n```\n\n### Inline Explanations\n\n```markdown\n---\ndescription: Deployment command with inline docs\n---\n\n# Deploy to $1\n\n## Pre-flight Checks\n\n\nCurrent branch: !`git branch --show-current`\n\n\nif [ \"$1\" = \"production\" ] && [ \"$(git branch --show-current)\" != \"main\" ]; then\n ⚠️ WARNING: Not on main branch for production deploy\n This is unusual. Confirm this is intentional.\nfi\n\n\nRunning tests: !`npm test`\n\n✓ All checks passed\n\n## Deployment\n\n\n\nDeploying to $1 environment...\n[Deployment steps...]\n\n\nVerifying deployment health...\n[Health checks...]\n\nDeployment complete!\n\n## Next Steps\n\n\n1. Monitor logs: /logs $1\n2. Run smoke tests: /smoke-test $1\n3. Notify team: /notify-deployment $1\n```\n\n### Decision Point Documentation\n\n```markdown\n---\ndescription: Interactive deployment command\n---\n\n# Interactive Deployment\n\n## Configuration Review\n\nTarget: $1\nCurrent version: !`cat version.txt`\nNew version: $2\n\n\n\n\n\nReview the above configuration.\n\n**Continue with deployment?**\n- Reply \"yes\" to proceed\n- Reply \"no\" to cancel\n- Reply \"edit\" to modify configuration\n\n[Await user input before continuing...]\n\n\n\n\nProceeding with deployment...\n```\n\n## Help Text Patterns\n\n### Built-in Help Command\n\nCreate a help subcommand for complex commands:\n\n```markdown\n---\ndescription: Main command with help\nargument-hint: [subcommand] [args]\n---\n\n# Command Processor\n\nif [ \"$1\" = \"help\" ] || [ \"$1\" = \"--help\" ] || [ \"$1\" = \"-h\" ]; then\n **Command Help**\n\n USAGE:\n /command [subcommand] [args]\n\n SUBCOMMANDS:\n init [name] Initialize new configuration\n deploy [env] Deploy to environment\n status Show current status\n rollback Rollback last deployment\n help Show this help\n\n EXAMPLES:\n /command init my-project\n /command deploy staging\n /command status\n /command rollback\n\n For detailed help on a subcommand:\n /command [subcommand] --help\n\n Exit.\nfi\n\n[Regular command processing...]\n```\n\n### Contextual Help\n\nProvide help based on context:\n\n```markdown\n---\ndescription: Context-aware command\nargument-hint: [operation] [target]\n---\n\n# Context-Aware Operation\n\nif [ -z \"$1\" ]; then\n **No operation specified**\n\n Available operations:\n - analyze: Analyze target for issues\n - fix: Apply automatic fixes\n - report: Generate detailed report\n\n Usage: /command [operation] [target]\n\n Examples:\n /command analyze src/\n /command fix src/app.js\n /command report\n\n Run /command help for more details.\n\n Exit.\nfi\n\n[Command continues if operation provided...]\n```\n\n## Error Message Documentation\n\n### Helpful Error Messages\n\n```markdown\n---\ndescription: Command with good error messages\n---\n\n# Validation Command\n\nif [ -z \"$1\" ]; then\n ❌ ERROR: Missing required argument\n\n The 'file-path' argument is required.\n\n USAGE:\n /validate [file-path]\n\n EXAMPLE:\n /validate src/app.js\n\n Try again with a file path.\n\n Exit.\nfi\n\nif [ ! -f \"$1\" ]; then\n ❌ ERROR: File not found: $1\n\n The specified file does not exist or is not accessible.\n\n COMMON CAUSES:\n 1. Typo in file path\n 2. File was deleted or moved\n 3. Insufficient permissions\n\n SUGGESTIONS:\n - Check spelling: $1\n - Verify file exists: ls -la $(dirname \"$1\")\n - Check permissions: ls -l \"$1\"\n\n Exit.\nfi\n\n[Command continues if validation passes...]\n```\n\n### Error Recovery Guidance\n\n```markdown\n---\ndescription: Command with recovery guidance\n---\n\n# Operation Command\n\nRunning operation...\n\n!`risky-operation.sh`\n\nif [ $? -ne 0 ]; then\n ❌ OPERATION FAILED\n\n The operation encountered an error and could not complete.\n\n WHAT HAPPENED:\n The risky-operation.sh script returned a non-zero exit code.\n\n WHAT THIS MEANS:\n - Changes may be partially applied\n - System may be in inconsistent state\n - Manual intervention may be needed\n\n RECOVERY STEPS:\n 1. Check operation logs: cat /tmp/operation.log\n 2. Verify system state: /check-state\n 3. If needed, rollback: /rollback-operation\n 4. Fix underlying issue\n 5. Retry operation: /retry-operation\n\n NEED HELP?\n - Check troubleshooting guide: /help troubleshooting\n - Contact support with error code: ERR_OP_FAILED_001\n\n Exit.\nfi\n```\n\n## Usage Example Documentation\n\n### Embedded Examples\n\n```markdown\n---\ndescription: Command with embedded examples\n---\n\n# Feature Command\n\nThis command performs feature analysis with multiple options.\n\n## Basic Usage\n\n\\`\\`\\`\n/feature analyze src/\n\\`\\`\\`\n\nAnalyzes all files in src/ directory for feature usage.\n\n## Advanced Usage\n\n\\`\\`\\`\n/feature analyze src/ --detailed\n\\`\\`\\`\n\nProvides detailed analysis including:\n- Feature breakdown by file\n- Usage patterns\n- Optimization suggestions\n\n## Use Cases\n\n**Use Case 1: Quick overview**\n\\`\\`\\`\n/feature analyze .\n\\`\\`\\`\nGet high-level feature summary of entire project.\n\n**Use Case 2: Specific directory**\n\\`\\`\\`\n/feature analyze src/components\n\\`\\`\\`\nFocus analysis on components directory only.\n\n**Use Case 3: Comparison**\n\\`\\`\\`\n/feature analyze src/ --compare baseline.json\n\\`\\`\\`\nCompare current features against baseline.\n\n---\n\nNow processing your request...\n\n[Command implementation...]\n```\n\n### Example-Driven Documentation\n\n```markdown\n---\ndescription: Example-heavy command\n---\n\n# Transformation Command\n\n## What This Does\n\nTransforms data from one format to another.\n\n## Examples First\n\n### Example 1: JSON to YAML\n**Input:** `data.json`\n\\`\\`\\`json\n{\"name\": \"test\", \"value\": 42}\n\\`\\`\\`\n\n**Command:** `/transform data.json yaml`\n\n**Output:** `data.yaml`\n\\`\\`\\`yaml\nname: test\nvalue: 42\n\\`\\`\\`\n\n### Example 2: CSV to JSON\n**Input:** `data.csv`\n\\`\\`\\`csv\nname,value\ntest,42\n\\`\\`\\`\n\n**Command:** `/transform data.csv json`\n\n**Output:** `data.json`\n\\`\\`\\`json\n[{\"name\": \"test\", \"value\": \"42\"}]\n\\`\\`\\`\n\n### Example 3: With Options\n**Command:** `/transform data.json yaml --pretty --sort-keys`\n\n**Result:** Formatted YAML with sorted keys\n\n---\n\n## Your Transformation\n\nFile: $1\nFormat: $2\n\n[Perform transformation...]\n```\n\n## Maintenance Documentation\n\n### Version and Changelog\n\n```markdown\n\n```\n\n### Maintenance Notes\n\n```markdown\n\n```\n\n## README Documentation\n\nCommands should have companion README files:\n\n```markdown\n# Command Name\n\nBrief description of what the command does.\n\n## Installation\n\nThis command is part of the [plugin-name] plugin.\n\nInstall with:\n\\`\\`\\`\n/plugin install plugin-name\n\\`\\`\\`\n\n## Usage\n\nBasic usage:\n\\`\\`\\`\n/command-name [arg1] [arg2]\n\\`\\`\\`\n\n## Arguments\n\n- `arg1`: Description (required)\n- `arg2`: Description (optional, defaults to X)\n\n## Examples\n\n### Example 1: Basic Usage\n\\`\\`\\`\n/command-name value1 value2\n\\`\\`\\`\n\nDescription of what happens.\n\n### Example 2: Advanced Usage\n\\`\\`\\`\n/command-name value1 --option\n\\`\\`\\`\n\nDescription of advanced feature.\n\n## Configuration\n\nOptional configuration file: `.claude/command-name.local.md`\n\n\\`\\`\\`markdown\n---\ndefault_arg: value\nenable_feature: true\n---\n\\`\\`\\`\n\n## Requirements\n\n- Git 2.x or later\n- jq (for JSON processing)\n- Node.js 14+ (optional, for advanced features)\n\n## Troubleshooting\n\n### Issue: Command not found\n\n**Solution:** Ensure plugin is installed and enabled.\n\n### Issue: Permission denied\n\n**Solution:** Check file permissions and allowed-tools setting.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT License - See [LICENSE](LICENSE).\n\n## Support\n\n- Issues: https://github.com/user/plugin/issues\n- Docs: https://docs.example.com\n- Email: support@example.com\n```\n\n## Best Practices\n\n### Documentation Principles\n\n1. **Write for your future self**: Assume you'll forget details\n2. **Examples before explanations**: Show, then tell\n3. **Progressive disclosure**: Basic info first, details available\n4. **Keep it current**: Update docs when code changes\n5. **Test your docs**: Verify examples actually work\n\n### Documentation Locations\n\n1. **In command file**: Core usage, examples, inline explanations\n2. **README**: Installation, configuration, troubleshooting\n3. **Separate docs**: Detailed guides, tutorials, API reference\n4. **Comments**: Implementation details for maintainers\n\n### Documentation Style\n\n1. **Clear and concise**: No unnecessary words\n2. **Active voice**: \"Run the command\" not \"The command can be run\"\n3. **Consistent terminology**: Use same terms throughout\n4. **Formatted well**: Use headings, lists, code blocks\n5. **Accessible**: Assume reader is beginner\n\n### Documentation Maintenance\n\n1. **Version everything**: Track what changed when\n2. **Deprecate gracefully**: Warn before removing features\n3. **Migration guides**: Help users upgrade\n4. **Archive old docs**: Keep old versions accessible\n5. **Review regularly**: Ensure docs match reality\n\n## Documentation Checklist\n\nBefore releasing a command:\n\n- [ ] Description in frontmatter is clear\n- [ ] argument-hint documents all arguments\n- [ ] Usage examples in comments\n- [ ] Common use cases shown\n- [ ] Error messages are helpful\n- [ ] Requirements documented\n- [ ] Related commands listed\n- [ ] Changelog maintained\n- [ ] Version number updated\n- [ ] README created/updated\n- [ ] Examples actually work\n- [ ] Troubleshooting section complete\n\nWith good documentation, commands become self-service, reducing support burden and improving user experience.\n\n\n# Command Frontmatter Reference\n\nComplete reference for YAML frontmatter fields in slash commands.\n\n## Frontmatter Overview\n\nYAML frontmatter is optional metadata at the start of command files:\n\n```markdown\n---\ndescription: Brief description\nallowed-tools: Read, Write\nmodel: sonnet\nargument-hint: [arg1] [arg2]\n---\n\nCommand prompt content here...\n```\n\nAll fields are optional. Commands work without any frontmatter.\n\n## Field Specifications\n\n### description\n\n**Type:** String\n**Required:** No\n**Default:** First line of command prompt\n**Max Length:** ~60 characters recommended for `/help` display\n\n**Purpose:** Describes what the command does, shown in `/help` output\n\n**Examples:**\n```yaml\ndescription: Review code for security issues\n```\n```yaml\ndescription: Deploy to staging environment\n```\n```yaml\ndescription: Generate API documentation\n```\n\n**Best practices:**\n- Keep under 60 characters for clean display\n- Start with verb (Review, Deploy, Generate)\n- Be specific about what command does\n- Avoid redundant \"command\" or \"slash command\"\n\n**Good:**\n- ✅ \"Review PR for code quality and security\"\n- ✅ \"Deploy application to specified environment\"\n- ✅ \"Generate comprehensive API documentation\"\n\n**Bad:**\n- ❌ \"This command reviews PRs\" (unnecessary \"This command\")\n- ❌ \"Review\" (too vague)\n- ❌ \"A command that reviews pull requests for code quality, security issues, and best practices\" (too long)\n\n### allowed-tools\n\n**Type:** String or Array of strings\n**Required:** No\n**Default:** Inherits from conversation permissions\n\n**Purpose:** Restrict or specify which tools command can use\n\n**Formats:**\n\n**Single tool:**\n```yaml\nallowed-tools: Read\n```\n\n**Multiple tools (comma-separated):**\n```yaml\nallowed-tools: Read, Write, Edit\n```\n\n**Multiple tools (array):**\n```yaml\nallowed-tools:\n - Read\n - Write\n - Bash(git:*)\n```\n\n**Tool Patterns:**\n\n**Specific tools:**\n```yaml\nallowed-tools: Read, Grep, Edit\n```\n\n**Bash with command filter:**\n```yaml\nallowed-tools: Bash(git:*) # Only git commands\nallowed-tools: Bash(npm:*) # Only npm commands\nallowed-tools: Bash(docker:*) # Only docker commands\n```\n\n**All tools (not recommended):**\n```yaml\nallowed-tools: \"*\"\n```\n\n**When to use:**\n\n1. **Security:** Restrict command to safe operations\n ```yaml\n allowed-tools: Read, Grep # Read-only command\n ```\n\n2. **Clarity:** Document required tools\n ```yaml\n allowed-tools: Bash(git:*), Read\n ```\n\n3. **Bash execution:** Enable bash command output\n ```yaml\n allowed-tools: Bash(git status:*), Bash(git diff:*)\n ```\n\n**Best practices:**\n- Be as restrictive as possible\n- Use command filters for Bash (e.g., `git:*` not `*`)\n- Only specify when different from conversation permissions\n- Document why specific tools are needed\n\n### model\n\n**Type:** String\n**Required:** No\n**Default:** Inherits from conversation\n**Values:** `sonnet`, `opus`, `haiku`\n\n**Purpose:** Specify which Claude model executes the command\n\n**Examples:**\n```yaml\nmodel: haiku # Fast, efficient for simple tasks\n```\n```yaml\nmodel: sonnet # Balanced performance (default)\n```\n```yaml\nmodel: opus # Maximum capability for complex tasks\n```\n\n**When to use:**\n\n**Use `haiku` for:**\n- Simple, formulaic commands\n- Fast execution needed\n- Low complexity tasks\n- Frequent invocations\n\n```yaml\n---\ndescription: Format code file\nmodel: haiku\n---\n```\n\n**Use `sonnet` for:**\n- Standard commands (default)\n- Balanced speed/quality\n- Most common use cases\n\n```yaml\n---\ndescription: Review code changes\nmodel: sonnet\n---\n```\n\n**Use `opus` for:**\n- Complex analysis\n- Architectural decisions\n- Deep code understanding\n- Critical tasks\n\n```yaml\n---\ndescription: Analyze system architecture\nmodel: opus\n---\n```\n\n**Best practices:**\n- Omit unless specific need\n- Use `haiku` for speed when possible\n- Reserve `opus` for genuinely complex tasks\n- Test with different models to find right balance\n\n### argument-hint\n\n**Type:** String\n**Required:** No\n**Default:** None\n\n**Purpose:** Document expected arguments for users and autocomplete\n\n**Format:**\n```yaml\nargument-hint: [arg1] [arg2] [optional-arg]\n```\n\n**Examples:**\n\n**Single argument:**\n```yaml\nargument-hint: [pr-number]\n```\n\n**Multiple required arguments:**\n```yaml\nargument-hint: [environment] [version]\n```\n\n**Optional arguments:**\n```yaml\nargument-hint: [file-path] [options]\n```\n\n**Descriptive names:**\n```yaml\nargument-hint: [source-branch] [target-branch] [commit-message]\n```\n\n**Best practices:**\n- Use square brackets `[]` for each argument\n- Use descriptive names (not `arg1`, `arg2`)\n- Indicate optional vs required in description\n- Match order to positional arguments in command\n- Keep concise but clear\n\n**Examples by pattern:**\n\n**Simple command:**\n```yaml\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$1...\n```\n\n**Multi-argument:**\n```yaml\n---\ndescription: Deploy to environment\nargument-hint: [app-name] [environment] [version]\n---\n\nDeploy $1 to $2 using version $3...\n```\n\n**With options:**\n```yaml\n---\ndescription: Run tests with options\nargument-hint: [test-pattern] [options]\n---\n\nRun tests matching $1 with options: $2\n```\n\n### disable-model-invocation\n\n**Type:** Boolean\n**Required:** No\n**Default:** false\n\n**Purpose:** Prevent SlashCommand tool from programmatically invoking command\n\n**Examples:**\n```yaml\ndisable-model-invocation: true\n```\n\n**When to use:**\n\n1. **Manual-only commands:** Commands requiring user judgment\n ```yaml\n ---\n description: Approve deployment to production\n disable-model-invocation: true\n ---\n ```\n\n2. **Destructive operations:** Commands with irreversible effects\n ```yaml\n ---\n description: Delete all test data\n disable-model-invocation: true\n ---\n ```\n\n3. **Interactive workflows:** Commands needing user input\n ```yaml\n ---\n description: Walk through setup wizard\n disable-model-invocation: true\n ---\n ```\n\n**Default behavior (false):**\n- Command available to SlashCommand tool\n- Claude can invoke programmatically\n- Still available for manual invocation\n\n**When true:**\n- Command only invokable by user typing `/command`\n- Not available to SlashCommand tool\n- Safer for sensitive operations\n\n**Best practices:**\n- Use sparingly (limits Claude's autonomy)\n- Document why in command comments\n- Consider if command should exist if always manual\n\n## Complete Examples\n\n### Minimal Command\n\nNo frontmatter needed:\n\n```markdown\nReview this code for common issues and suggest improvements.\n```\n\n### Simple Command\n\nJust description:\n\n```markdown\n---\ndescription: Review code for issues\n---\n\nReview this code for common issues and suggest improvements.\n```\n\n### Standard Command\n\nDescription and tools:\n\n```markdown\n---\ndescription: Review Git changes\nallowed-tools: Bash(git:*), Read\n---\n\nCurrent changes: !`git diff --name-only`\n\nReview each changed file for:\n- Code quality\n- Potential bugs\n- Best practices\n```\n\n### Complex Command\n\nAll common fields:\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [app-name] [environment] [version]\nallowed-tools: Bash(kubectl:*), Bash(helm:*), Read\nmodel: sonnet\n---\n\nDeploy $1 to $2 environment using version $3\n\nPre-deployment checks:\n- Verify $2 configuration\n- Check cluster status: !`kubectl cluster-info`\n- Validate version $3 exists\n\nProceed with deployment following deployment runbook.\n```\n\n### Manual-Only Command\n\nRestricted invocation:\n\n```markdown\n---\ndescription: Approve production deployment\nargument-hint: [deployment-id]\ndisable-model-invocation: true\nallowed-tools: Bash(gh:*)\n---\n\n\n\nReview deployment $1 for production approval:\n\nDeployment details: !`gh api /deployments/$1`\n\nVerify:\n- All tests passed\n- Security scan clean\n- Stakeholder approval\n- Rollback plan ready\n\nType \"APPROVED\" to confirm deployment.\n```\n\n## Validation\n\n### Common Errors\n\n**Invalid YAML syntax:**\n```yaml\n---\ndescription: Missing quote\nallowed-tools: Read, Write\nmodel: sonnet\n--- # ❌ Missing closing quote above\n```\n\n**Fix:** Validate YAML syntax\n\n**Incorrect tool specification:**\n```yaml\nallowed-tools: Bash # ❌ Missing command filter\n```\n\n**Fix:** Use `Bash(git:*)` format\n\n**Invalid model name:**\n```yaml\nmodel: gpt4 # ❌ Not a valid Claude model\n```\n\n**Fix:** Use `sonnet`, `opus`, or `haiku`\n\n### Validation Checklist\n\nBefore committing command:\n- [ ] YAML syntax valid (no errors)\n- [ ] Description under 60 characters\n- [ ] allowed-tools uses proper format\n- [ ] model is valid value if specified\n- [ ] argument-hint matches positional arguments\n- [ ] disable-model-invocation used appropriately\n\n## Best Practices Summary\n\n1. **Start minimal:** Add frontmatter only when needed\n2. **Document arguments:** Always use argument-hint with arguments\n3. **Restrict tools:** Use most restrictive allowed-tools that works\n4. **Choose right model:** Use haiku for speed, opus for complexity\n5. **Manual-only sparingly:** Only use disable-model-invocation when necessary\n6. **Clear descriptions:** Make commands discoverable in `/help`\n7. **Test thoroughly:** Verify frontmatter works as expected\n\n\n# Interactive Command Patterns\n\nComprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.\n\n## Overview\n\nSome commands need user input that doesn't work well with simple arguments. For example:\n- Choosing between multiple complex options with trade-offs\n- Selecting multiple items from a list\n- Making decisions that require explanation\n- Gathering preferences or configuration interactively\n\nFor these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments.\n\n## When to Use AskUserQuestion\n\n### Use AskUserQuestion When:\n\n1. **Multiple choice decisions** with explanations needed\n2. **Complex options** that require context to choose\n3. **Multi-select scenarios** (choosing multiple items)\n4. **Preference gathering** for configuration\n5. **Interactive workflows** that adapt based on answers\n\n### Use Command Arguments When:\n\n1. **Simple values** (file paths, numbers, names)\n2. **Known inputs** user already has\n3. **Scriptable workflows** that should be automatable\n4. **Fast invocations** where prompting would slow down\n\n## AskUserQuestion Basics\n\n### Tool Parameters\n\n```typescript\n{\n questions: [\n {\n question: \"Which authentication method should we use?\",\n header: \"Auth method\", // Short label (max 12 chars)\n multiSelect: false, // true for multiple selection\n options: [\n {\n label: \"OAuth 2.0\",\n description: \"Industry standard, supports multiple providers\"\n },\n {\n label: \"JWT\",\n description: \"Stateless, good for APIs\"\n },\n {\n label: \"Session\",\n description: \"Traditional, server-side state\"\n }\n ]\n }\n ]\n}\n```\n\n**Key points:**\n- Users can always choose \"Other\" to provide custom input (automatic)\n- `multiSelect: true` allows selecting multiple options\n- Options should be 2-4 choices (not more)\n- Can ask 1-4 questions per tool call\n\n## Command Pattern for User Interaction\n\n### Basic Interactive Command\n\n```markdown\n---\ndescription: Interactive setup command\nallowed-tools: AskUserQuestion, Write\n---\n\n# Interactive Plugin Setup\n\nThis command will guide you through configuring the plugin with a series of questions.\n\n## Step 1: Gather Configuration\n\nUse the AskUserQuestion tool to ask:\n\n**Question 1 - Deployment target:**\n- header: \"Deploy to\"\n- question: \"Which deployment platform will you use?\"\n- options:\n - AWS (Amazon Web Services with ECS/EKS)\n - GCP (Google Cloud with GKE)\n - Azure (Microsoft Azure with AKS)\n - Local (Docker on local machine)\n\n**Question 2 - Environment strategy:**\n- header: \"Environments\"\n- question: \"How many environments do you need?\"\n- options:\n - Single (Just production)\n - Standard (Dev, Staging, Production)\n - Complete (Dev, QA, Staging, Production)\n\n**Question 3 - Features to enable:**\n- header: \"Features\"\n- question: \"Which features do you want to enable?\"\n- multiSelect: true\n- options:\n - Auto-scaling (Automatic resource scaling)\n - Monitoring (Health checks and metrics)\n - CI/CD (Automated deployment pipeline)\n - Backups (Automated database backups)\n\n## Step 2: Process Answers\n\nBased on the answers received from AskUserQuestion:\n\n1. Parse the deployment target choice\n2. Set up environment-specific configuration\n3. Enable selected features\n4. Generate configuration files\n\n## Step 3: Generate Configuration\n\nCreate `.claude/plugin-name.local.md` with:\n\n\\`\\`\\`yaml\n---\ndeployment_target: [answer from Q1]\nenvironments: [answer from Q2]\nfeatures:\n auto_scaling: [true if selected in Q3]\n monitoring: [true if selected in Q3]\n ci_cd: [true if selected in Q3]\n backups: [true if selected in Q3]\n---\n\n# Plugin Configuration\n\nGenerated: [timestamp]\nTarget: [deployment_target]\nEnvironments: [environments]\n\\`\\`\\`\n\n## Step 4: Confirm and Next Steps\n\nConfirm configuration created and guide user on next steps.\n```\n\n### Multi-Stage Interactive Workflow\n\n```markdown\n---\ndescription: Multi-stage interactive workflow\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Multi-Stage Deployment Setup\n\nThis command walks through deployment setup in stages, adapting based on your answers.\n\n## Stage 1: Basic Configuration\n\nUse AskUserQuestion to ask about deployment basics.\n\nBased on answers, determine which additional questions to ask.\n\n## Stage 2: Advanced Options (Conditional)\n\nIf user selected \"Advanced\" deployment in Stage 1:\n\nUse AskUserQuestion to ask about:\n- Load balancing strategy\n- Caching configuration\n- Security hardening options\n\nIf user selected \"Simple\" deployment:\n- Skip advanced questions\n- Use sensible defaults\n\n## Stage 3: Confirmation\n\nShow summary of all selections.\n\nUse AskUserQuestion for final confirmation:\n- header: \"Confirm\"\n- question: \"Does this configuration look correct?\"\n- options:\n - Yes (Proceed with setup)\n - No (Start over)\n - Modify (Let me adjust specific settings)\n\nIf \"Modify\", ask which specific setting to change.\n\n## Stage 4: Execute Setup\n\nBased on confirmed configuration, execute setup steps.\n```\n\n## Interactive Question Design\n\n### Question Structure\n\n**Good questions:**\n```markdown\nQuestion: \"Which database should we use for this project?\"\nHeader: \"Database\"\nOptions:\n - PostgreSQL (Relational, ACID compliant, best for complex queries)\n - MongoDB (Document store, flexible schema, best for rapid iteration)\n - Redis (In-memory, fast, best for caching and sessions)\n```\n\n**Poor questions:**\n```markdown\nQuestion: \"Database?\" // Too vague\nHeader: \"DB\" // Unclear abbreviation\nOptions:\n - Option 1 // Not descriptive\n - Option 2\n```\n\n### Option Design Best Practices\n\n**Clear labels:**\n- Use 1-5 words\n- Specific and descriptive\n- No jargon without context\n\n**Helpful descriptions:**\n- Explain what the option means\n- Mention key benefits or trade-offs\n- Help user make informed decision\n- Keep to 1-2 sentences\n\n**Appropriate number:**\n- 2-4 options per question\n- Don't overwhelm with too many choices\n- Group related options\n- \"Other\" automatically provided\n\n### Multi-Select Questions\n\n**When to use multiSelect:**\n\n```markdown\nUse AskUserQuestion for enabling features:\n\nQuestion: \"Which features do you want to enable?\"\nHeader: \"Features\"\nmultiSelect: true // Allow selecting multiple\nOptions:\n - Logging (Detailed operation logs)\n - Metrics (Performance monitoring)\n - Alerts (Error notifications)\n - Backups (Automatic backups)\n```\n\nUser can select any combination: none, some, or all.\n\n**When NOT to use multiSelect:**\n\n```markdown\nQuestion: \"Which authentication method?\"\nmultiSelect: false // Only one auth method makes sense\n```\n\nMutually exclusive choices should not use multiSelect.\n\n## Command Patterns with AskUserQuestion\n\n### Pattern 1: Simple Yes/No Decision\n\n```markdown\n---\ndescription: Command with confirmation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Destructive Operation\n\nThis operation will delete all cached data.\n\nUse AskUserQuestion to confirm:\n\nQuestion: \"This will delete all cached data. Are you sure?\"\nHeader: \"Confirm\"\nOptions:\n - Yes (Proceed with deletion)\n - No (Cancel operation)\n\nIf user selects \"Yes\":\n Execute deletion\n Report completion\n\nIf user selects \"No\":\n Cancel operation\n Exit without changes\n```\n\n### Pattern 2: Multiple Configuration Questions\n\n```markdown\n---\ndescription: Multi-question configuration\nallowed-tools: AskUserQuestion, Write\n---\n\n# Project Configuration Setup\n\nGather configuration through multiple questions.\n\nUse AskUserQuestion with multiple questions in one call:\n\n**Question 1:**\n- question: \"Which programming language?\"\n- header: \"Language\"\n- options: Python, TypeScript, Go, Rust\n\n**Question 2:**\n- question: \"Which test framework?\"\n- header: \"Testing\"\n- options: Jest, PyTest, Go Test, Cargo Test\n (Adapt based on language from Q1)\n\n**Question 3:**\n- question: \"Which CI/CD platform?\"\n- header: \"CI/CD\"\n- options: GitHub Actions, GitLab CI, CircleCI\n\n**Question 4:**\n- question: \"Which features do you need?\"\n- header: \"Features\"\n- multiSelect: true\n- options: Linting, Type checking, Code coverage, Security scanning\n\nProcess all answers together to generate cohesive configuration.\n```\n\n### Pattern 3: Conditional Question Flow\n\n```markdown\n---\ndescription: Conditional interactive workflow\nallowed-tools: AskUserQuestion, Read, Write\n---\n\n# Adaptive Configuration\n\n## Question 1: Deployment Complexity\n\nUse AskUserQuestion:\n\nQuestion: \"How complex is your deployment?\"\nHeader: \"Complexity\"\nOptions:\n - Simple (Single server, straightforward)\n - Standard (Multiple servers, load balancing)\n - Complex (Microservices, orchestration)\n\n## Conditional Questions Based on Answer\n\nIf answer is \"Simple\":\n - No additional questions\n - Use minimal configuration\n\nIf answer is \"Standard\":\n - Ask about load balancing strategy\n - Ask about scaling policy\n\nIf answer is \"Complex\":\n - Ask about orchestration platform (Kubernetes, Docker Swarm)\n - Ask about service mesh (Istio, Linkerd, None)\n - Ask about monitoring (Prometheus, Datadog, CloudWatch)\n - Ask about logging aggregation\n\n## Process Conditional Answers\n\nGenerate configuration appropriate for selected complexity level.\n```\n\n### Pattern 4: Iterative Collection\n\n```markdown\n---\ndescription: Collect multiple items iteratively\nallowed-tools: AskUserQuestion, Write\n---\n\n# Collect Team Members\n\nWe'll collect team member information for the project.\n\n## Question: How many team members?\n\nUse AskUserQuestion:\n\nQuestion: \"How many team members should we set up?\"\nHeader: \"Team size\"\nOptions:\n - 2 people\n - 3 people\n - 4 people\n - 6 people\n\n## Iterate Through Team Members\n\nFor each team member (1 to N based on answer):\n\nUse AskUserQuestion for member details:\n\nQuestion: \"What role for team member [number]?\"\nHeader: \"Role\"\nOptions:\n - Frontend Developer\n - Backend Developer\n - DevOps Engineer\n - QA Engineer\n - Designer\n\nStore each member's information.\n\n## Generate Team Configuration\n\nAfter collecting all N members, create team configuration file with all members and their roles.\n```\n\n### Pattern 5: Dependency Selection\n\n```markdown\n---\ndescription: Select dependencies with multi-select\nallowed-tools: AskUserQuestion\n---\n\n# Configure Project Dependencies\n\n## Question: Required Libraries\n\nUse AskUserQuestion with multiSelect:\n\nQuestion: \"Which libraries does your project need?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - React (UI framework)\n - Express (Web server)\n - TypeORM (Database ORM)\n - Jest (Testing framework)\n - Axios (HTTP client)\n\nUser can select any combination.\n\n## Process Selections\n\nFor each selected library:\n- Add to package.json dependencies\n- Generate sample configuration\n- Create usage examples\n- Update documentation\n```\n\n## Best Practices for Interactive Commands\n\n### Question Design\n\n1. **Clear and specific**: Question should be unambiguous\n2. **Concise header**: Max 12 characters for clean display\n3. **Helpful options**: Labels are clear, descriptions explain trade-offs\n4. **Appropriate count**: 2-4 options per question, 1-4 questions per call\n5. **Logical order**: Questions flow naturally\n\n### Error Handling\n\n```markdown\n# Handle AskUserQuestion Responses\n\nAfter calling AskUserQuestion, verify answers received:\n\nIf answers are empty or invalid:\n Something went wrong gathering responses.\n\n Please try again or provide configuration manually:\n [Show alternative approach]\n\n Exit.\n\nIf answers look correct:\n Process as expected\n```\n\n### Progressive Disclosure\n\n```markdown\n# Start Simple, Get Detailed as Needed\n\n## Question 1: Setup Type\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to set up?\"\nHeader: \"Setup type\"\nOptions:\n - Quick (Use recommended defaults)\n - Custom (Configure all options)\n - Guided (Step-by-step with explanations)\n\nIf \"Quick\":\n Apply defaults, minimal questions\n\nIf \"Custom\":\n Ask all available configuration questions\n\nIf \"Guided\":\n Ask questions with extra explanation\n Provide recommendations along the way\n```\n\n### Multi-Select Guidelines\n\n**Good multi-select use:**\n```markdown\nQuestion: \"Which features do you want to enable?\"\nmultiSelect: true\nOptions:\n - Logging\n - Metrics\n - Alerts\n - Backups\n\nReason: User might want any combination\n```\n\n**Bad multi-select use:**\n```markdown\nQuestion: \"Which database engine?\"\nmultiSelect: true // ❌ Should be single-select\n\nReason: Can only use one database engine\n```\n\n## Advanced Patterns\n\n### Validation Loop\n\n```markdown\n---\ndescription: Interactive with validation\nallowed-tools: AskUserQuestion, Bash\n---\n\n# Setup with Validation\n\n## Gather Configuration\n\nUse AskUserQuestion to collect settings.\n\n## Validate Configuration\n\nCheck if configuration is valid:\n- Required dependencies available?\n- Settings compatible with each other?\n- No conflicts detected?\n\nIf validation fails:\n Show validation errors\n\n Use AskUserQuestion to ask:\n\n Question: \"Configuration has issues. What would you like to do?\"\n Header: \"Next step\"\n Options:\n - Fix (Adjust settings to resolve issues)\n - Override (Proceed despite warnings)\n - Cancel (Abort setup)\n\n Based on answer, retry or proceed or exit.\n```\n\n### Build Configuration Incrementally\n\n```markdown\n---\ndescription: Incremental configuration builder\nallowed-tools: AskUserQuestion, Write, Read\n---\n\n# Incremental Setup\n\n## Phase 1: Core Settings\n\nUse AskUserQuestion for core settings.\n\nSave to `.claude/config-partial.yml`\n\n## Phase 2: Review Core Settings\n\nShow user the core settings:\n\nBased on these core settings, you need to configure:\n- [Setting A] (because you chose [X])\n- [Setting B] (because you chose [Y])\n\nReady to continue?\n\n## Phase 3: Detailed Settings\n\nUse AskUserQuestion for settings based on Phase 1 answers.\n\nMerge with core settings.\n\n## Phase 4: Final Review\n\nPresent complete configuration.\n\nUse AskUserQuestion for confirmation:\n\nQuestion: \"Is this configuration correct?\"\nOptions:\n - Yes (Save and apply)\n - No (Start over)\n - Modify (Edit specific settings)\n```\n\n### Dynamic Options Based on Context\n\n```markdown\n---\ndescription: Context-aware questions\nallowed-tools: AskUserQuestion, Bash, Read\n---\n\n# Context-Aware Setup\n\n## Detect Current State\n\nCheck existing configuration:\n- Current language: !`detect-language.sh`\n- Existing frameworks: !`detect-frameworks.sh`\n- Available tools: !`check-tools.sh`\n\n## Ask Context-Appropriate Questions\n\nBased on detected language, ask relevant questions.\n\nIf language is TypeScript:\n\n Use AskUserQuestion:\n\n Question: \"Which TypeScript features should we enable?\"\n Options:\n - Strict Mode (Maximum type safety)\n - Decorators (Experimental decorator support)\n - Path Mapping (Module path aliases)\n\nIf language is Python:\n\n Use AskUserQuestion:\n\n Question: \"Which Python tools should we configure?\"\n Options:\n - Type Hints (mypy for type checking)\n - Black (Code formatting)\n - Pylint (Linting and style)\n\nQuestions adapt to project context.\n```\n\n## Real-World Example: Multi-Agent Swarm Launch\n\n**From multi-agent-swarm plugin:**\n\n```markdown\n---\ndescription: Launch multi-agent swarm\nallowed-tools: AskUserQuestion, Read, Write, Bash\n---\n\n# Launch Multi-Agent Swarm\n\n## Interactive Mode (No Task List Provided)\n\nIf user didn't provide task list file, help create one interactively.\n\n### Question 1: Agent Count\n\nUse AskUserQuestion:\n\nQuestion: \"How many agents should we launch?\"\nHeader: \"Agent count\"\nOptions:\n - 2 agents (Best for simple projects)\n - 3 agents (Good for medium projects)\n - 4 agents (Standard team size)\n - 6 agents (Large projects)\n - 8 agents (Complex multi-component projects)\n\n### Question 2: Task Definition Approach\n\nUse AskUserQuestion:\n\nQuestion: \"How would you like to define tasks?\"\nHeader: \"Task setup\"\nOptions:\n - File (I have a task list file ready)\n - Guided (Help me create tasks interactively)\n - Custom (Other approach)\n\nIf \"File\":\n Ask for file path\n Validate file exists and has correct format\n\nIf \"Guided\":\n Enter iterative task creation mode (see below)\n\n### Question 3: Coordination Mode\n\nUse AskUserQuestion:\n\nQuestion: \"How should agents coordinate?\"\nHeader: \"Coordination\"\nOptions:\n - Team Leader (One agent coordinates others)\n - Collaborative (Agents coordinate as peers)\n - Autonomous (Independent work, minimal coordination)\n\n### Iterative Task Creation (If \"Guided\" Selected)\n\nFor each agent (1 to N from Question 1):\n\n**Question A: Agent Name**\nQuestion: \"What should we call agent [number]?\"\nHeader: \"Agent name\"\nOptions:\n - auth-agent\n - api-agent\n - ui-agent\n - db-agent\n (Provide relevant suggestions based on common patterns)\n\n**Question B: Task Type**\nQuestion: \"What task for [agent-name]?\"\nHeader: \"Task type\"\nOptions:\n - Authentication (User auth, JWT, OAuth)\n - API Endpoints (REST/GraphQL APIs)\n - UI Components (Frontend components)\n - Database (Schema, migrations, queries)\n - Testing (Test suites and coverage)\n - Documentation (Docs, README, guides)\n\n**Question C: Dependencies**\nQuestion: \"What does [agent-name] depend on?\"\nHeader: \"Dependencies\"\nmultiSelect: true\nOptions:\n - [List of previously defined agents]\n - No dependencies\n\n**Question D: Base Branch**\nQuestion: \"Which base branch for PR?\"\nHeader: \"PR base\"\nOptions:\n - main\n - staging\n - develop\n\nStore all task information for each agent.\n\n### Generate Task List File\n\nAfter collecting all agent task details:\n\n1. Ask for project name\n2. Generate task list in proper format\n3. Save to `.daisy/swarm/tasks.md`\n4. Show user the file path\n5. Proceed with launch using generated task list\n```\n\n## Best Practices\n\n### Question Writing\n\n1. **Be specific**: \"Which database?\" not \"Choose option?\"\n2. **Explain trade-offs**: Describe pros/cons in option descriptions\n3. **Provide context**: Question text should stand alone\n4. **Guide decisions**: Help user make informed choice\n5. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences\n\n### Option Design\n\n1. **Meaningful labels**: Specific, clear names\n2. **Informative descriptions**: Explain what each option does\n3. **Show trade-offs**: Help user understand implications\n4. **Consistent detail**: All options equally explained\n5. **2-4 options**: Not too few, not too many\n\n### Flow Design\n\n1. **Logical order**: Questions flow naturally\n2. **Build on previous**: Later questions use earlier answers\n3. **Minimize questions**: Ask only what's needed\n4. **Group related**: Ask related questions together\n5. **Show progress**: Indicate where in flow\n\n### User Experience\n\n1. **Set expectations**: Tell user what to expect\n2. **Explain why**: Help user understand purpose\n3. **Provide defaults**: Suggest recommended options\n4. **Allow escape**: Let user cancel or restart\n5. **Confirm actions**: Summarize before executing\n\n## Common Patterns\n\n### Pattern: Feature Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which features do you need?\"\nHeader: \"Features\"\nmultiSelect: true\nOptions:\n - Authentication\n - Authorization\n - Rate Limiting\n - Caching\n```\n\n### Pattern: Environment Configuration\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"Which environment is this?\"\nHeader: \"Environment\"\nOptions:\n - Development (Local development)\n - Staging (Pre-production testing)\n - Production (Live environment)\n```\n\n### Pattern: Priority Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What's the priority for this task?\"\nHeader: \"Priority\"\nOptions:\n - Critical (Must be done immediately)\n - High (Important, do soon)\n - Medium (Standard priority)\n - Low (Nice to have)\n```\n\n### Pattern: Scope Selection\n\n```markdown\nUse AskUserQuestion:\n\nQuestion: \"What scope should we analyze?\"\nHeader: \"Scope\"\nOptions:\n - Current file (Just this file)\n - Current directory (All files in directory)\n - Entire project (Full codebase scan)\n```\n\n## Combining Arguments and Questions\n\n### Use Both Appropriately\n\n**Arguments for known values:**\n```markdown\n---\nargument-hint: [project-name]\nallowed-tools: AskUserQuestion, Write\n---\n\nSetup for project: $1\n\nNow gather additional configuration...\n\nUse AskUserQuestion for options that require explanation.\n```\n\n**Questions for complex choices:**\n```markdown\nProject name from argument: $1\n\nNow use AskUserQuestion to choose:\n- Architecture pattern\n- Technology stack\n- Deployment strategy\n\nThese require explanation, so questions work better than arguments.\n```\n\n## Troubleshooting\n\n**Questions not appearing:**\n- Verify AskUserQuestion in allowed-tools\n- Check question format is correct\n- Ensure options array has 2-4 items\n\n**User can't make selection:**\n- Check option labels are clear\n- Verify descriptions are helpful\n- Consider if too many options\n- Ensure multiSelect setting is correct\n\n**Flow feels confusing:**\n- Reduce number of questions\n- Group related questions\n- Add explanation between stages\n- Show progress through workflow\n\nWith AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.\n\n\n# Marketplace Considerations for Commands\n\nGuidelines for creating commands designed for distribution and marketplace success.\n\n## Overview\n\nCommands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.\n\n## Design for Distribution\n\n### Universal Compatibility\n\n**Cross-platform considerations:**\n\n```markdown\n---\ndescription: Cross-platform command\nallowed-tools: Bash(*)\n---\n\n# Platform-Aware Command\n\nDetecting platform...\n\ncase \"$(uname)\" in\n Darwin*) PLATFORM=\"macOS\" ;;\n Linux*) PLATFORM=\"Linux\" ;;\n MINGW*|MSYS*|CYGWIN*) PLATFORM=\"Windows\" ;;\n *) PLATFORM=\"Unknown\" ;;\nesac\n\nPlatform: $PLATFORM\n\n\nif [ \"$PLATFORM\" = \"Windows\" ]; then\n # Windows-specific handling\n PATH_SEP=\"\\\\\"\n NULL_DEVICE=\"NUL\"\nelse\n # Unix-like handling\n PATH_SEP=\"/\"\n NULL_DEVICE=\"/dev/null\"\nfi\n\n[Platform-appropriate implementation...]\n```\n\n**Avoid platform-specific commands:**\n\n```markdown\n\n!`pbcopy < file.txt`\n\n\nif command -v pbcopy > /dev/null; then\n pbcopy < file.txt\nelif command -v xclip > /dev/null; then\n xclip -selection clipboard < file.txt\nelif command -v clip.exe > /dev/null; then\n cat file.txt | clip.exe\nelse\n echo \"Clipboard not available on this platform\"\nfi\n```\n\n### Minimal Dependencies\n\n**Check for required tools:**\n\n```markdown\n---\ndescription: Dependency-aware command\nallowed-tools: Bash(*)\n---\n\n# Check Dependencies\n\nRequired tools:\n- git\n- jq\n- node\n\nChecking availability...\n\nMISSING_DEPS=\"\"\n\nfor tool in git jq node; do\n if ! command -v $tool > /dev/null; then\n MISSING_DEPS=\"$MISSING_DEPS $tool\"\n fi\ndone\n\nif [ -n \"$MISSING_DEPS\" ]; then\n ❌ ERROR: Missing required dependencies:$MISSING_DEPS\n\n INSTALLATION:\n - git: https://git-scm.com/downloads\n - jq: https://stedolan.github.io/jq/download/\n - node: https://nodejs.org/\n\n Install missing tools and try again.\n\n Exit.\nfi\n\n✓ All dependencies available\n\n[Continue with command...]\n```\n\n**Document optional dependencies:**\n\n```markdown\n\n```\n\n### Graceful Degradation\n\n**Handle missing features:**\n\n```markdown\n---\ndescription: Feature-aware command\n---\n\n# Feature Detection\n\nDetecting available features...\n\nFEATURES=\"\"\n\nif command -v gh > /dev/null; then\n FEATURES=\"$FEATURES github\"\nfi\n\nif command -v docker > /dev/null; then\n FEATURES=\"$FEATURES docker\"\nfi\n\nAvailable features: $FEATURES\n\nif echo \"$FEATURES\" | grep -q \"github\"; then\n # Full functionality with GitHub integration\n echo \"✓ GitHub integration available\"\nelse\n # Reduced functionality without GitHub\n echo \"⚠ Limited functionality: GitHub CLI not installed\"\n echo \" Install 'gh' for full features\"\nfi\n\n[Adapt behavior based on available features...]\n```\n\n## User Experience for Unknown Users\n\n### Clear Onboarding\n\n**First-run experience:**\n\n```markdown\n---\ndescription: Command with onboarding\nallowed-tools: Read, Write\n---\n\n# First Run Check\n\nif [ ! -f \".claude/command-initialized\" ]; then\n **Welcome to Command Name!**\n\n This appears to be your first time using this command.\n\n WHAT THIS COMMAND DOES:\n [Brief explanation of purpose and benefits]\n\n QUICK START:\n 1. Basic usage: /command [arg]\n 2. For help: /command help\n 3. Examples: /command examples\n\n SETUP:\n No additional setup required. You're ready to go!\n\n ✓ Initialization complete\n\n [Create initialization marker]\n\n Ready to proceed with your request...\nfi\n\n[Normal command execution...]\n```\n\n**Progressive feature discovery:**\n\n```markdown\n---\ndescription: Command with tips\n---\n\n# Command Execution\n\n[Main functionality...]\n\n---\n\n💡 TIP: Did you know?\n\nYou can speed up this command with the --fast flag:\n /command --fast [args]\n\nFor more tips: /command tips\n```\n\n### Comprehensive Error Handling\n\n**Anticipate user mistakes:**\n\n```markdown\n---\ndescription: Forgiving command\n---\n\n# User Input Handling\n\nArgument: \"$1\"\n\n\nif [ \"$1\" = \"hlep\" ] || [ \"$1\" = \"hepl\" ]; then\n Did you mean: help?\n\n Showing help instead...\n [Display help]\n\n Exit.\nfi\n\n\nif [ \"$1\" != \"valid-option1\" ] && [ \"$1\" != \"valid-option2\" ]; then\n ❌ Unknown option: $1\n\n Did you mean:\n - valid-option1 (most similar)\n - valid-option2\n\n For all options: /command help\n\n Exit.\nfi\n\n[Command continues...]\n```\n\n**Helpful diagnostics:**\n\n```markdown\n---\ndescription: Diagnostic command\n---\n\n# Operation Failed\n\nThe operation could not complete.\n\n**Diagnostic Information:**\n\nEnvironment:\n- Platform: $(uname)\n- Shell: $SHELL\n- Working directory: $(pwd)\n- Command: /command $@\n\nChecking common issues:\n- Git repository: $(git rev-parse --git-dir 2>&1)\n- Write permissions: $(test -w . && echo \"OK\" || echo \"DENIED\")\n- Required files: $(test -f config.yml && echo \"Found\" || echo \"Missing\")\n\nThis information helps debug the issue.\n\nFor support, include the above diagnostics.\n```\n\n## Distribution Best Practices\n\n### Namespace Awareness\n\n**Avoid name collisions:**\n\n```markdown\n---\ndescription: Namespaced command\n---\n\n\n\n# Plugin Name Command\n\n[Implementation...]\n```\n\n**Document naming rationale:**\n\n```markdown\n\n```\n\n### Configurability\n\n**User preferences:**\n\n```markdown\n---\ndescription: Configurable command\nallowed-tools: Read\n---\n\n# Load User Configuration\n\nDefault configuration:\n- verbose: false\n- color: true\n- max_results: 10\n\nChecking for user config: .claude/plugin-name.local.md\n\nif [ -f \".claude/plugin-name.local.md\" ]; then\n # Parse YAML frontmatter for settings\n VERBOSE=$(grep \"^verbose:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n COLOR=$(grep \"^color:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n MAX_RESULTS=$(grep \"^max_results:\" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')\n\n echo \"✓ Using user configuration\"\nelse\n echo \"Using default configuration\"\n echo \"Create .claude/plugin-name.local.md to customize\"\nfi\n\n[Use configuration in command...]\n```\n\n**Sensible defaults:**\n\n```markdown\n---\ndescription: Command with smart defaults\n---\n\n# Smart Defaults\n\nConfiguration:\n- Format: ${FORMAT:-json} # Defaults to json\n- Output: ${OUTPUT:-stdout} # Defaults to stdout\n- Verbose: ${VERBOSE:-false} # Defaults to false\n\nThese defaults work for 80% of use cases.\n\nOverride with arguments:\n /command --format yaml --output file.txt --verbose\n\nOr set in .claude/plugin-name.local.md:\n\\`\\`\\`yaml\n---\nformat: yaml\noutput: custom.txt\nverbose: true\n---\n\\`\\`\\`\n```\n\n### Version Compatibility\n\n**Version checking:**\n\n```markdown\n---\ndescription: Version-aware command\n---\n\n\n\n# Version Check\n\nCommand version: 2.1.0\nPlugin version: [detect from plugin.json]\n\nif [ \"$PLUGIN_VERSION\" < \"2.0.0\" ]; then\n ❌ ERROR: Incompatible plugin version\n\n This command requires plugin version >= 2.0.0\n Current version: $PLUGIN_VERSION\n\n Update plugin:\n /plugin update plugin-name\n\n Exit.\nfi\n\n✓ Version compatible\n\n[Command continues...]\n```\n\n**Deprecation warnings:**\n\n```markdown\n---\ndescription: Command with deprecation warnings\n---\n\n# Deprecation Check\n\nif [ \"$1\" = \"--old-flag\" ]; then\n ⚠️ DEPRECATION WARNING\n\n The --old-flag option is deprecated as of v2.0.0\n It will be removed in v3.0.0 (est. June 2025)\n\n Use instead: --new-flag\n\n Example:\n Old: /command --old-flag value\n New: /command --new-flag value\n\n See migration guide: /command migrate\n\n Continuing with deprecated behavior for now...\nfi\n\n[Handle both old and new flags during deprecation period...]\n```\n\n## Marketplace Presentation\n\n### Command Discovery\n\n**Descriptive naming:**\n\n```markdown\n---\ndescription: Review pull request with security and quality checks\n---\n\n\n```\n\n```markdown\n---\ndescription: Do the thing\n---\n\n\n```\n\n**Searchable keywords:**\n\n```markdown\n\n```\n\n### Showcase Examples\n\n**Compelling demonstrations:**\n\n```markdown\n---\ndescription: Advanced code analysis command\n---\n\n# Code Analysis Command\n\nThis command performs deep code analysis with actionable insights.\n\n## Demo: Quick Security Audit\n\nTry it now:\n\\`\\`\\`\n/analyze-code src/ --security\n\\`\\`\\`\n\n**What you'll get:**\n- Security vulnerability detection\n- Code quality metrics\n- Performance bottleneck identification\n- Actionable recommendations\n\n**Sample output:**\n\\`\\`\\`\nSecurity Analysis Results\n=========================\n\n🔴 Critical (2):\n - SQL injection risk in users.js:45\n - XSS vulnerability in display.js:23\n\n🟡 Warnings (5):\n - Unvalidated input in api.js:67\n ...\n\nRecommendations:\n1. Fix critical issues immediately\n2. Review warnings before next release\n3. Run /analyze-code --fix for auto-fixes\n\\`\\`\\`\n\n---\n\nReady to analyze your code...\n\n[Command implementation...]\n```\n\n### User Reviews and Feedback\n\n**Feedback mechanism:**\n\n```markdown\n---\ndescription: Command with feedback\n---\n\n# Command Complete\n\n[Command results...]\n\n---\n\n**How was your experience?**\n\nThis helps improve the command for everyone.\n\nRate this command:\n- 👍 Helpful\n- 👎 Not helpful\n- 🐛 Found a bug\n- 💡 Have a suggestion\n\nReply with an emoji or:\n- /command feedback\n\nYour feedback matters!\n```\n\n**Usage analytics preparation:**\n\n```markdown\n\n```\n\n## Quality Standards\n\n### Professional Polish\n\n**Consistent branding:**\n\n```markdown\n---\ndescription: Branded command\n---\n\n# ✨ Command Name\n\nPart of the [Plugin Name] suite\n\n[Command functionality...]\n\n---\n\n**Need Help?**\n- Documentation: https://docs.example.com\n- Support: support@example.com\n- Community: https://community.example.com\n\nPowered by Plugin Name v2.1.0\n```\n\n**Attention to detail:**\n\n```markdown\n\n\n✓ Use proper emoji/symbols consistently\n✓ Align output columns neatly\n✓ Format numbers with thousands separators\n✓ Use color/formatting appropriately\n✓ Provide progress indicators\n✓ Show estimated time remaining\n✓ Confirm successful operations\n```\n\n### Reliability\n\n**Idempotency:**\n\n```markdown\n---\ndescription: Idempotent command\n---\n\n# Safe Repeated Execution\n\nChecking if operation already completed...\n\nif [ -f \".claude/operation-completed.flag\" ]; then\n ℹ️ Operation already completed\n\n Completed at: $(cat .claude/operation-completed.flag)\n\n To re-run:\n 1. Remove flag: rm .claude/operation-completed.flag\n 2. Run command again\n\n Otherwise, no action needed.\n\n Exit.\nfi\n\nPerforming operation...\n\n[Safe, repeatable operation...]\n\nMarking complete...\necho \"$(date)\" > .claude/operation-completed.flag\n```\n\n**Atomic operations:**\n\n```markdown\n---\ndescription: Atomic command\n---\n\n# Atomic Operation\n\nThis operation is atomic - either fully succeeds or fully fails.\n\nCreating temporary workspace...\nTEMP_DIR=$(mktemp -d)\n\nPerforming changes in isolated environment...\n[Make changes in $TEMP_DIR]\n\nif [ $? -eq 0 ]; then\n ✓ Changes validated\n\n Applying changes atomically...\n mv $TEMP_DIR/* ./target/\n\n ✓ Operation complete\nelse\n ❌ Changes failed validation\n\n Rolling back...\n rm -rf $TEMP_DIR\n\n No changes applied. Safe to retry.\nfi\n```\n\n## Testing for Distribution\n\n### Pre-Release Checklist\n\n```markdown\n\n```\n\n### Beta Testing\n\n**Beta release approach:**\n\n```markdown\n---\ndescription: Beta command (v0.9.0)\n---\n\n# 🧪 Beta Command\n\n**This is a beta release**\n\nFeatures may change based on feedback.\n\nBETA STATUS:\n- Version: 0.9.0\n- Stability: Experimental\n- Support: Limited\n- Feedback: Encouraged\n\nKnown limitations:\n- Performance not optimized\n- Some edge cases not handled\n- Documentation incomplete\n\nHelp improve this command:\n- Report issues: /command report-issue\n- Suggest features: /command suggest\n- Join beta testers: /command join-beta\n\n---\n\n[Command implementation...]\n\n---\n\n**Thank you for beta testing!**\n\nYour feedback helps make this command better.\n```\n\n## Maintenance and Updates\n\n### Update Strategy\n\n**Versioned commands:**\n\n```markdown\n\n```\n\n**Update notifications:**\n\n```markdown\n---\ndescription: Update-aware command\n---\n\n# Check for Updates\n\nCurrent version: 2.1.0\nLatest version: [check if available]\n\nif [ \"$CURRENT_VERSION\" != \"$LATEST_VERSION\" ]; then\n 📢 UPDATE AVAILABLE\n\n New version: $LATEST_VERSION\n Current: $CURRENT_VERSION\n\n What's new:\n - Feature improvements\n - Bug fixes\n - Performance enhancements\n\n Update with:\n /plugin update plugin-name\n\n Release notes: https://releases.example.com/v$LATEST_VERSION\nfi\n\n[Command continues...]\n```\n\n## Best Practices Summary\n\n### Distribution Design\n\n1. **Universal**: Works across platforms and environments\n2. **Self-contained**: Minimal dependencies, clear requirements\n3. **Graceful**: Degrades gracefully when features unavailable\n4. **Forgiving**: Anticipates and handles user mistakes\n5. **Helpful**: Clear errors, good defaults, excellent docs\n\n### Marketplace Success\n\n1. **Discoverable**: Clear name, good description, searchable keywords\n2. **Professional**: Polished presentation, consistent branding\n3. **Reliable**: Tested thoroughly, handles edge cases\n4. **Maintainable**: Versioned, updated regularly, supported\n5. **User-focused**: Great UX, responsive to feedback\n\n### Quality Standards\n\n1. **Complete**: Fully documented, all features working\n2. **Tested**: Works in real environments, edge cases handled\n3. **Secure**: No vulnerabilities, safe operations\n4. **Performant**: Reasonable speed, resource-efficient\n5. **Ethical**: Privacy-respecting, user consent\n\nWith these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.\n\n\n# Plugin-Specific Command Features Reference\n\nThis reference covers features and patterns specific to commands bundled in Claude Code plugins.\n\n## Table of Contents\n\n- [Plugin Command Discovery](#plugin-command-discovery)\n- [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable)\n- [Plugin Command Patterns](#plugin-command-patterns)\n- [Integration with Plugin Components](#integration-with-plugin-components)\n- [Validation Patterns](#validation-patterns)\n\n## Plugin Command Discovery\n\n### Auto-Discovery\n\nClaude Code automatically discovers commands in plugins using the following locations:\n\n```\nplugin-name/\n├── commands/ # Auto-discovered commands\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ └── bar.md # /bar (plugin:plugin-name)\n└── plugin.json # Plugin manifest\n```\n\n**Key points:**\n- Commands are discovered at plugin load time\n- No manual registration required\n- Commands appear in `/help` with \"(plugin:plugin-name)\" label\n- Subdirectories create namespaces\n\n### Namespaced Plugin Commands\n\nOrganize commands in subdirectories for logical grouping:\n\n```\nplugin-name/\n└── commands/\n ├── review/\n │ ├── security.md # /security (plugin:plugin-name:review)\n │ └── style.md # /style (plugin:plugin-name:review)\n └── deploy/\n ├── staging.md # /staging (plugin:plugin-name:deploy)\n └── prod.md # /prod (plugin:plugin-name:deploy)\n```\n\n**Namespace behavior:**\n- Subdirectory name becomes namespace\n- Shown as \"(plugin:plugin-name:namespace)\" in `/help`\n- Helps organize related commands\n- Use when plugin has 5+ commands\n\n### Command Naming Conventions\n\n**Plugin command names should:**\n1. Be descriptive and action-oriented\n2. Avoid conflicts with common command names\n3. Use hyphens for multi-word names\n4. Consider prefixing with plugin name for uniqueness\n\n**Examples:**\n```\nGood:\n- /mylyn-sync (plugin-specific prefix)\n- /analyze-performance (descriptive action)\n- /docker-compose-up (clear purpose)\n\nAvoid:\n- /test (conflicts with common name)\n- /run (too generic)\n- /do-stuff (not descriptive)\n```\n\n## CLAUDE_PLUGIN_ROOT Environment Variable\n\n### Purpose\n\n`${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory.\n\n**Why it matters:**\n- Enables portable paths within plugin\n- Allows referencing plugin files and scripts\n- Works across different installations\n- Essential for multi-file plugin operations\n\n### Basic Usage\n\nReference files within your plugin:\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*), Read\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`\n\nRead template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md\n```\n\n**Expands to:**\n```\nRun analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js`\n\nRead template: @/path/to/plugins/plugin-name/templates/report.md\n```\n\n### Common Patterns\n\n#### 1. Executing Plugin Scripts\n\n```markdown\n---\ndescription: Run custom linter from plugin\nallowed-tools: Bash(node:*)\n---\n\nLint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`\n\nReview the linting output and suggest fixes.\n```\n\n#### 2. Loading Configuration Files\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nallowed-tools: Read, Bash(*)\n---\n\nConfiguration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json\n\nDeploy application using the configuration above for $1 environment.\n```\n\n#### 3. Accessing Plugin Resources\n\n```markdown\n---\ndescription: Generate report from template\n---\n\nUse this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md\n\nGenerate a report for @$1 following the template format.\n```\n\n#### 4. Multi-Step Plugin Workflows\n\n```markdown\n---\ndescription: Complete plugin workflow\nallowed-tools: Bash(*), Read\n---\n\nStep 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`\nStep 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\nStep 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`\n\nReview results and report status.\n```\n\n### Best Practices\n\n1. **Always use for plugin-internal paths:**\n ```markdown\n # Good\n @${CLAUDE_PLUGIN_ROOT}/templates/foo.md\n\n # Bad\n @./templates/foo.md # Relative to current directory, not plugin\n ```\n\n2. **Validate file existence:**\n ```markdown\n ---\n description: Use plugin config if exists\n allowed-tools: Bash(test:*), Read\n ---\n\n !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"exists\" || echo \"missing\"`\n\n If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json\n Otherwise, use defaults...\n ```\n\n3. **Document plugin file structure:**\n ```markdown\n \n ```\n\n4. **Combine with arguments:**\n ```markdown\n Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2`\n ```\n\n### Troubleshooting\n\n**Variable not expanding:**\n- Ensure command is loaded from plugin\n- Check bash execution is allowed\n- Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}`\n\n**File not found errors:**\n- Verify file exists in plugin directory\n- Check file path is correct relative to plugin root\n- Ensure file permissions allow reading/execution\n\n**Path with spaces:**\n- Bash commands automatically handle spaces\n- File references work with spaces in paths\n- No special quoting needed\n\n## Plugin Command Patterns\n\n### Pattern 1: Configuration-Based Commands\n\nCommands that load plugin-specific configuration:\n\n```markdown\n---\ndescription: Deploy using plugin settings\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json\n\nDeploy to $1 environment using:\n1. Configuration settings above\n2. Current git branch: !`git branch --show-current`\n3. Application version: !`cat package.json | grep version`\n\nExecute deployment and monitor progress.\n```\n\n**When to use:** Commands that need consistent settings across invocations\n\n### Pattern 2: Template-Based Generation\n\nCommands that use plugin templates:\n\n```markdown\n---\ndescription: Generate documentation from template\nargument-hint: [component-name]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md\n\nGenerate documentation for $1 component following the template structure.\nInclude:\n- Component purpose and usage\n- API reference\n- Examples\n- Testing guidelines\n```\n\n**When to use:** Standardized output generation\n\n### Pattern 3: Multi-Script Workflow\n\nCommands that orchestrate multiple plugin scripts:\n\n```markdown\n---\ndescription: Complete build and test workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nValidate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\n\nReview all outputs and report:\n1. Build status\n2. Validation results\n3. Test results\n4. Recommended next steps\n```\n\n**When to use:** Complex plugin workflows with multiple steps\n\n### Pattern 4: Environment-Aware Commands\n\nCommands that adapt to environment:\n\n```markdown\n---\ndescription: Deploy based on environment\nargument-hint: [dev|staging|prod]\n---\n\nEnvironment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json\n\nEnvironment check: !`echo \"Deploying to: $1\"`\n\nDeploy application using $1 environment configuration.\nVerify deployment and run smoke tests.\n```\n\n**When to use:** Commands that behave differently per environment\n\n### Pattern 5: Plugin Data Management\n\nCommands that manage plugin-specific data:\n\n```markdown\n---\ndescription: Save analysis results to plugin cache\nallowed-tools: Bash(*), Read, Write\n---\n\nCache directory: ${CLAUDE_PLUGIN_ROOT}/cache/\n\nAnalyze @$1 and save results to cache:\n!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`\n\nStore analysis for future reference and comparison.\n```\n\n**When to use:** Commands that need persistent data storage\n\n## Integration with Plugin Components\n\n### Invoking Plugin Agents\n\nCommands can trigger plugin agents using the Task tool:\n\n```markdown\n---\ndescription: Deep analysis using plugin agent\nargument-hint: [file-path]\n---\n\nInitiate deep code analysis of @$1 using the code-analyzer agent.\n\nThe agent will:\n1. Analyze code structure\n2. Identify patterns\n3. Suggest improvements\n4. Generate detailed report\n\nNote: This uses the Task tool to launch the plugin's code-analyzer agent.\n```\n\n**Key points:**\n- Agent must be defined in plugin's `agents/` directory\n- Claude will automatically use Task tool to launch agent\n- Agent has access to same plugin resources\n\n### Invoking Plugin Skills\n\nCommands can reference plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: API documentation with best practices\nargument-hint: [api-file]\n---\n\nDocument the API in @$1 following our API documentation standards.\n\nUse the api-docs-standards skill to ensure documentation includes:\n- Endpoint descriptions\n- Parameter specifications\n- Response formats\n- Error codes\n- Usage examples\n\nNote: This leverages the plugin's api-docs-standards skill for consistency.\n```\n\n**Key points:**\n- Skill must be defined in plugin's `skills/` directory\n- Mention skill by name to hint Claude should invoke it\n- Skills provide specialized domain knowledge\n\n### Coordinating with Plugin Hooks\n\nCommands can be designed to work with plugin hooks:\n\n```markdown\n---\ndescription: Commit with pre-commit validation\nallowed-tools: Bash(git:*)\n---\n\nStage changes: !\\`git add $1\\`\n\nCommit changes: !\\`git commit -m \"$2\"\\`\n\nNote: This commit will trigger the plugin's pre-commit hook for validation.\nReview hook output for any issues.\n```\n\n**Key points:**\n- Hooks execute automatically on events\n- Commands can prepare state for hooks\n- Document hook interaction in command\n\n### Multi-Component Plugin Commands\n\nCommands that coordinate multiple plugin components:\n\n```markdown\n---\ndescription: Comprehensive code review workflow\nargument-hint: [file-path]\n---\n\nFile to review: @$1\n\nExecute comprehensive review:\n\n1. **Static Analysis** (via plugin scripts)\n !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\n2. **Deep Review** (via plugin agent)\n Launch the code-reviewer agent for detailed analysis.\n\n3. **Best Practices** (via plugin skill)\n Use the code-standards skill to ensure compliance.\n\n4. **Documentation** (via plugin template)\n Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md\n\nGenerate final report combining all outputs.\n```\n\n**When to use:** Complex workflows leveraging multiple plugin capabilities\n\n## Validation Patterns\n\n### Input Validation\n\nCommands should validate inputs before processing:\n\n```markdown\n---\ndescription: Deploy to environment with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\n$IF($1 in [dev, staging, prod],\n Deploy to $1 environment using validated configuration,\n ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod\n)\n```\n\n**Validation approaches:**\n1. Bash validation using grep/test\n2. Inline validation in prompt\n3. Script-based validation\n\n### File Existence Checks\n\nVerify required files exist:\n\n```markdown\n---\ndescription: Process configuration file\nargument-hint: [config-file]\n---\n\nCheck file: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nProcess configuration if file exists: @$1\n\nIf file doesn't exist, explain:\n- Expected location\n- Required format\n- How to create it\n```\n\n### Required Arguments\n\nValidate required arguments provided:\n\n```markdown\n---\ndescription: Create deployment with version\nargument-hint: [environment] [version]\n---\n\nValidate inputs: !`test -n \"$1\" -a -n \"$2\" && echo \"OK\" || echo \"MISSING\"`\n\n$IF($1 AND $2,\n Deploy version $2 to $1 environment,\n ERROR: Both environment and version required. Usage: /deploy [env] [version]\n)\n```\n\n### Plugin Resource Validation\n\nVerify plugin resources available:\n\n```markdown\n---\ndescription: Run analysis with plugin tools\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n- Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo \"✓\" || echo \"✗\"`\n- Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, proceed with analysis.\nOtherwise, report missing components and installation steps.\n```\n\n### Output Validation\n\nValidate command execution results:\n\n```markdown\n---\ndescription: Build and validate output\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\n\nValidate output:\n- Exit code: !`echo $?`\n- Output exists: !`test -d dist && echo \"✓\" || echo \"✗\"`\n- File count: !`find dist -type f | wc -l`\n\nReport build status and any validation failures.\n```\n\n### Graceful Error Handling\n\nHandle errors gracefully with helpful messages:\n\n```markdown\n---\ndescription: Process file with error handling\nargument-hint: [file-path]\n---\n\nTry processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo \"ERROR: $?\"`\n\nIf processing succeeded:\n- Report results\n- Suggest next steps\n\nIf processing failed:\n- Explain likely causes\n- Provide troubleshooting steps\n- Suggest alternative approaches\n```\n\n## Best Practices Summary\n\n### Plugin Commands Should:\n\n1. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths**\n - Scripts, templates, configuration, resources\n\n2. **Validate inputs early**\n - Check required arguments\n - Verify file existence\n - Validate argument formats\n\n3. **Document plugin structure**\n - Explain required files\n - Document script purposes\n - Clarify dependencies\n\n4. **Integrate with plugin components**\n - Reference agents for complex tasks\n - Use skills for specialized knowledge\n - Coordinate with hooks when relevant\n\n5. **Provide helpful error messages**\n - Explain what went wrong\n - Suggest how to fix\n - Offer alternatives\n\n6. **Handle edge cases**\n - Missing files\n - Invalid arguments\n - Failed script execution\n - Missing dependencies\n\n7. **Keep commands focused**\n - One clear purpose per command\n - Delegate complex logic to scripts\n - Use agents for multi-step workflows\n\n8. **Test across installations**\n - Verify paths work everywhere\n - Test with different arguments\n - Validate error cases\n\n---\n\nFor general command development, see main SKILL.md.\nFor command examples, see examples/ directory.\n\n\n# Command Testing Strategies\n\nComprehensive strategies for testing slash commands before deployment and distribution.\n\n## Overview\n\nTesting commands ensures they work correctly, handle edge cases, and provide good user experience. A systematic testing approach catches issues early and builds confidence in command reliability.\n\n## Testing Levels\n\n### Level 1: Syntax and Structure Validation\n\n**What to test:**\n- YAML frontmatter syntax\n- Markdown format\n- File location and naming\n\n**How to test:**\n\n```bash\n# Validate YAML frontmatter\nhead -n 20 .claude/commands/my-command.md | grep -A 10 \"^---\"\n\n# Check for closing frontmatter marker\nhead -n 20 .claude/commands/my-command.md | grep -c \"^---\" # Should be 2\n\n# Verify file has .md extension\nls .claude/commands/*.md\n\n# Check file is in correct location\ntest -f .claude/commands/my-command.md && echo \"Found\" || echo \"Missing\"\n```\n\n**Automated validation script:**\n\n```bash\n#!/bin/bash\n# validate-command.sh\n\nCOMMAND_FILE=\"$1\"\n\nif [ ! -f \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File not found: $COMMAND_FILE\"\n exit 1\nfi\n\n# Check .md extension\nif [[ ! \"$COMMAND_FILE\" =~ \\.md$ ]]; then\n echo \"ERROR: File must have .md extension\"\n exit 1\nfi\n\n# Validate YAML frontmatter if present\nif head -n 1 \"$COMMAND_FILE\" | grep -q \"^---\"; then\n # Count frontmatter markers\n MARKERS=$(head -n 50 \"$COMMAND_FILE\" | grep -c \"^---\")\n if [ \"$MARKERS\" -ne 2 ]; then\n echo \"ERROR: Invalid YAML frontmatter (need exactly 2 '---' markers)\"\n exit 1\n fi\n echo \"✓ YAML frontmatter syntax valid\"\nfi\n\n# Check for empty file\nif [ ! -s \"$COMMAND_FILE\" ]; then\n echo \"ERROR: File is empty\"\n exit 1\nfi\n\necho \"✓ Command file structure valid\"\n```\n\n### Level 2: Frontmatter Field Validation\n\n**What to test:**\n- Field types correct\n- Values in valid ranges\n- Required fields present (if any)\n\n**Validation script:**\n\n```bash\n#!/bin/bash\n# validate-frontmatter.sh\n\nCOMMAND_FILE=\"$1\"\n\n# Extract YAML frontmatter\nFRONTMATTER=$(sed -n '/^---$/,/^---$/p' \"$COMMAND_FILE\" | sed '1d;$d')\n\nif [ -z \"$FRONTMATTER\" ]; then\n echo \"No frontmatter to validate\"\n exit 0\nfi\n\n# Check 'model' field if present\nif echo \"$FRONTMATTER\" | grep -q \"^model:\"; then\n MODEL=$(echo \"$FRONTMATTER\" | grep \"^model:\" | cut -d: -f2 | tr -d ' ')\n if ! echo \"sonnet opus haiku\" | grep -qw \"$MODEL\"; then\n echo \"ERROR: Invalid model '$MODEL' (must be sonnet, opus, or haiku)\"\n exit 1\n fi\n echo \"✓ Model field valid: $MODEL\"\nfi\n\n# Check 'allowed-tools' field format\nif echo \"$FRONTMATTER\" | grep -q \"^allowed-tools:\"; then\n echo \"✓ allowed-tools field present\"\n # Could add more sophisticated validation here\nfi\n\n# Check 'description' length\nif echo \"$FRONTMATTER\" | grep -q \"^description:\"; then\n DESC=$(echo \"$FRONTMATTER\" | grep \"^description:\" | cut -d: -f2-)\n LENGTH=${#DESC}\n if [ \"$LENGTH\" -gt 80 ]; then\n echo \"WARNING: Description length $LENGTH (recommend < 60 chars)\"\n else\n echo \"✓ Description length acceptable: $LENGTH chars\"\n fi\nfi\n\necho \"✓ Frontmatter fields valid\"\n```\n\n### Level 3: Manual Command Invocation\n\n**What to test:**\n- Command appears in `/help`\n- Command executes without errors\n- Output is as expected\n\n**Test procedure:**\n\n```bash\n# 1. Start Claude Code\nclaude --debug\n\n# 2. Check command appears in help\n> /help\n# Look for your command in the list\n\n# 3. Invoke command without arguments\n> /my-command\n# Check for reasonable error or behavior\n\n# 4. Invoke with valid arguments\n> /my-command arg1 arg2\n# Verify expected behavior\n\n# 5. Check debug logs\ntail -f ~/.claude/debug-logs/latest\n# Look for errors or warnings\n```\n\n### Level 4: Argument Testing\n\n**What to test:**\n- Positional arguments work ($1, $2, etc.)\n- $ARGUMENTS captures all arguments\n- Missing arguments handled gracefully\n- Invalid arguments detected\n\n**Test matrix:**\n\n| Test Case | Command | Expected Result |\n|-----------|---------|-----------------|\n| No args | `/cmd` | Graceful handling or useful message |\n| One arg | `/cmd arg1` | $1 substituted correctly |\n| Two args | `/cmd arg1 arg2` | $1 and $2 substituted |\n| Extra args | `/cmd a b c d` | All captured or extras ignored appropriately |\n| Special chars | `/cmd \"arg with spaces\"` | Quotes handled correctly |\n| Empty arg | `/cmd \"\"` | Empty string handled |\n\n**Test script:**\n\n```bash\n#!/bin/bash\n# test-command-arguments.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing argument handling for /$COMMAND\"\necho\n\necho \"Test 1: No arguments\"\necho \" Command: /$COMMAND\"\necho \" Expected: [describe expected behavior]\"\necho \" Manual test required\"\necho\n\necho \"Test 2: Single argument\"\necho \" Command: /$COMMAND test-value\"\necho \" Expected: 'test-value' appears in output\"\necho \" Manual test required\"\necho\n\necho \"Test 3: Multiple arguments\"\necho \" Command: /$COMMAND arg1 arg2 arg3\"\necho \" Expected: All arguments used appropriately\"\necho \" Manual test required\"\necho\n\necho \"Test 4: Special characters\"\necho \" Command: /$COMMAND \\\"value with spaces\\\"\"\necho \" Expected: Entire phrase captured\"\necho \" Manual test required\"\n```\n\n### Level 5: File Reference Testing\n\n**What to test:**\n- @ syntax loads file contents\n- Non-existent files handled\n- Large files handled appropriately\n- Multiple file references work\n\n**Test procedure:**\n\n```bash\n# Create test files\necho \"Test content\" > /tmp/test-file.txt\necho \"Second file\" > /tmp/test-file-2.txt\n\n# Test single file reference\n> /my-command /tmp/test-file.txt\n# Verify file content is read\n\n# Test non-existent file\n> /my-command /tmp/nonexistent.txt\n# Verify graceful error handling\n\n# Test multiple files\n> /my-command /tmp/test-file.txt /tmp/test-file-2.txt\n# Verify both files processed\n\n# Test large file\ndd if=/dev/zero of=/tmp/large-file.bin bs=1M count=100\n> /my-command /tmp/large-file.bin\n# Verify reasonable behavior (may truncate or warn)\n\n# Cleanup\nrm /tmp/test-file*.txt /tmp/large-file.bin\n```\n\n### Level 6: Bash Execution Testing\n\n**What to test:**\n- !` commands execute correctly\n- Command output included in prompt\n- Command failures handled\n- Security: only allowed commands run\n\n**Test procedure:**\n\n```bash\n# Create test command with bash execution\ncat > .claude/commands/test-bash.md << 'EOF'\n---\ndescription: Test bash execution\nallowed-tools: Bash(echo:*), Bash(date:*)\n---\n\nCurrent date: !`date`\nTest output: !`echo \"Hello from bash\"`\n\nAnalysis of output above...\nEOF\n\n# Test in Claude Code\n> /test-bash\n# Verify:\n# 1. Date appears correctly\n# 2. Echo output appears\n# 3. No errors in debug logs\n\n# Test with disallowed command (should fail or be blocked)\ncat > .claude/commands/test-forbidden.md << 'EOF'\n---\ndescription: Test forbidden command\nallowed-tools: Bash(echo:*)\n---\n\nTrying forbidden: !`ls -la /`\nEOF\n\n> /test-forbidden\n# Verify: Permission denied or appropriate error\n```\n\n### Level 7: Integration Testing\n\n**What to test:**\n- Commands work with other plugin components\n- Commands interact correctly with each other\n- State management works across invocations\n- Workflow commands execute in sequence\n\n**Test scenarios:**\n\n**Scenario 1: Command + Hook Integration**\n\n```bash\n# Setup: Command that triggers a hook\n# Test: Invoke command, verify hook executes\n\n# Command: .claude/commands/risky-operation.md\n# Hook: PreToolUse that validates the operation\n\n> /risky-operation\n# Verify: Hook executes and validates before command completes\n```\n\n**Scenario 2: Command Sequence**\n\n```bash\n# Setup: Multi-command workflow\n> /workflow-init\n# Verify: State file created\n\n> /workflow-step2\n# Verify: State file read, step 2 executes\n\n> /workflow-complete\n# Verify: State file cleaned up\n```\n\n**Scenario 3: Command + MCP Integration**\n\n```bash\n# Setup: Command uses MCP tools\n# Test: Verify MCP server accessible\n\n> /mcp-command\n# Verify:\n# 1. MCP server starts (if stdio)\n# 2. Tool calls succeed\n# 3. Results included in output\n```\n\n## Automated Testing Approaches\n\n### Command Test Suite\n\nCreate a test suite script:\n\n```bash\n#!/bin/bash\n# test-commands.sh - Command test suite\n\nTEST_DIR=\".claude/commands\"\nFAILED_TESTS=0\n\necho \"Command Test Suite\"\necho \"==================\"\necho\n\nfor cmd_file in \"$TEST_DIR\"/*.md; do\n cmd_name=$(basename \"$cmd_file\" .md)\n echo \"Testing: $cmd_name\"\n\n # Validate structure\n if ./validate-command.sh \"$cmd_file\"; then\n echo \" ✓ Structure valid\"\n else\n echo \" ✗ Structure invalid\"\n ((FAILED_TESTS++))\n fi\n\n # Validate frontmatter\n if ./validate-frontmatter.sh \"$cmd_file\"; then\n echo \" ✓ Frontmatter valid\"\n else\n echo \" ✗ Frontmatter invalid\"\n ((FAILED_TESTS++))\n fi\n\n echo\ndone\n\necho \"==================\"\necho \"Tests complete\"\necho \"Failed: $FAILED_TESTS\"\n\nexit $FAILED_TESTS\n```\n\n### Pre-Commit Hook\n\nValidate commands before committing:\n\n```bash\n#!/bin/bash\n# .git/hooks/pre-commit\n\necho \"Validating commands...\"\n\nCOMMANDS_CHANGED=$(git diff --cached --name-only | grep \"\\.claude/commands/.*\\.md\")\n\nif [ -z \"$COMMANDS_CHANGED\" ]; then\n echo \"No commands changed\"\n exit 0\nfi\n\nfor cmd in $COMMANDS_CHANGED; do\n echo \"Checking: $cmd\"\n\n if ! ./scripts/validate-command.sh \"$cmd\"; then\n echo \"ERROR: Command validation failed: $cmd\"\n exit 1\n fi\ndone\n\necho \"✓ All commands valid\"\n```\n\n### Continuous Testing\n\nTest commands in CI/CD:\n\n```yaml\n# .github/workflows/test-commands.yml\nname: Test Commands\n\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n\n - name: Validate command structure\n run: |\n for cmd in .claude/commands/*.md; do\n echo \"Testing: $cmd\"\n ./scripts/validate-command.sh \"$cmd\"\n done\n\n - name: Validate frontmatter\n run: |\n for cmd in .claude/commands/*.md; do\n ./scripts/validate-frontmatter.sh \"$cmd\"\n done\n\n - name: Check for TODOs\n run: |\n if grep -r \"TODO\" .claude/commands/; then\n echo \"ERROR: TODOs found in commands\"\n exit 1\n fi\n```\n\n## Edge Case Testing\n\n### Test Edge Cases\n\n**Empty arguments:**\n```bash\n> /cmd \"\"\n> /cmd '' ''\n```\n\n**Special characters:**\n```bash\n> /cmd \"arg with spaces\"\n> /cmd arg-with-dashes\n> /cmd arg_with_underscores\n> /cmd arg/with/slashes\n> /cmd 'arg with \"quotes\"'\n```\n\n**Long arguments:**\n```bash\n> /cmd $(python -c \"print('a' * 10000)\")\n```\n\n**Unusual file paths:**\n```bash\n> /cmd ./file\n> /cmd ../file\n> /cmd ~/file\n> /cmd \"/path with spaces/file\"\n```\n\n**Bash command edge cases:**\n```markdown\n# Commands that might fail\n!`exit 1`\n!`false`\n!`command-that-does-not-exist`\n\n# Commands with special output\n!`echo \"\"`\n!`cat /dev/null`\n!`yes | head -n 1000000`\n```\n\n## Performance Testing\n\n### Response Time Testing\n\n```bash\n#!/bin/bash\n# test-command-performance.sh\n\nCOMMAND=\"$1\"\n\necho \"Testing performance of /$COMMAND\"\necho\n\nfor i in {1..5}; do\n echo \"Run $i:\"\n START=$(date +%s%N)\n\n # Invoke command (manual step - record time)\n echo \" Invoke: /$COMMAND\"\n echo \" Start time: $START\"\n echo \" (Record end time manually)\"\n echo\ndone\n\necho \"Analyze results:\"\necho \" - Average response time\"\necho \" - Variance\"\necho \" - Acceptable threshold: < 3 seconds for fast commands\"\n```\n\n### Resource Usage Testing\n\n```bash\n# Monitor Claude Code during command execution\n# In terminal 1:\nclaude --debug\n\n# In terminal 2:\nwatch -n 1 'ps aux | grep claude'\n\n# Execute command and observe:\n# - Memory usage\n# - CPU usage\n# - Process count\n```\n\n## User Experience Testing\n\n### Usability Checklist\n\n- [ ] Command name is intuitive\n- [ ] Description is clear in `/help`\n- [ ] Arguments are well-documented\n- [ ] Error messages are helpful\n- [ ] Output is formatted readably\n- [ ] Long-running commands show progress\n- [ ] Results are actionable\n- [ ] Edge cases have good UX\n\n### User Acceptance Testing\n\nRecruit testers:\n\n```markdown\n# Testing Guide for Beta Testers\n\n## Command: /my-new-command\n\n### Test Scenarios\n\n1. **Basic usage:**\n - Run: `/my-new-command`\n - Expected: [describe]\n - Rate clarity: 1-5\n\n2. **With arguments:**\n - Run: `/my-new-command arg1 arg2`\n - Expected: [describe]\n - Rate usefulness: 1-5\n\n3. **Error case:**\n - Run: `/my-new-command invalid-input`\n - Expected: Helpful error message\n - Rate error message: 1-5\n\n### Feedback Questions\n\n1. Was the command easy to understand?\n2. Did the output meet your expectations?\n3. What would you change?\n4. Would you use this command regularly?\n```\n\n## Testing Checklist\n\nBefore releasing a command:\n\n### Structure\n- [ ] File in correct location\n- [ ] Correct .md extension\n- [ ] Valid YAML frontmatter (if present)\n- [ ] Markdown syntax correct\n\n### Functionality\n- [ ] Command appears in `/help`\n- [ ] Description is clear\n- [ ] Command executes without errors\n- [ ] Arguments work as expected\n- [ ] File references work\n- [ ] Bash execution works (if used)\n\n### Edge Cases\n- [ ] Missing arguments handled\n- [ ] Invalid arguments detected\n- [ ] Non-existent files handled\n- [ ] Special characters work\n- [ ] Long inputs handled\n\n### Integration\n- [ ] Works with other commands\n- [ ] Works with hooks (if applicable)\n- [ ] Works with MCP (if applicable)\n- [ ] State management works\n\n### Quality\n- [ ] Performance acceptable\n- [ ] No security issues\n- [ ] Error messages helpful\n- [ ] Output formatted well\n- [ ] Documentation complete\n\n### Distribution\n- [ ] Tested by others\n- [ ] Feedback incorporated\n- [ ] README updated\n- [ ] Examples provided\n\n## Debugging Failed Tests\n\n### Common Issues and Solutions\n\n**Issue: Command not appearing in /help**\n\n```bash\n# Check file location\nls -la .claude/commands/my-command.md\n\n# Check permissions\nchmod 644 .claude/commands/my-command.md\n\n# Check syntax\nhead -n 20 .claude/commands/my-command.md\n\n# Restart Claude Code\nclaude --debug\n```\n\n**Issue: Arguments not substituting**\n\n```bash\n# Verify syntax\ngrep '\\$1' .claude/commands/my-command.md\ngrep '\\$ARGUMENTS' .claude/commands/my-command.md\n\n# Test with simple command first\necho \"Test: \\$1 and \\$2\" > .claude/commands/test-args.md\n```\n\n**Issue: Bash commands not executing**\n\n```bash\n# Check allowed-tools\ngrep \"allowed-tools\" .claude/commands/my-command.md\n\n# Verify command syntax\ngrep '!\\`' .claude/commands/my-command.md\n\n# Test command manually\ndate\necho \"test\"\n```\n\n**Issue: File references not working**\n\n```bash\n# Check @ syntax\ngrep '@' .claude/commands/my-command.md\n\n# Verify file exists\nls -la /path/to/referenced/file\n\n# Check permissions\nchmod 644 /path/to/referenced/file\n```\n\n## Best Practices\n\n1. **Test early, test often**: Validate as you develop\n2. **Automate validation**: Use scripts for repeatable checks\n3. **Test edge cases**: Don't just test the happy path\n4. **Get feedback**: Have others test before wide release\n5. **Document tests**: Keep test scenarios for regression testing\n6. **Monitor in production**: Watch for issues after release\n7. **Iterate**: Improve based on real usage data\n\n\n---\nname: Command Development\ndescription: This skill should be used when the user asks to \"create a slash command\", \"add a command\", \"write a custom command\", \"define command arguments\", \"use command frontmatter\", \"organize commands\", \"create command with file references\", \"interactive command\", \"use AskUserQuestion in command\", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.\nversion: 0.2.0\n---\n\n# Command Development for Claude Code\n\n## Overview\n\nSlash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.\n\n**Key concepts:**\n- Markdown file format for commands\n- YAML frontmatter for configuration\n- Dynamic arguments and file references\n- Bash execution for context\n- Command organization and namespacing\n\n## Command Basics\n\n### What is a Slash Command?\n\nA slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:\n- **Reusability**: Define once, use repeatedly\n- **Consistency**: Standardize common workflows\n- **Sharing**: Distribute across team or projects\n- **Efficiency**: Quick access to complex prompts\n\n### Critical: Commands are Instructions FOR Claude\n\n**Commands are written for agent consumption, not human consumption.**\n\nWhen a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.\n\n**Correct approach (instructions for Claude):**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication issues\n\nProvide specific line numbers and severity ratings.\n```\n\n**Incorrect approach (messages to user):**\n```markdown\nThis command will review your code for security issues.\nYou'll receive a report with vulnerability details.\n```\n\nThe first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.\n\n### Command Locations\n\n**Project commands** (shared with team):\n- Location: `.claude/commands/`\n- Scope: Available in specific project\n- Label: Shown as \"(project)\" in `/help`\n- Use for: Team workflows, project-specific tasks\n\n**Personal commands** (available everywhere):\n- Location: `~/.claude/commands/`\n- Scope: Available in all projects\n- Label: Shown as \"(user)\" in `/help`\n- Use for: Personal workflows, cross-project utilities\n\n**Plugin commands** (bundled with plugins):\n- Location: `plugin-name/commands/`\n- Scope: Available when plugin installed\n- Label: Shown as \"(plugin-name)\" in `/help`\n- Use for: Plugin-specific functionality\n\n## File Format\n\n### Basic Structure\n\nCommands are Markdown files with `.md` extension:\n\n```\n.claude/commands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**Simple command:**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication bypass\n- Insecure data handling\n```\n\nNo frontmatter needed for basic commands.\n\n### With YAML Frontmatter\n\nAdd configuration using YAML frontmatter:\n\n```markdown\n---\ndescription: Review code for security issues\nallowed-tools: Read, Grep, Bash(git:*)\nmodel: sonnet\n---\n\nReview this code for security vulnerabilities...\n```\n\n## YAML Frontmatter Fields\n\n### description\n\n**Purpose:** Brief description shown in `/help`\n**Type:** String\n**Default:** First line of command prompt\n\n```yaml\n---\ndescription: Review pull request for code quality\n---\n```\n\n**Best practice:** Clear, actionable description (under 60 characters)\n\n### allowed-tools\n\n**Purpose:** Specify which tools command can use\n**Type:** String or Array\n**Default:** Inherits from conversation\n\n```yaml\n---\nallowed-tools: Read, Write, Edit, Bash(git:*)\n---\n```\n\n**Patterns:**\n- `Read, Write, Edit` - Specific tools\n- `Bash(git:*)` - Bash with git commands only\n- `*` - All tools (rarely needed)\n\n**Use when:** Command requires specific tool access\n\n### model\n\n**Purpose:** Specify model for command execution\n**Type:** String (sonnet, opus, haiku)\n**Default:** Inherits from conversation\n\n```yaml\n---\nmodel: haiku\n---\n```\n\n**Use cases:**\n- `haiku` - Fast, simple commands\n- `sonnet` - Standard workflows\n- `opus` - Complex analysis\n\n### argument-hint\n\n**Purpose:** Document expected arguments for autocomplete\n**Type:** String\n**Default:** None\n\n```yaml\n---\nargument-hint: [pr-number] [priority] [assignee]\n---\n```\n\n**Benefits:**\n- Helps users understand command arguments\n- Improves command discovery\n- Documents command interface\n\n### disable-model-invocation\n\n**Purpose:** Prevent SlashCommand tool from programmatically calling command\n**Type:** Boolean\n**Default:** false\n\n```yaml\n---\ndisable-model-invocation: true\n---\n```\n\n**Use when:** Command should only be manually invoked\n\n## Dynamic Arguments\n\n### Using $ARGUMENTS\n\nCapture all arguments as single string:\n\n```markdown\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$ARGUMENTS following our coding standards and best practices.\n```\n\n**Usage:**\n```\n> /fix-issue 123\n> /fix-issue 456\n```\n\n**Expands to:**\n```\nFix issue #123 following our coding standards...\nFix issue #456 following our coding standards...\n```\n\n### Using Positional Arguments\n\nCapture individual arguments with `$1`, `$2`, `$3`, etc.:\n\n```markdown\n---\ndescription: Review PR with priority and assignee\nargument-hint: [pr-number] [priority] [assignee]\n---\n\nReview pull request #$1 with priority level $2.\nAfter review, assign to $3 for follow-up.\n```\n\n**Usage:**\n```\n> /review-pr 123 high alice\n```\n\n**Expands to:**\n```\nReview pull request #123 with priority level high.\nAfter review, assign to alice for follow-up.\n```\n\n### Combining Arguments\n\nMix positional and remaining arguments:\n\n```markdown\nDeploy $1 to $2 environment with options: $3\n```\n\n**Usage:**\n```\n> /deploy api staging --force --skip-tests\n```\n\n**Expands to:**\n```\nDeploy api to staging environment with options: --force --skip-tests\n```\n\n## File References\n\n### Using @ Syntax\n\nInclude file contents in command:\n\n```markdown\n---\ndescription: Review specific file\nargument-hint: [file-path]\n---\n\nReview @$1 for:\n- Code quality\n- Best practices\n- Potential bugs\n```\n\n**Usage:**\n```\n> /review-file src/api/users.ts\n```\n\n**Effect:** Claude reads `src/api/users.ts` before processing command\n\n### Multiple File References\n\nReference multiple files:\n\n```markdown\nCompare @src/old-version.js with @src/new-version.js\n\nIdentify:\n- Breaking changes\n- New features\n- Bug fixes\n```\n\n### Static File References\n\nReference known files without arguments:\n\n```markdown\nReview @package.json and @tsconfig.json for consistency\n\nEnsure:\n- TypeScript version matches\n- Dependencies are aligned\n- Build configuration is correct\n```\n\n## Bash Execution in Commands\n\nCommands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.\n\n**When to use:**\n- Include dynamic context (git status, environment vars, etc.)\n- Gather project/repository state\n- Build context-aware workflows\n\n**Implementation details:**\nFor complete syntax, examples, and best practices, see `references/plugin-features-reference.md` section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues\n\n## Command Organization\n\n### Flat Structure\n\nSimple organization for small command sets:\n\n```\n.claude/commands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**Use when:** 5-15 commands, no clear categories\n\n### Namespaced Structure\n\nOrganize commands in subdirectories:\n\n```\n.claude/commands/\n├── ci/\n│ ├── build.md # /build (project:ci)\n│ ├── test.md # /test (project:ci)\n│ └── lint.md # /lint (project:ci)\n├── git/\n│ ├── commit.md # /commit (project:git)\n│ └── pr.md # /pr (project:git)\n└── docs/\n ├── generate.md # /generate (project:docs)\n └── publish.md # /publish (project:docs)\n```\n\n**Benefits:**\n- Logical grouping by category\n- Namespace shown in `/help`\n- Easier to find related commands\n\n**Use when:** 15+ commands, clear categories\n\n## Best Practices\n\n### Command Design\n\n1. **Single responsibility:** One command, one task\n2. **Clear descriptions:** Self-explanatory in `/help`\n3. **Explicit dependencies:** Use `allowed-tools` when needed\n4. **Document arguments:** Always provide `argument-hint`\n5. **Consistent naming:** Use verb-noun pattern (review-pr, fix-issue)\n\n### Argument Handling\n\n1. **Validate arguments:** Check for required arguments in prompt\n2. **Provide defaults:** Suggest defaults when arguments missing\n3. **Document format:** Explain expected argument format\n4. **Handle edge cases:** Consider missing or invalid arguments\n\n```markdown\n---\nargument-hint: [pr-number]\n---\n\n$IF($1,\n Review PR #$1,\n Please provide a PR number. Usage: /review-pr [number]\n)\n```\n\n### File References\n\n1. **Explicit paths:** Use clear file paths\n2. **Check existence:** Handle missing files gracefully\n3. **Relative paths:** Use project-relative paths\n4. **Glob support:** Consider using Glob tool for patterns\n\n### Bash Commands\n\n1. **Limit scope:** Use `Bash(git:*)` not `Bash(*)`\n2. **Safe commands:** Avoid destructive operations\n3. **Handle errors:** Consider command failures\n4. **Keep fast:** Long-running commands slow invocation\n\n### Documentation\n\n1. **Add comments:** Explain complex logic\n2. **Provide examples:** Show usage in comments\n3. **List requirements:** Document dependencies\n4. **Version commands:** Note breaking changes\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment] [version]\n---\n\n\n\nDeploy application to $1 environment using version $2...\n```\n\n## Common Patterns\n\n### Review Pattern\n\n```markdown\n---\ndescription: Review code changes\nallowed-tools: Read, Bash(git:*)\n---\n\nFiles changed: !`git diff --name-only`\n\nReview each file for:\n1. Code quality and style\n2. Potential bugs or issues\n3. Test coverage\n4. Documentation needs\n\nProvide specific feedback for each file.\n```\n\n### Testing Pattern\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*)\n---\n\nRun tests: !`npm test $1`\n\nAnalyze results and suggest fixes for failures.\n```\n\n### Documentation Pattern\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1 including:\n- Function/class descriptions\n- Parameter documentation\n- Return value descriptions\n- Usage examples\n- Edge cases and errors\n```\n\n### Workflow Pattern\n\n```markdown\n---\ndescription: Complete PR workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read\n---\n\nPR #$1 Workflow:\n\n1. Fetch PR: !`gh pr view $1`\n2. Review changes\n3. Run checks\n4. Approve or request changes\n```\n\n## Troubleshooting\n\n**Command not appearing:**\n- Check file is in correct directory\n- Verify `.md` extension present\n- Ensure valid Markdown format\n- Restart Claude Code\n\n**Arguments not working:**\n- Verify `$1`, `$2` syntax correct\n- Check `argument-hint` matches usage\n- Ensure no extra spaces\n\n**Bash execution failing:**\n- Check `allowed-tools` includes Bash\n- Verify command syntax in backticks\n- Test command in terminal first\n- Check for required permissions\n\n**File references not working:**\n- Verify `@` syntax correct\n- Check file path is valid\n- Ensure Read tool allowed\n- Use absolute or project-relative paths\n\n## Plugin-Specific Features\n\n### CLAUDE_PLUGIN_ROOT Variable\n\nPlugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path.\n\n**Purpose:**\n- Reference plugin files portably\n- Execute plugin scripts\n- Load plugin configuration\n- Access plugin templates\n\n**Basic usage:**\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*)\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\nReview results and report findings.\n```\n\n**Common patterns:**\n\n```markdown\n# Execute plugin script\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n\n# Load plugin configuration\n@${CLAUDE_PLUGIN_ROOT}/config/settings.json\n\n# Use plugin template\n@${CLAUDE_PLUGIN_ROOT}/templates/report.md\n\n# Access plugin resources\n@${CLAUDE_PLUGIN_ROOT}/docs/reference.md\n```\n\n**Why use it:**\n- Works across all installations\n- Portable between systems\n- No hardcoded paths needed\n- Essential for multi-file plugins\n\n### Plugin Command Organization\n\nPlugin commands discovered automatically from `commands/` directory:\n\n```\nplugin-name/\n├── commands/\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ ├── bar.md # /bar (plugin:plugin-name)\n│ └── utils/\n│ └── helper.md # /helper (plugin:plugin-name:utils)\n└── plugin.json\n```\n\n**Namespace benefits:**\n- Logical command grouping\n- Shown in `/help` output\n- Avoid name conflicts\n- Organize related commands\n\n**Naming conventions:**\n- Use descriptive action names\n- Avoid generic names (test, run)\n- Consider plugin-specific prefix\n- Use hyphens for multi-word names\n\n### Plugin Command Patterns\n\n**Configuration-based pattern:**\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nDeploy to $1 using configuration settings.\nMonitor deployment and report status.\n```\n\n**Template-based pattern:**\n\n```markdown\n---\ndescription: Generate docs from template\nargument-hint: [component]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md\n\nGenerate documentation for $1 following template structure.\n```\n\n**Multi-script pattern:**\n\n```markdown\n---\ndescription: Complete build workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\nPackage: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`\n\nReview outputs and report workflow status.\n```\n\n**See `references/plugin-features-reference.md` for detailed patterns.**\n\n## Integration with Plugin Components\n\nCommands can integrate with other plugin components for powerful workflows.\n\n### Agent Integration\n\nLaunch plugin agents for complex tasks:\n\n```markdown\n---\ndescription: Deep code review\nargument-hint: [file-path]\n---\n\nInitiate comprehensive review of @$1 using the code-reviewer agent.\n\nThe agent will analyze:\n- Code structure\n- Security issues\n- Performance\n- Best practices\n\nAgent uses plugin resources:\n- ${CLAUDE_PLUGIN_ROOT}/config/rules.json\n- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md\n```\n\n**Key points:**\n- Agent must exist in `plugin/agents/` directory\n- Claude uses Task tool to launch agent\n- Document agent capabilities\n- Reference plugin resources agent uses\n\n### Skill Integration\n\nLeverage plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: Document API with standards\nargument-hint: [api-file]\n---\n\nDocument API in @$1 following plugin standards.\n\nUse the api-docs-standards skill to ensure:\n- Complete endpoint documentation\n- Consistent formatting\n- Example quality\n- Error documentation\n\nGenerate production-ready API docs.\n```\n\n**Key points:**\n- Skill must exist in `plugin/skills/` directory\n- Mention skill name to trigger invocation\n- Document skill purpose\n- Explain what skill provides\n\n### Hook Coordination\n\nDesign commands that work with plugin hooks:\n- Commands can prepare state for hooks to process\n- Hooks execute automatically on tool events\n- Commands should document expected hook behavior\n- Guide Claude on interpreting hook output\n\nSee `references/plugin-features-reference.md` for examples of commands that coordinate with hooks\n\n### Multi-Component Workflows\n\nCombine agents, skills, and scripts:\n\n```markdown\n---\ndescription: Comprehensive review workflow\nargument-hint: [file]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget: @$1\n\nPhase 1 - Static Analysis:\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\nPhase 2 - Deep Review:\nLaunch code-reviewer agent for detailed analysis.\n\nPhase 3 - Standards Check:\nUse coding-standards skill for validation.\n\nPhase 4 - Report:\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review.md\n\nCompile findings into report following template.\n```\n\n**When to use:**\n- Complex multi-step workflows\n- Leverage multiple plugin capabilities\n- Require specialized analysis\n- Need structured outputs\n\n## Validation Patterns\n\nCommands should validate inputs and resources before processing.\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\nIf $1 is valid environment:\n Deploy to $1\nOtherwise:\n Explain valid environments: dev, staging, prod\n Show usage: /deploy [environment]\n```\n\n### File Existence Checks\n\n```markdown\n---\ndescription: Process configuration\nargument-hint: [config-file]\n---\n\nCheck file exists: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nIf file exists:\n Process configuration: @$1\nOtherwise:\n Explain where to place config file\n Show expected format\n Provide example configuration\n```\n\n### Plugin Resource Validation\n\n```markdown\n---\ndescription: Run plugin analyzer\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, run analysis.\nOtherwise, report missing components.\n```\n\n### Error Handling\n\n```markdown\n---\ndescription: Build with error handling\nallowed-tools: Bash(*)\n---\n\nExecute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo \"BUILD_FAILED\"`\n\nIf build succeeded:\n Report success and output location\nIf build failed:\n Analyze error output\n Suggest likely causes\n Provide troubleshooting steps\n```\n\n**Best practices:**\n- Validate early in command\n- Provide helpful error messages\n- Suggest corrective actions\n- Handle edge cases gracefully\n\n---\n\nFor detailed frontmatter field specifications, see `references/frontmatter-reference.md`.\nFor plugin-specific features and patterns, see `references/plugin-features-reference.md`.\nFor command pattern examples, see `examples/` directory.\n\n\n# Advanced Hook Use Cases\n\nThis reference covers advanced hook patterns and techniques for sophisticated automation workflows.\n\n## Multi-Stage Validation\n\nCombine command and prompt hooks for layered validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Use case:** Fast deterministic checks followed by intelligent analysis\n\n**Example quick-check.sh:**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Immediate approval for safe commands\nif [[ \"$command\" =~ ^(ls|pwd|echo|date|whoami)$ ]]; then\n exit 0\nfi\n\n# Let prompt hook handle complex cases\nexit 0\n```\n\nThe command hook quickly approves obviously safe commands, while the prompt hook analyzes everything else.\n\n## Conditional Hook Execution\n\nExecute hooks based on environment or context:\n\n```bash\n#!/bin/bash\n# Only run in CI environment\nif [ -z \"$CI\" ]; then\n echo '{\"continue\": true}' # Skip in non-CI\n exit 0\nfi\n\n# Run validation logic in CI\ninput=$(cat)\n# ... validation code ...\n```\n\n**Use cases:**\n- Different behavior in CI vs local development\n- Project-specific validation\n- User-specific rules\n\n**Example: Skip certain checks for trusted users:**\n```bash\n#!/bin/bash\n# Skip detailed checks for admin users\nif [ \"$USER\" = \"admin\" ]; then\n exit 0\nfi\n\n# Full validation for other users\ninput=$(cat)\n# ... validation code ...\n```\n\n## Hook Chaining via State\n\nShare state between hooks using temporary files:\n\n```bash\n# Hook 1: Analyze and save state\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Analyze command\nrisk_level=$(calculate_risk \"$command\")\necho \"$risk_level\" > /tmp/hook-state-$$\n\nexit 0\n```\n\n```bash\n# Hook 2: Use saved state\n#!/bin/bash\nrisk_level=$(cat /tmp/hook-state-$$ 2>/dev/null || echo \"unknown\")\n\nif [ \"$risk_level\" = \"high\" ]; then\n echo \"High risk operation detected\" >&2\n exit 2\nfi\n```\n\n**Important:** This only works for sequential hook events (e.g., PreToolUse then PostToolUse), not parallel hooks.\n\n## Dynamic Hook Configuration\n\nModify hook behavior based on project configuration:\n\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Read project-specific config\nif [ -f \".claude-hooks-config.json\" ]; then\n strict_mode=$(jq -r '.strict_mode' .claude-hooks-config.json)\n\n if [ \"$strict_mode\" = \"true\" ]; then\n # Apply strict validation\n # ...\n else\n # Apply lenient validation\n # ...\n fi\nfi\n```\n\n**Example .claude-hooks-config.json:**\n```json\n{\n \"strict_mode\": true,\n \"allowed_commands\": [\"ls\", \"pwd\", \"grep\"],\n \"forbidden_paths\": [\"/etc\", \"/sys\"]\n}\n```\n\n## Context-Aware Prompt Hooks\n\nUse transcript and session context for intelligent decisions:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review the full transcript at $TRANSCRIPT_PATH. Check: 1) Were tests run after code changes? 2) Did the build succeed? 3) Were all user questions answered? 4) Is there any unfinished work? Return 'approve' only if everything is complete.\"\n }\n ]\n }\n ]\n}\n```\n\nThe LLM can read the transcript file and make context-aware decisions.\n\n## Performance Optimization\n\n### Caching Validation Results\n\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncache_key=$(echo -n \"$file_path\" | md5sum | cut -d' ' -f1)\ncache_file=\"/tmp/hook-cache-$cache_key\"\n\n# Check cache\nif [ -f \"$cache_file\" ]; then\n cache_age=$(($(date +%s) - $(stat -f%m \"$cache_file\" 2>/dev/null || stat -c%Y \"$cache_file\")))\n if [ \"$cache_age\" -lt 300 ]; then # 5 minute cache\n cat \"$cache_file\"\n exit 0\n fi\nfi\n\n# Perform validation\nresult='{\"decision\": \"approve\"}'\n\n# Cache result\necho \"$result\" > \"$cache_file\"\necho \"$result\"\n```\n\n### Parallel Execution Optimization\n\nSince hooks run in parallel, design them to be independent:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash check-size.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"command\",\n \"command\": \"bash check-path.sh\", // Independent\n \"timeout\": 2\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check content safety\", // Independent\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nAll three hooks run simultaneously, reducing total latency.\n\n## Cross-Event Workflows\n\nCoordinate hooks across different events:\n\n**SessionStart - Set up tracking:**\n```bash\n#!/bin/bash\n# Initialize session tracking\necho \"0\" > /tmp/test-count-$$\necho \"0\" > /tmp/build-count-$$\n```\n\n**PostToolUse - Track events:**\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\nif [ \"$tool_name\" = \"Bash\" ]; then\n command=$(echo \"$input\" | jq -r '.tool_result')\n if [[ \"$command\" == *\"test\"* ]]; then\n count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n echo $((count + 1)) > /tmp/test-count-$$\n fi\nfi\n```\n\n**Stop - Verify based on tracking:**\n```bash\n#!/bin/bash\ntest_count=$(cat /tmp/test-count-$$ 2>/dev/null || echo \"0\")\n\nif [ \"$test_count\" -eq 0 ]; then\n echo '{\"decision\": \"block\", \"reason\": \"No tests were run\"}' >&2\n exit 2\nfi\n```\n\n## Integration with External Systems\n\n### Slack Notifications\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ndecision=\"blocked\"\n\n# Send notification to Slack\ncurl -X POST \"$SLACK_WEBHOOK\" \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"text\\\": \\\"Hook ${decision} ${tool_name} operation\\\"}\" \\\n 2>/dev/null\n\necho '{\"decision\": \"deny\"}' >&2\nexit 2\n```\n\n### Database Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\n\n# Log to database\npsql \"$DATABASE_URL\" -c \"INSERT INTO hook_logs (event, data) VALUES ('PreToolUse', '$input')\" \\\n 2>/dev/null\n\nexit 0\n```\n\n### Metrics Collection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Send metrics to monitoring system\necho \"hook.pretooluse.${tool_name}:1|c\" | nc -u -w1 statsd.local 8125\n\nexit 0\n```\n\n## Security Patterns\n\n### Rate Limiting\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Track command frequency\nrate_file=\"/tmp/hook-rate-$$\"\ncurrent_minute=$(date +%Y%m%d%H%M)\n\nif [ -f \"$rate_file\" ]; then\n last_minute=$(head -1 \"$rate_file\")\n count=$(tail -1 \"$rate_file\")\n\n if [ \"$current_minute\" = \"$last_minute\" ]; then\n if [ \"$count\" -gt 10 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Rate limit exceeded\"}' >&2\n exit 2\n fi\n count=$((count + 1))\n else\n count=1\n fi\nelse\n count=1\nfi\n\necho \"$current_minute\" > \"$rate_file\"\necho \"$count\" >> \"$rate_file\"\n\nexit 0\n```\n\n### Audit Logging\n\n```bash\n#!/bin/bash\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\ntimestamp=$(date -Iseconds)\n\n# Append to audit log\necho \"$timestamp | $USER | $tool_name | $input\" >> ~/.claude/audit.log\n\nexit 0\n```\n\n### Secret Detection\n\n```bash\n#!/bin/bash\ninput=$(cat)\ncontent=$(echo \"$input\" | jq -r '.tool_input.content')\n\n# Check for common secret patterns\nif echo \"$content\" | grep -qE \"(api[_-]?key|password|secret|token).{0,20}['\\\"]?[A-Za-z0-9]{20,}\"; then\n echo '{\"decision\": \"deny\", \"reason\": \"Potential secret detected in content\"}' >&2\n exit 2\nfi\n\nexit 0\n```\n\n## Testing Advanced Hooks\n\n### Unit Testing Hook Scripts\n\n```bash\n# test-hook.sh\n#!/bin/bash\n\n# Test 1: Approve safe command\nresult=$(echo '{\"tool_input\": {\"command\": \"ls\"}}' | bash validate-bash.sh)\nif [ $? -eq 0 ]; then\n echo \"✓ Test 1 passed\"\nelse\n echo \"✗ Test 1 failed\"\nfi\n\n# Test 2: Block dangerous command\nresult=$(echo '{\"tool_input\": {\"command\": \"rm -rf /\"}}' | bash validate-bash.sh)\nif [ $? -eq 2 ]; then\n echo \"✓ Test 2 passed\"\nelse\n echo \"✗ Test 2 failed\"\nfi\n```\n\n### Integration Testing\n\nCreate test scenarios that exercise the full hook workflow:\n\n```bash\n# integration-test.sh\n#!/bin/bash\n\n# Set up test environment\nexport CLAUDE_PROJECT_DIR=\"/tmp/test-project\"\nexport CLAUDE_PLUGIN_ROOT=\"$(pwd)\"\nmkdir -p \"$CLAUDE_PROJECT_DIR\"\n\n# Test SessionStart hook\necho '{}' | bash hooks/session-start.sh\nif [ -f \"/tmp/session-initialized\" ]; then\n echo \"✓ SessionStart hook works\"\nelse\n echo \"✗ SessionStart hook failed\"\nfi\n\n# Clean up\nrm -rf \"$CLAUDE_PROJECT_DIR\"\n```\n\n## Best Practices for Advanced Hooks\n\n1. **Keep hooks independent**: Don't rely on execution order\n2. **Use timeouts**: Set appropriate limits for each hook type\n3. **Handle errors gracefully**: Provide clear error messages\n4. **Document complexity**: Explain advanced patterns in README\n5. **Test thoroughly**: Cover edge cases and failure modes\n6. **Monitor performance**: Track hook execution time\n7. **Version configuration**: Use version control for hook configs\n8. **Provide escape hatches**: Allow users to bypass hooks when needed\n\n## Common Pitfalls\n\n### ❌ Assuming Hook Order\n\n```bash\n# BAD: Assumes hooks run in specific order\n# Hook 1 saves state, Hook 2 reads it\n# This can fail because hooks run in parallel!\n```\n\n### ❌ Long-Running Hooks\n\n```bash\n# BAD: Hook takes 2 minutes to run\nsleep 120\n# This will timeout and block the workflow\n```\n\n### ❌ Uncaught Exceptions\n\n```bash\n# BAD: Script crashes on unexpected input\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\ncat \"$file_path\" # Fails if file doesn't exist\n```\n\n### ✅ Proper Error Handling\n\n```bash\n# GOOD: Handles errors gracefully\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nif [ ! -f \"$file_path\" ]; then\n echo '{\"continue\": true, \"systemMessage\": \"File not found, skipping check\"}' >&2\n exit 0\nfi\n```\n\n## Conclusion\n\nAdvanced hook patterns enable sophisticated automation while maintaining reliability and performance. Use these techniques when basic hooks are insufficient, but always prioritize simplicity and maintainability.\n\n\n# Migrating from Basic to Advanced Hooks\n\nThis guide shows how to migrate from basic command hooks to advanced prompt-based hooks for better maintainability and flexibility.\n\n## Why Migrate?\n\nPrompt-based hooks offer several advantages:\n\n- **Natural language reasoning**: LLM understands context and intent\n- **Better edge case handling**: Adapts to unexpected scenarios\n- **No bash scripting required**: Simpler to write and maintain\n- **More flexible validation**: Can handle complex logic without coding\n\n## Migration Example: Bash Command Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-bash.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-bash.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Hard-coded validation logic\nif [[ \"$command\" == *\"rm -rf\"* ]]; then\n echo \"Dangerous command detected\" >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Only checks for exact \"rm -rf\" pattern\n- Doesn't catch variations like `rm -fr` or `rm -r -f`\n- Misses other dangerous commands (`dd`, `mkfs`, etc.)\n- No context awareness\n- Requires bash scripting knowledge\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. Analyze for: 1) Destructive operations (rm -rf, dd, mkfs, etc) 2) Privilege escalation (sudo) 3) Network operations without user consent. Return 'approve' or 'deny' with explanation.\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Catches all variations and patterns\n- Understands intent, not just literal strings\n- No script file needed\n- Easy to extend with new criteria\n- Context-aware decisions\n- Natural language explanation in denial\n\n## Migration Example: File Write Validation\n\n### Before (Basic Command Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash validate-write.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Script (validate-write.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Check for path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Check for system paths\nif [[ \"$file_path\" == \"/etc/\"* ]] || [[ \"$file_path\" == \"/sys/\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"System file\"}' >&2\n exit 2\nfi\n```\n\n**Problems:**\n- Hard-coded path patterns\n- Doesn't understand symlinks\n- Missing edge cases (e.g., `/etc` vs `/etc/`)\n- No consideration of file content\n\n### After (Advanced Prompt Hook)\n\n**Configuration:**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Content preview: $TOOL_INPUT.content (first 200 chars). Verify: 1) Not system directories (/etc, /sys, /usr) 2) Not credentials (.env, tokens, secrets) 3) No path traversal 4) Content doesn't expose secrets. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Benefits:**\n- Context-aware (considers content too)\n- Handles symlinks and edge cases\n- Natural understanding of \"system directories\"\n- Can detect secrets in content\n- Easy to extend criteria\n\n## When to Keep Command Hooks\n\nCommand hooks still have their place:\n\n### 1. Deterministic Performance Checks\n\n```bash\n#!/bin/bash\n# Check file size quickly\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nsize=$(stat -f%z \"$file_path\" 2>/dev/null || stat -c%s \"$file_path\" 2>/dev/null)\n\nif [ \"$size\" -gt 10000000 ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File too large\"}' >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Validation is purely mathematical or deterministic.\n\n### 2. External Tool Integration\n\n```bash\n#!/bin/bash\n# Run security scanner\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\nscan_result=$(security-scanner \"$file_path\")\n\nif [ \"$?\" -ne 0 ]; then\n echo \"Security scan failed: $scan_result\" >&2\n exit 2\nfi\n```\n\n**Use command hooks when:** Integrating with external tools that provide yes/no answers.\n\n### 3. Very Fast Checks (< 50ms)\n\n```bash\n#!/bin/bash\n# Quick regex check\ncommand=$(echo \"$input\" | jq -r '.tool_input.command')\n\nif [[ \"$command\" =~ ^(ls|pwd|echo)$ ]]; then\n exit 0 # Safe commands\nfi\n```\n\n**Use command hooks when:** Performance is critical and logic is simple.\n\n## Hybrid Approach\n\nCombine both for multi-stage validation:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh\",\n \"timeout\": 5\n },\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deep analysis of bash command: $TOOL_INPUT\",\n \"timeout\": 15\n }\n ]\n }\n ]\n}\n```\n\nThe command hook does fast deterministic checks, while the prompt hook handles complex reasoning.\n\n## Migration Checklist\n\nWhen migrating hooks:\n\n- [ ] Identify the validation logic in the command hook\n- [ ] Convert hard-coded patterns to natural language criteria\n- [ ] Test with edge cases the old hook missed\n- [ ] Verify LLM understands the intent\n- [ ] Set appropriate timeout (usually 15-30s for prompt hooks)\n- [ ] Document the new hook in README\n- [ ] Remove or archive old script files\n\n## Migration Tips\n\n1. **Start with one hook**: Don't migrate everything at once\n2. **Test thoroughly**: Verify prompt hook catches what command hook caught\n3. **Look for improvements**: Use migration as opportunity to enhance validation\n4. **Keep scripts for reference**: Archive old scripts in case you need to reference the logic\n5. **Document reasoning**: Explain why prompt hook is better in README\n\n## Complete Migration Example\n\n### Original Plugin Structure\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json\n└── scripts/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### After Migration\n\n```\nmy-plugin/\n├── .claude-plugin/plugin.json\n├── hooks/hooks.json # Now uses prompt hooks\n└── scripts/ # Archive or delete\n └── archive/\n ├── validate-bash.sh\n ├── validate-write.sh\n └── check-tests.sh\n```\n\n### Updated hooks.json\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety: destructive ops, privilege escalation, network access\"\n }\n ]\n },\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety: system paths, credentials, path traversal, content secrets\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests were run if code was modified\"\n }\n ]\n }\n ]\n}\n```\n\n**Result:** Simpler, more maintainable, more powerful.\n\n## Common Migration Patterns\n\n### Pattern: String Contains → Natural Language\n\n**Before:**\n```bash\nif [[ \"$command\" == *\"sudo\"* ]]; then\n echo \"Privilege escalation\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check for privilege escalation (sudo, su, etc)\"\n```\n\n### Pattern: Regex → Intent\n\n**Before:**\n```bash\nif [[ \"$file\" =~ \\.(env|secret|key|token)$ ]]; then\n echo \"Credential file\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Verify not writing to credential files (.env, secrets, keys, tokens)\"\n```\n\n### Pattern: Multiple Conditions → Criteria List\n\n**Before:**\n```bash\nif [ condition1 ] || [ condition2 ] || [ condition3 ]; then\n echo \"Invalid\" >&2\n exit 2\nfi\n```\n\n**After:**\n```\n\"Check: 1) condition1 2) condition2 3) condition3. Deny if any fail.\"\n```\n\n## Conclusion\n\nMigrating to prompt-based hooks makes plugins more maintainable, flexible, and powerful. Reserve command hooks for deterministic checks and external tool integration.\n\n\n# Common Hook Patterns\n\nThis reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases.\n\n## Pattern 1: Security Validation\n\nBlock dangerous file writes using prompt-based hooks:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Preventing writes to sensitive files or system directories.\n\n## Pattern 2: Test Enforcement\n\nEnsure tests run before stopping:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Enforcing quality standards and preventing incomplete work.\n\n## Pattern 3: Context Loading\n\nLoad project-specific context at session start:\n\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (load-context.sh):**\n```bash\n#!/bin/bash\ncd \"$CLAUDE_PROJECT_DIR\" || exit 1\n\n# Detect project type\nif [ -f \"package.json\" ]; then\n echo \"📦 Node.js project detected\"\n echo \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\nelif [ -f \"Cargo.toml\" ]; then\n echo \"🦀 Rust project detected\"\n echo \"export PROJECT_TYPE=rust\" >> \"$CLAUDE_ENV_FILE\"\nfi\n```\n\n**Use for:** Automatically detecting and configuring project-specific settings.\n\n## Pattern 4: Notification Logging\n\nLog all notifications for audit or analysis:\n\n```json\n{\n \"Notification\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Tracking user notifications or integration with external logging systems.\n\n## Pattern 5: MCP Tool Monitoring\n\nMonitor and validate MCP tool usage:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"mcp__.*__delete.*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Protecting against destructive MCP operations.\n\n## Pattern 6: Build Verification\n\nEnsure project builds after code changes:\n\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** Catching build errors before committing or stopping work.\n\n## Pattern 7: Permission Confirmation\n\nAsk user before dangerous operations:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Use for:** User confirmation on potentially destructive commands.\n\n## Pattern 8: Code Quality Checks\n\nRun linters or formatters on file edits:\n\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Example script (check-quality.sh):**\n```bash\n#!/bin/bash\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run linter if applicable\nif [[ \"$file_path\" == *.js ]] || [[ \"$file_path\" == *.ts ]]; then\n npx eslint \"$file_path\" 2>&1 || true\nfi\n```\n\n**Use for:** Automatic code quality enforcement.\n\n## Pattern Combinations\n\nCombine multiple patterns for comprehensive protection:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n },\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate bash command safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify tests run and build succeeded\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\nThis provides multi-layered protection and automation.\n\n## Pattern 9: Temporarily Active Hooks\n\nCreate hooks that only run when explicitly enabled via flag files:\n\n```bash\n#!/bin/bash\n# Hook only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-security-scan\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Quick exit when disabled\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Run security scan\nsecurity-scanner \"$file_path\"\n```\n\n**Activation:**\n```bash\n# Enable the hook\ntouch .enable-security-scan\n\n# Disable the hook\nrm .enable-security-scan\n```\n\n**Use for:**\n- Temporary debugging hooks\n- Feature flags for development\n- Project-specific validation that's opt-in\n- Performance-intensive checks only when needed\n\n**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes.\n\n## Pattern 10: Configuration-Driven Hooks\n\nUse JSON configuration to control hook behavior:\n\n```bash\n#!/bin/bash\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json\"\n\n# Read configuration\nif [ -f \"$CONFIG_FILE\" ]; then\n strict_mode=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n max_file_size=$(jq -r '.maxFileSize // 1000000' \"$CONFIG_FILE\")\nelse\n # Defaults\n strict_mode=false\n max_file_size=1000000\nfi\n\n# Skip if not in strict mode\nif [ \"$strict_mode\" != \"true\" ]; then\n exit 0\nfi\n\n# Apply configured limits\ninput=$(cat)\nfile_size=$(echo \"$input\" | jq -r '.tool_input.content | length')\n\nif [ \"$file_size\" -gt \"$max_file_size\" ]; then\n echo '{\"decision\": \"deny\", \"reason\": \"File exceeds configured size limit\"}' >&2\n exit 2\nfi\n```\n\n**Configuration file (.claude/my-plugin.local.json):**\n```json\n{\n \"strictMode\": true,\n \"maxFileSize\": 500000,\n \"allowedPaths\": [\"/tmp\", \"/home/user/projects\"]\n}\n```\n\n**Use for:**\n- User-configurable hook behavior\n- Per-project settings\n- Team-specific rules\n- Dynamic validation criteria\n\n\n---\nname: Hook Development\ndescription: This skill should be used when the user asks to \"create a hook\", \"add a PreToolUse/PostToolUse/Stop hook\", \"validate tool use\", \"implement prompt-based hooks\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"set up event-driven automation\", \"block dangerous commands\", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.\nversion: 0.1.0\n---\n\n# Hook Development for Claude Code Plugins\n\n## Overview\n\nHooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.\n\n**Key capabilities:**\n- Validate tool calls before execution (PreToolUse)\n- React to tool results (PostToolUse)\n- Enforce completion standards (Stop, SubagentStop)\n- Load project context (SessionStart)\n- Automate workflows across the development lifecycle\n\n## Hook Types\n\n### Prompt-Based Hooks (Recommended)\n\nUse LLM-driven decision making for context-aware validation:\n\n```json\n{\n \"type\": \"prompt\",\n \"prompt\": \"Evaluate if this tool use is appropriate: $TOOL_INPUT\",\n \"timeout\": 30\n}\n```\n\n**Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse\n\n**Benefits:**\n- Context-aware decisions based on natural language reasoning\n- Flexible evaluation logic without bash scripting\n- Better edge case handling\n- Easier to maintain and extend\n\n### Command Hooks\n\nExecute bash commands for deterministic checks:\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\",\n \"timeout\": 60\n}\n```\n\n**Use for:**\n- Fast deterministic validations\n- File system operations\n- External tool integrations\n- Performance-critical checks\n\n## Hook Configuration Formats\n\n### Plugin hooks.json Format\n\n**For plugin hooks** in `hooks/hooks.json`, use wrapper format:\n\n```json\n{\n \"description\": \"Brief explanation of hooks (optional)\",\n \"hooks\": {\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n }\n}\n```\n\n**Key points:**\n- `description` field is optional\n- `hooks` field is required wrapper containing actual hook events\n- This is the **plugin-specific format**\n\n**Example:**\n```json\n{\n \"description\": \"Validation hooks for code quality\",\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh\"\n }\n ]\n }\n ]\n }\n}\n```\n\n### Settings Format (Direct)\n\n**For user settings** in `.claude/settings.json`, use direct format:\n\n```json\n{\n \"PreToolUse\": [...],\n \"Stop\": [...],\n \"SessionStart\": [...]\n}\n```\n\n**Key points:**\n- No wrapper - events directly at top level\n- No description field\n- This is the **settings format**\n\n**Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{\"hooks\": {...}}`.\n\n## Hook Events\n\n### PreToolUse\n\nExecute before any tool runs. Use to approve, deny, or modify tool calls.\n\n**Example (prompt-based):**\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output for PreToolUse:**\n```json\n{\n \"hookSpecificOutput\": {\n \"permissionDecision\": \"allow|deny|ask\",\n \"updatedInput\": {\"field\": \"modified_value\"}\n },\n \"systemMessage\": \"Explanation for Claude\"\n}\n```\n\n### PostToolUse\n\nExecute after tool completes. Use to react to results, provide feedback, or log.\n\n**Example:**\n```json\n{\n \"PostToolUse\": [\n {\n \"matcher\": \"Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback.\"\n }\n ]\n }\n ]\n}\n```\n\n**Output behavior:**\n- Exit 0: stdout shown in transcript\n- Exit 2: stderr fed back to Claude\n- systemMessage included in context\n\n### Stop\n\nExecute when main agent considers stopping. Use to validate completeness.\n\n**Example:**\n```json\n{\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue.\"\n }\n ]\n }\n ]\n}\n```\n\n**Decision output:**\n```json\n{\n \"decision\": \"approve|block\",\n \"reason\": \"Explanation\",\n \"systemMessage\": \"Additional context\"\n}\n```\n\n### SubagentStop\n\nExecute when subagent considers stopping. Use to ensure subagent completed its task.\n\nSimilar to Stop hook, but for subagents.\n\n### UserPromptSubmit\n\nExecute when user submits a prompt. Use to add context, validate, or block prompts.\n\n**Example:**\n```json\n{\n \"UserPromptSubmit\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings.\"\n }\n ]\n }\n ]\n}\n```\n\n### SessionStart\n\nExecute when Claude Code session begins. Use to load context and set environment.\n\n**Example:**\n```json\n{\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\"\n }\n ]\n }\n ]\n}\n```\n\n**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`:\n```bash\necho \"export PROJECT_TYPE=nodejs\" >> \"$CLAUDE_ENV_FILE\"\n```\n\nSee `examples/load-context.sh` for complete example.\n\n### SessionEnd\n\nExecute when session ends. Use for cleanup, logging, and state preservation.\n\n### PreCompact\n\nExecute before context compaction. Use to add critical information to preserve.\n\n### Notification\n\nExecute when Claude sends notifications. Use to react to user notifications.\n\n## Hook Output Format\n\n### Standard Output (All Hooks)\n\n```json\n{\n \"continue\": true,\n \"suppressOutput\": false,\n \"systemMessage\": \"Message for Claude\"\n}\n```\n\n- `continue`: If false, halt processing (default true)\n- `suppressOutput`: Hide output from transcript (default false)\n- `systemMessage`: Message shown to Claude\n\n### Exit Codes\n\n- `0` - Success (stdout shown in transcript)\n- `2` - Blocking error (stderr fed back to Claude)\n- Other - Non-blocking error\n\n## Hook Input Format\n\nAll hooks receive JSON via stdin with common fields:\n\n```json\n{\n \"session_id\": \"abc123\",\n \"transcript_path\": \"/path/to/transcript.txt\",\n \"cwd\": \"/current/working/dir\",\n \"permission_mode\": \"ask|allow\",\n \"hook_event_name\": \"PreToolUse\"\n}\n```\n\n**Event-specific fields:**\n\n- **PreToolUse/PostToolUse:** `tool_name`, `tool_input`, `tool_result`\n- **UserPromptSubmit:** `user_prompt`\n- **Stop/SubagentStop:** `reason`\n\nAccess fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc.\n\n## Environment Variables\n\nAvailable in all command hooks:\n\n- `$CLAUDE_PROJECT_DIR` - Project root path\n- `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths)\n- `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here\n- `$CLAUDE_CODE_REMOTE` - Set if running in remote context\n\n**Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:**\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\"\n}\n```\n\n## Plugin Hook Configuration\n\nIn plugins, define hooks in `hooks/hooks.json`:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Validate file write safety\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"Verify task completion\"\n }\n ]\n }\n ],\n \"SessionStart\": [\n {\n \"matcher\": \"*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh\",\n \"timeout\": 10\n }\n ]\n }\n ]\n}\n```\n\nPlugin hooks merge with user's hooks and run in parallel.\n\n## Matchers\n\n### Tool Name Matching\n\n**Exact match:**\n```json\n\"matcher\": \"Write\"\n```\n\n**Multiple tools:**\n```json\n\"matcher\": \"Read|Write|Edit\"\n```\n\n**Wildcard (all tools):**\n```json\n\"matcher\": \"*\"\n```\n\n**Regex patterns:**\n```json\n\"matcher\": \"mcp__.*__delete.*\" // All MCP delete tools\n```\n\n**Note:** Matchers are case-sensitive.\n\n### Common Patterns\n\n```json\n// All MCP tools\n\"matcher\": \"mcp__.*\"\n\n// Specific plugin's MCP tools\n\"matcher\": \"mcp__plugin_asana_.*\"\n\n// All file operations\n\"matcher\": \"Read|Write|Edit\"\n\n// Bash commands only\n\"matcher\": \"Bash\"\n```\n\n## Security Best Practices\n\n### Input Validation\n\nAlways validate inputs in command hooks:\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\ninput=$(cat)\ntool_name=$(echo \"$input\" | jq -r '.tool_name')\n\n# Validate tool name format\nif [[ ! \"$tool_name\" =~ ^[a-zA-Z0-9_]+$ ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Invalid tool name\"}' >&2\n exit 2\nfi\n```\n\n### Path Safety\n\nCheck for path traversal and sensitive files:\n\n```bash\nfile_path=$(echo \"$input\" | jq -r '.tool_input.file_path')\n\n# Deny path traversal\nif [[ \"$file_path\" == *\"..\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Path traversal detected\"}' >&2\n exit 2\nfi\n\n# Deny sensitive files\nif [[ \"$file_path\" == *\".env\"* ]]; then\n echo '{\"decision\": \"deny\", \"reason\": \"Sensitive file\"}' >&2\n exit 2\nfi\n```\n\nSee `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples.\n\n### Quote All Variables\n\n```bash\n# GOOD: Quoted\necho \"$file_path\"\ncd \"$CLAUDE_PROJECT_DIR\"\n\n# BAD: Unquoted (injection risk)\necho $file_path\ncd $CLAUDE_PROJECT_DIR\n```\n\n### Set Appropriate Timeouts\n\n```json\n{\n \"type\": \"command\",\n \"command\": \"bash script.sh\",\n \"timeout\": 10\n}\n```\n\n**Defaults:** Command hooks (60s), Prompt hooks (30s)\n\n## Performance Considerations\n\n### Parallel Execution\n\nAll matching hooks run **in parallel**:\n\n```json\n{\n \"PreToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n {\"type\": \"command\", \"command\": \"check1.sh\"}, // Parallel\n {\"type\": \"command\", \"command\": \"check2.sh\"}, // Parallel\n {\"type\": \"prompt\", \"prompt\": \"Validate...\"} // Parallel\n ]\n }\n ]\n}\n```\n\n**Design implications:**\n- Hooks don't see each other's output\n- Non-deterministic ordering\n- Design for independence\n\n### Optimization\n\n1. Use command hooks for quick deterministic checks\n2. Use prompt hooks for complex reasoning\n3. Cache validation results in temp files\n4. Minimize I/O in hot paths\n\n## Temporarily Active Hooks\n\nCreate hooks that activate conditionally by checking for a flag file or configuration:\n\n**Pattern: Flag file activation**\n```bash\n#!/bin/bash\n# Only active when flag file exists\nFLAG_FILE=\"$CLAUDE_PROJECT_DIR/.enable-strict-validation\"\n\nif [ ! -f \"$FLAG_FILE\" ]; then\n # Flag not present, skip validation\n exit 0\nfi\n\n# Flag present, run validation\ninput=$(cat)\n# ... validation logic ...\n```\n\n**Pattern: Configuration-based activation**\n```bash\n#!/bin/bash\n# Check configuration for activation\nCONFIG_FILE=\"$CLAUDE_PROJECT_DIR/.claude/plugin-config.json\"\n\nif [ -f \"$CONFIG_FILE\" ]; then\n enabled=$(jq -r '.strictMode // false' \"$CONFIG_FILE\")\n if [ \"$enabled\" != \"true\" ]; then\n exit 0 # Not enabled, skip\n fi\nfi\n\n# Enabled, run hook logic\ninput=$(cat)\n# ... hook logic ...\n```\n\n**Use cases:**\n- Enable strict validation only when needed\n- Temporary debugging hooks\n- Project-specific hook behavior\n- Feature flags for hooks\n\n**Best practice:** Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.\n\n## Hook Lifecycle and Limitations\n\n### Hooks Load at Session Start\n\n**Important:** Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.\n\n**Cannot hot-swap hooks:**\n- Editing `hooks/hooks.json` won't affect current session\n- Adding new hook scripts won't be recognized\n- Changing hook commands/prompts won't update\n- Must restart Claude Code: exit and run `claude` again\n\n**To test hook changes:**\n1. Edit hook configuration or scripts\n2. Exit Claude Code session\n3. Restart: `claude` or `cc`\n4. New hook configuration loads\n5. Test hooks with `claude --debug`\n\n### Hook Validation at Startup\n\nHooks are validated when Claude Code starts:\n- Invalid JSON in hooks.json causes loading failure\n- Missing scripts cause warnings\n- Syntax errors reported in debug mode\n\nUse `/hooks` command to review loaded hooks in current session.\n\n## Debugging Hooks\n\n### Enable Debug Mode\n\n```bash\nclaude --debug\n```\n\nLook for hook registration, execution logs, input/output JSON, and timing information.\n\n### Test Hook Scripts\n\nTest command hooks directly:\n\n```bash\necho '{\"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"/test\"}}' | \\\n bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh\n\necho \"Exit code: $?\"\n```\n\n### Validate JSON Output\n\nEnsure hooks output valid JSON:\n\n```bash\noutput=$(./your-hook.sh < test-input.json)\necho \"$output\" | jq .\n```\n\n## Quick Reference\n\n### Hook Events Summary\n\n| Event | When | Use For |\n|-------|------|---------|\n| PreToolUse | Before tool | Validation, modification |\n| PostToolUse | After tool | Feedback, logging |\n| UserPromptSubmit | User input | Context, validation |\n| Stop | Agent stopping | Completeness check |\n| SubagentStop | Subagent done | Task validation |\n| SessionStart | Session begins | Context loading |\n| SessionEnd | Session ends | Cleanup, logging |\n| PreCompact | Before compact | Preserve context |\n| Notification | User notified | Logging, reactions |\n\n### Best Practices\n\n**DO:**\n- ✅ Use prompt-based hooks for complex logic\n- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability\n- ✅ Validate all inputs in command hooks\n- ✅ Quote all bash variables\n- ✅ Set appropriate timeouts\n- ✅ Return structured JSON output\n- ✅ Test hooks thoroughly\n\n**DON'T:**\n- ❌ Use hardcoded paths\n- ❌ Trust user input without validation\n- ❌ Create long-running hooks\n- ❌ Rely on hook execution order\n- ❌ Modify global state unpredictably\n- ❌ Log sensitive information\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed patterns and advanced techniques, consult:\n\n- **`references/patterns.md`** - Common hook patterns (8+ proven patterns)\n- **`references/migration.md`** - Migrating from basic to advanced hooks\n- **`references/advanced.md`** - Advanced use cases and techniques\n\n### Example Hook Scripts\n\nWorking examples in `examples/`:\n\n- **`validate-write.sh`** - File write validation example\n- **`validate-bash.sh`** - Bash command validation example\n- **`load-context.sh`** - SessionStart context loading example\n\n### Utility Scripts\n\nDevelopment tools in `scripts/`:\n\n- **`validate-hook-schema.sh`** - Validate hooks.json structure and syntax\n- **`test-hook.sh`** - Test hooks with sample input before deployment\n- **`hook-linter.sh`** - Check hook scripts for common issues and best practices\n\n### External Resources\n\n- **Official Docs**: https://docs.claude.com/en/docs/claude-code/hooks\n- **Examples**: See security-guidance plugin in marketplace\n- **Testing**: Use `claude --debug` for detailed logs\n- **Validation**: Use `jq` to validate hook JSON output\n\n## Implementation Workflow\n\nTo implement hooks in a plugin:\n\n1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.)\n2. Decide between prompt-based (flexible) or command (deterministic) hooks\n3. Write hook configuration in `hooks/hooks.json`\n4. For command hooks, create hook scripts\n5. Use ${CLAUDE_PLUGIN_ROOT} for all file references\n6. Validate configuration with `scripts/validate-hook-schema.sh hooks/hooks.json`\n7. Test hooks with `scripts/test-hook.sh` before deployment\n8. Test in Claude Code with `claude --debug`\n9. Document hooks in plugin README\n\nFocus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.\n\n\n{\n \"_comment\": \"Example HTTP MCP server configuration for REST APIs\",\n \"rest-api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"Content-Type\": \"application/json\",\n \"X-API-Version\": \"2024-01-01\"\n }\n },\n \"internal-service\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\",\n \"X-Service-Name\": \"claude-plugin\"\n }\n }\n}\n\n\n{\n \"_comment\": \"Example SSE MCP server configuration for hosted cloud services\",\n \"asana\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.asana.com/sse\"\n },\n \"github\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.github.com/sse\"\n },\n \"custom-service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-API-Version\": \"v1\",\n \"X-Client-ID\": \"${CLIENT_ID}\"\n }\n }\n}\n\n\n{\n \"_comment\": \"Example stdio MCP server configuration for local file system access\",\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"${CLAUDE_PROJECT_DIR}\"],\n \"env\": {\n \"LOG_LEVEL\": \"info\"\n }\n },\n \"database\": {\n \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server.js\",\n \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config/db.json\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_POOL_SIZE\": \"10\"\n }\n },\n \"custom-tools\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\", \"--port\", \"8080\"],\n \"env\": {\n \"API_KEY\": \"${CUSTOM_API_KEY}\",\n \"DEBUG\": \"false\"\n }\n }\n}\n\n\n# MCP Authentication Patterns\n\nComplete guide to authentication methods for MCP servers in Claude Code plugins.\n\n## Overview\n\nMCP servers support multiple authentication methods depending on the server type and service requirements. Choose the method that best matches your use case and security requirements.\n\n## OAuth (Automatic)\n\n### How It Works\n\nClaude Code automatically handles the complete OAuth 2.0 flow for SSE and HTTP servers:\n\n1. User attempts to use MCP tool\n2. Claude Code detects authentication needed\n3. Opens browser for OAuth consent\n4. User authorizes in browser\n5. Tokens stored securely by Claude Code\n6. Automatic token refresh\n\n### Configuration\n\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\"\n }\n}\n```\n\nNo additional auth configuration needed! Claude Code handles everything.\n\n### Supported Services\n\n**Known OAuth-enabled MCP servers:**\n- Asana: `https://mcp.asana.com/sse`\n- GitHub (when available)\n- Google services (when available)\n- Custom OAuth servers\n\n### OAuth Scopes\n\nOAuth scopes are determined by the MCP server. Users see required scopes during the consent flow.\n\n**Document required scopes in your README:**\n```markdown\n## Authentication\n\nThis plugin requires the following Asana permissions:\n- Read tasks and projects\n- Create and update tasks\n- Access workspace data\n```\n\n### Token Storage\n\nTokens are stored securely by Claude Code:\n- Not accessible to plugins\n- Encrypted at rest\n- Automatic refresh\n- Cleared on sign-out\n\n### Troubleshooting OAuth\n\n**Authentication loop:**\n- Clear cached tokens (sign out and sign in)\n- Check OAuth redirect URLs\n- Verify server OAuth configuration\n\n**Scope issues:**\n- User may need to re-authorize for new scopes\n- Check server documentation for required scopes\n\n**Token expiration:**\n- Claude Code auto-refreshes\n- If refresh fails, prompts re-authentication\n\n## Token-Based Authentication\n\n### Bearer Tokens\n\nMost common for HTTP and WebSocket servers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${API_TOKEN}\"\n }\n }\n}\n```\n\n**Environment variable:**\n```bash\nexport API_TOKEN=\"your-secret-token-here\"\n```\n\n### API Keys\n\nAlternative to Bearer tokens, often in custom headers.\n\n**Configuration:**\n```json\n{\n \"api\": {\n \"type\": \"http\",\n \"url\": \"https://api.example.com/mcp\",\n \"headers\": {\n \"X-API-Key\": \"${API_KEY}\",\n \"X-API-Secret\": \"${API_SECRET}\"\n }\n }\n}\n```\n\n### Custom Headers\n\nServices may use custom authentication headers.\n\n**Configuration:**\n```json\n{\n \"service\": {\n \"type\": \"sse\",\n \"url\": \"https://mcp.example.com/sse\",\n \"headers\": {\n \"X-Auth-Token\": \"${AUTH_TOKEN}\",\n \"X-User-ID\": \"${USER_ID}\",\n \"X-Tenant-ID\": \"${TENANT_ID}\"\n }\n }\n}\n```\n\n### Documenting Token Requirements\n\nAlways document in your README:\n\n```markdown\n## Setup\n\n### Required Environment Variables\n\nSet these environment variables before using the plugin:\n\n\\`\\`\\`bash\nexport API_TOKEN=\"your-token-here\"\nexport API_SECRET=\"your-secret-here\"\n\\`\\`\\`\n\n### Obtaining Tokens\n\n1. Visit https://api.example.com/tokens\n2. Create a new API token\n3. Copy the token and secret\n4. Set environment variables as shown above\n\n### Token Permissions\n\nThe API token needs the following permissions:\n- Read access to resources\n- Write access for creating items\n- Delete access (optional, for cleanup operations)\n\\`\\`\\`\n```\n\n## Environment Variable Authentication (stdio)\n\n### Passing Credentials to Server\n\nFor stdio servers, pass credentials via environment variables:\n\n```json\n{\n \"database\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server_db\"],\n \"env\": {\n \"DATABASE_URL\": \"${DATABASE_URL}\",\n \"DB_USER\": \"${DB_USER}\",\n \"DB_PASSWORD\": \"${DB_PASSWORD}\"\n }\n }\n}\n```\n\n### User Environment Variables\n\n```bash\n# User sets these in their shell\nexport DATABASE_URL=\"postgresql://localhost/mydb\"\nexport DB_USER=\"myuser\"\nexport DB_PASSWORD=\"mypassword\"\n```\n\n### Documentation Template\n\n```markdown\n## Database Configuration\n\nSet these environment variables:\n\n\\`\\`\\`bash\nexport DATABASE_URL=\"postgresql://host:port/database\"\nexport DB_USER=\"username\"\nexport DB_PASSWORD=\"password\"\n\\`\\`\\`\n\nOr create a `.env` file (add to `.gitignore`):\n\n\\`\\`\\`\nDATABASE_URL=postgresql://localhost:5432/mydb\nDB_USER=myuser\nDB_PASSWORD=mypassword\n\\`\\`\\`\n\nLoad with: \\`source .env\\` or \\`export $(cat .env | xargs)\\`\n\\`\\`\\`\n```\n\n## Dynamic Headers\n\n### Headers Helper Script\n\nFor tokens that change or expire, use a helper script:\n\n```json\n{\n \"api\": {\n \"type\": \"sse\",\n \"url\": \"https://api.example.com\",\n \"headersHelper\": \"${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh\"\n }\n}\n```\n\n**Script (get-headers.sh):**\n```bash\n#!/bin/bash\n# Generate dynamic authentication headers\n\n# Fetch fresh token\nTOKEN=$(get-fresh-token-from-somewhere)\n\n# Output JSON headers\ncat <\n"}