[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M70P0KRWFXT0BNB9MW4WDRCK":3,"skill-same:01M70P0KRWFXT0BNB9MW4WDRCK":85},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":34,"publishedAt":55,"linkOnly":56,"markdownContent":57,"markdownBody":58,"frontMatter":59,"refName":61,"commitSha":62,"skillDirectory":63,"forksCount":64,"repositoryHtmlUrl":65,"repositoryHomepageUrl":66,"ownerHtmlUrl":67,"ownerBlogUrl":68,"ownerDescription":69,"updatedAt":70,"install":71,"resources":84},"01M70P0KRWFXT0BNB9MW4WDRCK","writing-plugins",null,"How to design and build Claude Code plugins -- architecture decisions, component selection, file structure, manifest configuration, marketplace publishing. Use when planning, creating, or reviewing a Claude Code plugin.","shengdabai\u002FTony-Claude-Code-Skills","shengdabai","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F116417419?v=4","01M70F6D2WY5PQV5A92BKYJQEW","Tony Sheng","01M70F6D3GAAAYZ5H4CC1G8VXM",3,"MIT","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fxiaolai\u002Fnlpm\u002Fskills\u002Fnlpm\u002Fwriting-plugins\u002FSKILL.md",[18,23,26,31],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":32,"categoryName":33,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000036","内容创作者",[35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54],"writing","plugins","writing plugins","file","decisions","manifest","use","publishing","planning","claude code plugins","how","component","structure","marketplace publishing","architecture","code","when","design","how to","selection","2026-11-10 10:12:30",false,"---\nname: writing-plugins\ndescription: \"How to design and build Claude Code plugins -- architecture decisions, component selection, file structure, manifest configuration, marketplace publishing. Use when planning, creating, or reviewing a Claude Code plugin.\"\nversion: 0.1.0\n---\n\n# Writing Plugins\n\n> Scope: covers plugin design and architecture. For individual component authoring, see [[writing-skills]], [[writing-agents]], [[writing-hooks]], [[writing-rules]].\n\n## 1. Plugin = Commands + Agents + Skills + Hooks\n\nA plugin is a collection of NL artifacts that work together. Before writing anything, decide which components you need.\n\n### Component Selection Guide\n\n| User need | Component | Example |\n|-----------|-----------|---------|\n| User runs a slash command | Command | `\u002Fnlpm:score path\u002Fto\u002Ffile.md` |\n| AI works autonomously on a task | Agent | Security scanner dispatched by a command |\n| Domain knowledge for agents\u002FClaude | Skill | SKILL.md with patterns and decision tables |\n| Something must happen automatically on events | Hook | Lint-on-save, block force push |\n| External service integration | MCP server (`.mcp.json`) | GitHub API, Slack notifications |\n\n### Minimum Viable Plugin\n\nThe smallest useful plugin has **one component**:\n\n```\nmy-plugin\u002F\n  .claude-plugin\u002F\n    plugin.json\n  commands\u002F\n    do-thing.md\n```\n\nDon't add agents, skills, or hooks until you need them. Each component adds maintenance burden.\n\n## 2. Architecture Patterns\n\n### Pattern: Single Command (simplest)\n\nCommand does everything itself. No agents, no orchestration.\n\n```\nCommand receives input --> processes --> outputs result\n```\n\n**Use when**: task is simple, deterministic, single-step.\n**Example**: `loc-guardian \u002Fscan` -- counts lines, checks limits, reports.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Fdo-thing.md\n```\n\n### Pattern: Command + Agent\n\nCommand parses input and dispatches one agent for heavy work.\n\n```\nCommand parses input --> dispatches agent --> formats output\n```\n\n**Use when**: task requires AI judgment but has a clear entry point.\n**Example**: `\u002Fnlpm:score` dispatches a scorer agent.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Fanalyze.md\n  agents\u002Fanalyzer.md\n```\n\n### Pattern: Command + Multiple Agents (parallel)\n\nCommand dispatches several agents simultaneously, synthesizes results.\n\n```\nCommand --> agent-1 (security)\n        --> agent-2 (performance)    --> synthesize --> output\n        --> agent-3 (architecture)\n```\n\n**Use when**: multiple independent analyses of the same input.\n**Example**: grill dispatches 6 review agents in parallel.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Freview.md\n  agents\u002F\n    security-agent.md\n    performance-agent.md\n    architecture-agent.md\n```\n\n### Pattern: Command + Agent Pipeline (sequential)\n\nEach agent feeds into the next. Stages have different model requirements.\n\n```\nCommand --> parse (haiku) --> analyze (sonnet) --> QC (sonnet) --> output\n```\n\n**Use when**: multi-phase processing where each phase depends on the previous.\n**Example**: reading-assistant's 4-phase pipeline.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Fprocess.md\n  agents\u002F\n    parser.md       # haiku\n    analyzer.md     # sonnet\n    qc-agent.md     # sonnet\n```\n\n### Pattern: Hooks Only (no commands)\n\nPlugin enforces policy silently via hooks. No user-facing commands.\n\n```\nEvent fires --> hook checks --> allow\u002Fdeny\u002Fadvise\n```\n\n**Use when**: enforcement should be automatic, not user-initiated.\n**Example**: tdd-guardian's pre-commit quality gate.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  hooks\u002Fhooks.json\n  scripts\u002Fcheck.sh\n```\n\n### Pattern Selection Matrix\n\n| Question | Yes --> | No --> |\n|----------|---------|--------|\n| Does the user explicitly trigger it? | Needs a command | Hooks only |\n| Does it require AI judgment? | Needs agents | Command-only or hooks |\n| Are there independent sub-analyses? | Parallel agents | Sequential or single agent |\n| Does each step depend on the previous? | Sequential pipeline | Parallel or single |\n| Should it run automatically on events? | Add hooks | Commands only |\n| Does Claude need domain knowledge? | Add skills | No skills needed |\n\n## 3. The plugin.json Manifest\n\n### Required Fields\n\nOnly `name` is strictly required:\n\n```json\n{\n  \"name\": \"my-plugin\"\n}\n```\n\n### Recommended Fields\n\nShip with these for discoverability and marketplace listing:\n\n```json\n{\n  \"name\": \"my-plugin\",\n  \"version\": \"0.1.0\",\n  \"description\": \"What this plugin does in one sentence\",\n  \"author\": { \"name\": \"your-name\" },\n  \"license\": \"MIT\",\n  \"keywords\": [\"relevant\", \"search\", \"terms\"],\n  \"category\": \"developer-tools\"\n}\n```\n\n### Field Reference\n\n| Field | Purpose | Example |\n|-------|---------|---------|\n| `name` | Unique identifier, used in slash commands | `\"nlpm\"` |\n| `version` | Semver, used by marketplace and update checks | `\"0.1.0\"` |\n| `description` | One-line summary for marketplace listing | `\"NL programming quality tools\"` |\n| `author.name` | Creator attribution | `\"xiaolai\"` |\n| `license` | Open source license | `\"MIT\"` |\n| `keywords` | Search terms for marketplace discovery | `[\"linter\", \"quality\"]` |\n| `category` | Marketplace category | `\"developer-tools\"` |\n\n## 4. File Structure\n\n### Full Plugin Layout\n\n```\nmy-plugin\u002F\n  .claude-plugin\u002F\n    plugin.json              # manifest (required)\n    marketplace.json         # for marketplace publishing\n  commands\u002F                  # auto-discovered by Claude Code\n    do-thing.md              # user-invocable: \u002Fplugin:do-thing\n    advanced-thing.md\n    shared\u002F                  # non-invocable partials\n      common-logic.md        # user-invocable: false\n      format-output.md\n  agents\u002F                    # auto-discovered\n    worker.md\n    reviewer.md\n  skills\u002F                    # auto-discovered\n    my-plugin\u002F\n      domain-knowledge\u002F\n        SKILL.md\n      advanced-topic\u002F\n        SKILL.md\n        references\u002F\n          deep-dive.md\n  hooks\u002F\n    hooks.json               # hook definitions\n  scripts\u002F                   # hook scripts, utilities\n    check.sh\n    validate.sh\n  CLAUDE.md                  # architecture guide (for Claude)\n  README.md                  # user documentation (for humans)\n  LICENSE\n```\n\n### Directory Conventions\n\n| Directory | Auto-discovered? | What goes here |\n|-----------|-----------------|----------------|\n| `.claude-plugin\u002F` | Yes (manifest) | Plugin metadata |\n| `commands\u002F` | Yes | Slash command definitions |\n| `commands\u002Fshared\u002F` | Yes (but not invocable) | Shared command logic |\n| `agents\u002F` | Yes | Agent definitions |\n| `skills\u002F` | Yes | Domain knowledge |\n| `hooks\u002F` | Yes (`hooks.json`) | Event hooks |\n| `scripts\u002F` | No | Shell scripts, utilities |\n\n### Naming Conventions\n\n| Component | File naming | Example |\n|-----------|------------|---------|\n| Commands | kebab-case, descriptive verb | `scan-files.md`, `generate-report.md` |\n| Agents | kebab-case, role-noun | `security-reviewer.md`, `parser.md` |\n| Skills | kebab-case directory, always `SKILL.md` | `skills\u002Fmy-plugin\u002Freact-patterns\u002FSKILL.md` |\n| Hook scripts | kebab-case, descriptive | `check-loc.sh`, `validate-config.sh` |\n\n## 5. Versioning\n\n### Semver Rules\n\n| Change type | Bump | Example |\n|------------|------|---------|\n| Bug fixes, typo corrections, penalty adjustments | Patch: 0.1.0 -> 0.1.1 | Fix scoring formula |\n| New commands, new agents, new features | Minor: 0.1.0 -> 0.2.0 | Add `\u002Fplugin:export` command |\n| Breaking changes (renamed commands, removed features) | Major: 0.1.0 -> 1.0.0 | Rename `\u002Fscan` to `\u002Fanalyze` |\n\n### Four-Place Update\n\nWhen bumping version, update in **four** places:\n\n| Location | File | Field |\n|----------|------|-------|\n| 1. Plugin manifest | `.claude-plugin\u002Fplugin.json` | `version` |\n| 2. Plugin marketplace | `.claude-plugin\u002Fmarketplace.json` | `version` in the plugin's entry |\n| 3. Central marketplace manifest | `~\u002F.claude\u002Fplugins\u002Fmarketplaces\u002Fxiaolai\u002F.claude-plugin\u002Fmarketplace.json` | `version` |\n| 4. Central marketplace README | `~\u002F.claude\u002Fplugins\u002Fmarketplaces\u002Fxiaolai\u002FREADME.md` | Version in the table |\n\n**Order**: push plugin repo first, then update central marketplace. The marketplace points to the repo -- if the repo isn't updated yet, users pull stale code.\n\n## 6. CLAUDE.md for Plugins\n\nYour plugin's CLAUDE.md is for **Claude** (the AI), not the user. It tells Claude how the plugin's components relate to each other.\n\n### What to Include\n\n```markdown\n# my-plugin\n\n## Architecture\nBrief description of what the plugin does and how components interact.\n\n## Components\n\n### Commands\n| Command | Purpose |\n|---------|---------|\n| \u002Fplugin:scan | Discovers and inventories files |\n| \u002Fplugin:fix | Auto-fixes issues found by scan |\n\n### Agents\n| Agent | Model | Role |\n|-------|-------|------|\n| scanner | haiku | Mechanical file discovery |\n| fixer | sonnet | AI-powered fix generation |\n\n### Conventions\n- All agents output findings in severity-tagged format\n- Scanner runs before fixer (sequential dependency)\n- Hook scripts use fail-open pattern\n```\n\n### What NOT to Include\n\n- Installation instructions (those go in README.md)\n- User-facing documentation (README.md)\n- Changelog (CHANGELOG.md or git history)\n- Contributing guidelines (CONTRIBUTING.md)\n\n## 7. Shared Partials\n\nExtract repeated logic into `commands\u002Fshared\u002F*.md` with `user-invocable: false`.\n\n### Partial Frontmatter\n\n```yaml\n---\nuser-invocable: false\ndescription: \"Shared config loading logic\"\n---\n```\n\n### Good Candidates for Extraction\n\n| Partial | Content | When to extract |\n|---------|---------|----------------|\n| `shared\u002Fload-config.md` | Read and validate config file | 3+ commands need config |\n| `shared\u002Fdiscover-files.md` | Find target files by pattern | 3+ commands scan files |\n| `shared\u002Fvalidate-prereqs.md` | Check tool availability | 2+ commands need same tools |\n| `shared\u002Fformat-report.md` | Report header, footer, severity format | 3+ commands output reports |\n\n### When NOT to Extract\n\n- Logic used by only 1 command (premature abstraction)\n- Simple logic under 10 lines (duplication is fine)\n- Logic that differs slightly between commands (forced generalization adds complexity)\n\n## 8. Testing Your Plugin\n\n### Pre-Publish Checklist\n\n| Check | How | Pass criteria |\n|-------|-----|---------------|\n| Structure validation | `claude plugin validate \u002Fpath\u002Fto\u002Fplugin` | No errors |\n| Command: no args | Run each command with no arguments | Helpful error or usage message |\n| Command: normal args | Run each command with typical input | Correct output |\n| Command: edge cases | Empty files, huge files, missing files | Graceful error handling |\n| Agent triggering | Try queries that should and shouldn't trigger | Correct dispatch decisions |\n| Hook scripts | `chmod +x` check, run with test JSON | Valid JSON output |\n| Hook fail-open | Kill script mid-execution | Action is allowed |\n\n### Testing Agent Triggers\n\nFor each agent, test with 3 types of queries:\n\n| Query type | Expected | Example |\n|-----------|----------|---------|\n| Direct match | Agent triggers | \"Scan this code for security issues\" |\n| Adjacent topic | Agent may or may not trigger | \"Is this code okay?\" |\n| Unrelated | Agent does NOT trigger | \"What's the weather?\" |\n\n## 9. Marketplace Publishing\n\n1. Push your plugin repo to GitHub\n2. Add entry to central `marketplace.json` (name, source, description, version, author, license, keywords, category)\n3. Add row to central marketplace `README.md` version table\n4. Commit and push the central marketplace repo\n5. Verify: `claude plugin install my-plugin@xiaolai --scope project`\n\n**Pre-publish checks**: `claude plugin validate .`, verify no hardcoded paths (`grep -r '\u002FUsers\u002F' commands\u002F agents\u002F hooks\u002F`), verify all scripts executable, verify version matches in all 4 locations.\n\n## 10. Common Mistakes\n\n| Mistake | Impact | Fix |\n|---------|--------|-----|\n| Commands that do too much | Hard to maintain, unreliable | Split into focused commands |\n| Agents without examples | 40% trigger accuracy | Add 2-3 specific scenario examples |\n| Skills over 500 lines | Context bloat, slow loading | Extract to references\u002F subdirectory |\n| Hooks that block without explanation | Frustrating UX | Always include `permissionDecisionReason` |\n| No CLAUDE.md | Claude doesn't understand plugin architecture | Add architecture overview |\n| README documents internals | Users confused by implementation details | README = user guide, CLAUDE.md = internals |\n| Hardcoded paths | Breaks on other machines | Use `${CLAUDE_PLUGIN_ROOT}` everywhere |\n| No error handling in commands | Silent failures | Add explicit error cases |\n| Version not updated in all 4 places | Marketplace shows wrong version | Use the four-place update checklist |\n| Premature extraction into shared\u002F | Over-abstracted, harder to understand | Extract only when 3+ consumers exist |\n","# Writing Plugins\n\n> Scope: covers plugin design and architecture. For individual component authoring, see [[writing-skills]], [[writing-agents]], [[writing-hooks]], [[writing-rules]].\n\n## 1. Plugin = Commands + Agents + Skills + Hooks\n\nA plugin is a collection of NL artifacts that work together. Before writing anything, decide which components you need.\n\n### Component Selection Guide\n\n| User need | Component | Example |\n|-----------|-----------|---------|\n| User runs a slash command | Command | `\u002Fnlpm:score path\u002Fto\u002Ffile.md` |\n| AI works autonomously on a task | Agent | Security scanner dispatched by a command |\n| Domain knowledge for agents\u002FClaude | Skill | SKILL.md with patterns and decision tables |\n| Something must happen automatically on events | Hook | Lint-on-save, block force push |\n| External service integration | MCP server (`.mcp.json`) | GitHub API, Slack notifications |\n\n### Minimum Viable Plugin\n\nThe smallest useful plugin has **one component**:\n\n```\nmy-plugin\u002F\n  .claude-plugin\u002F\n    plugin.json\n  commands\u002F\n    do-thing.md\n```\n\nDon't add agents, skills, or hooks until you need them. Each component adds maintenance burden.\n\n## 2. Architecture Patterns\n\n### Pattern: Single Command (simplest)\n\nCommand does everything itself. No agents, no orchestration.\n\n```\nCommand receives input --> processes --> outputs result\n```\n\n**Use when**: task is simple, deterministic, single-step.\n**Example**: `loc-guardian \u002Fscan` -- counts lines, checks limits, reports.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Fdo-thing.md\n```\n\n### Pattern: Command + Agent\n\nCommand parses input and dispatches one agent for heavy work.\n\n```\nCommand parses input --> dispatches agent --> formats output\n```\n\n**Use when**: task requires AI judgment but has a clear entry point.\n**Example**: `\u002Fnlpm:score` dispatches a scorer agent.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Fanalyze.md\n  agents\u002Fanalyzer.md\n```\n\n### Pattern: Command + Multiple Agents (parallel)\n\nCommand dispatches several agents simultaneously, synthesizes results.\n\n```\nCommand --> agent-1 (security)\n        --> agent-2 (performance)    --> synthesize --> output\n        --> agent-3 (architecture)\n```\n\n**Use when**: multiple independent analyses of the same input.\n**Example**: grill dispatches 6 review agents in parallel.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Freview.md\n  agents\u002F\n    security-agent.md\n    performance-agent.md\n    architecture-agent.md\n```\n\n### Pattern: Command + Agent Pipeline (sequential)\n\nEach agent feeds into the next. Stages have different model requirements.\n\n```\nCommand --> parse (haiku) --> analyze (sonnet) --> QC (sonnet) --> output\n```\n\n**Use when**: multi-phase processing where each phase depends on the previous.\n**Example**: reading-assistant's 4-phase pipeline.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  commands\u002Fprocess.md\n  agents\u002F\n    parser.md       # haiku\n    analyzer.md     # sonnet\n    qc-agent.md     # sonnet\n```\n\n### Pattern: Hooks Only (no commands)\n\nPlugin enforces policy silently via hooks. No user-facing commands.\n\n```\nEvent fires --> hook checks --> allow\u002Fdeny\u002Fadvise\n```\n\n**Use when**: enforcement should be automatic, not user-initiated.\n**Example**: tdd-guardian's pre-commit quality gate.\n\n**File structure**:\n```\nmy-plugin\u002F\n  .claude-plugin\u002Fplugin.json\n  hooks\u002Fhooks.json\n  scripts\u002Fcheck.sh\n```\n\n### Pattern Selection Matrix\n\n| Question | Yes --> | No --> |\n|----------|---------|--------|\n| Does the user explicitly trigger it? | Needs a command | Hooks only |\n| Does it require AI judgment? | Needs agents | Command-only or hooks |\n| Are there independent sub-analyses? | Parallel agents | Sequential or single agent |\n| Does each step depend on the previous? | Sequential pipeline | Parallel or single |\n| Should it run automatically on events? | Add hooks | Commands only |\n| Does Claude need domain knowledge? | Add skills | No skills needed |\n\n## 3. The plugin.json Manifest\n\n### Required Fields\n\nOnly `name` is strictly required:\n\n```json\n{\n  \"name\": \"my-plugin\"\n}\n```\n\n### Recommended Fields\n\nShip with these for discoverability and marketplace listing:\n\n```json\n{\n  \"name\": \"my-plugin\",\n  \"version\": \"0.1.0\",\n  \"description\": \"What this plugin does in one sentence\",\n  \"author\": { \"name\": \"your-name\" },\n  \"license\": \"MIT\",\n  \"keywords\": [\"relevant\", \"search\", \"terms\"],\n  \"category\": \"developer-tools\"\n}\n```\n\n### Field Reference\n\n| Field | Purpose | Example |\n|-------|---------|---------|\n| `name` | Unique identifier, used in slash commands | `\"nlpm\"` |\n| `version` | Semver, used by marketplace and update checks | `\"0.1.0\"` |\n| `description` | One-line summary for marketplace listing | `\"NL programming quality tools\"` |\n| `author.name` | Creator attribution | `\"xiaolai\"` |\n| `license` | Open source license | `\"MIT\"` |\n| `keywords` | Search terms for marketplace discovery | `[\"linter\", \"quality\"]` |\n| `category` | Marketplace category | `\"developer-tools\"` |\n\n## 4. File Structure\n\n### Full Plugin Layout\n\n```\nmy-plugin\u002F\n  .claude-plugin\u002F\n    plugin.json              # manifest (required)\n    marketplace.json         # for marketplace publishing\n  commands\u002F                  # auto-discovered by Claude Code\n    do-thing.md              # user-invocable: \u002Fplugin:do-thing\n    advanced-thing.md\n    shared\u002F                  # non-invocable partials\n      common-logic.md        # user-invocable: false\n      format-output.md\n  agents\u002F                    # auto-discovered\n    worker.md\n    reviewer.md\n  skills\u002F                    # auto-discovered\n    my-plugin\u002F\n      domain-knowledge\u002F\n        SKILL.md\n      advanced-topic\u002F\n        SKILL.md\n        references\u002F\n          deep-dive.md\n  hooks\u002F\n    hooks.json               # hook definitions\n  scripts\u002F                   # hook scripts, utilities\n    check.sh\n    validate.sh\n  CLAUDE.md                  # architecture guide (for Claude)\n  README.md                  # user documentation (for humans)\n  LICENSE\n```\n\n### Directory Conventions\n\n| Directory | Auto-discovered? | What goes here |\n|-----------|-----------------|----------------|\n| `.claude-plugin\u002F` | Yes (manifest) | Plugin metadata |\n| `commands\u002F` | Yes | Slash command definitions |\n| `commands\u002Fshared\u002F` | Yes (but not invocable) | Shared command logic |\n| `agents\u002F` | Yes | Agent definitions |\n| `skills\u002F` | Yes | Domain knowledge |\n| `hooks\u002F` | Yes (`hooks.json`) | Event hooks |\n| `scripts\u002F` | No | Shell scripts, utilities |\n\n### Naming Conventions\n\n| Component | File naming | Example |\n|-----------|------------|---------|\n| Commands | kebab-case, descriptive verb | `scan-files.md`, `generate-report.md` |\n| Agents | kebab-case, role-noun | `security-reviewer.md`, `parser.md` |\n| Skills | kebab-case directory, always `SKILL.md` | `skills\u002Fmy-plugin\u002Freact-patterns\u002FSKILL.md` |\n| Hook scripts | kebab-case, descriptive | `check-loc.sh`, `validate-config.sh` |\n\n## 5. Versioning\n\n### Semver Rules\n\n| Change type | Bump | Example |\n|------------|------|---------|\n| Bug fixes, typo corrections, penalty adjustments | Patch: 0.1.0 -> 0.1.1 | Fix scoring formula |\n| New commands, new agents, new features | Minor: 0.1.0 -> 0.2.0 | Add `\u002Fplugin:export` command |\n| Breaking changes (renamed commands, removed features) | Major: 0.1.0 -> 1.0.0 | Rename `\u002Fscan` to `\u002Fanalyze` |\n\n### Four-Place Update\n\nWhen bumping version, update in **four** places:\n\n| Location | File | Field |\n|----------|------|-------|\n| 1. Plugin manifest | `.claude-plugin\u002Fplugin.json` | `version` |\n| 2. Plugin marketplace | `.claude-plugin\u002Fmarketplace.json` | `version` in the plugin's entry |\n| 3. Central marketplace manifest | `~\u002F.claude\u002Fplugins\u002Fmarketplaces\u002Fxiaolai\u002F.claude-plugin\u002Fmarketplace.json` | `version` |\n| 4. Central marketplace README | `~\u002F.claude\u002Fplugins\u002Fmarketplaces\u002Fxiaolai\u002FREADME.md` | Version in the table |\n\n**Order**: push plugin repo first, then update central marketplace. The marketplace points to the repo -- if the repo isn't updated yet, users pull stale code.\n\n## 6. CLAUDE.md for Plugins\n\nYour plugin's CLAUDE.md is for **Claude** (the AI), not the user. It tells Claude how the plugin's components relate to each other.\n\n### What to Include\n\n```markdown\n# my-plugin\n\n## Architecture\nBrief description of what the plugin does and how components interact.\n\n## Components\n\n### Commands\n| Command | Purpose |\n|---------|---------|\n| \u002Fplugin:scan | Discovers and inventories files |\n| \u002Fplugin:fix | Auto-fixes issues found by scan |\n\n### Agents\n| Agent | Model | Role |\n|-------|-------|------|\n| scanner | haiku | Mechanical file discovery |\n| fixer | sonnet | AI-powered fix generation |\n\n### Conventions\n- All agents output findings in severity-tagged format\n- Scanner runs before fixer (sequential dependency)\n- Hook scripts use fail-open pattern\n```\n\n### What NOT to Include\n\n- Installation instructions (those go in README.md)\n- User-facing documentation (README.md)\n- Changelog (CHANGELOG.md or git history)\n- Contributing guidelines (CONTRIBUTING.md)\n\n## 7. Shared Partials\n\nExtract repeated logic into `commands\u002Fshared\u002F*.md` with `user-invocable: false`.\n\n### Partial Frontmatter\n\n```yaml\n---\nuser-invocable: false\ndescription: \"Shared config loading logic\"\n---\n```\n\n### Good Candidates for Extraction\n\n| Partial | Content | When to extract |\n|---------|---------|----------------|\n| `shared\u002Fload-config.md` | Read and validate config file | 3+ commands need config |\n| `shared\u002Fdiscover-files.md` | Find target files by pattern | 3+ commands scan files |\n| `shared\u002Fvalidate-prereqs.md` | Check tool availability | 2+ commands need same tools |\n| `shared\u002Fformat-report.md` | Report header, footer, severity format | 3+ commands output reports |\n\n### When NOT to Extract\n\n- Logic used by only 1 command (premature abstraction)\n- Simple logic under 10 lines (duplication is fine)\n- Logic that differs slightly between commands (forced generalization adds complexity)\n\n## 8. Testing Your Plugin\n\n### Pre-Publish Checklist\n\n| Check | How | Pass criteria |\n|-------|-----|---------------|\n| Structure validation | `claude plugin validate \u002Fpath\u002Fto\u002Fplugin` | No errors |\n| Command: no args | Run each command with no arguments | Helpful error or usage message |\n| Command: normal args | Run each command with typical input | Correct output |\n| Command: edge cases | Empty files, huge files, missing files | Graceful error handling |\n| Agent triggering | Try queries that should and shouldn't trigger | Correct dispatch decisions |\n| Hook scripts | `chmod +x` check, run with test JSON | Valid JSON output |\n| Hook fail-open | Kill script mid-execution | Action is allowed |\n\n### Testing Agent Triggers\n\nFor each agent, test with 3 types of queries:\n\n| Query type | Expected | Example |\n|-----------|----------|---------|\n| Direct match | Agent triggers | \"Scan this code for security issues\" |\n| Adjacent topic | Agent may or may not trigger | \"Is this code okay?\" |\n| Unrelated | Agent does NOT trigger | \"What's the weather?\" |\n\n## 9. Marketplace Publishing\n\n1. Push your plugin repo to GitHub\n2. Add entry to central `marketplace.json` (name, source, description, version, author, license, keywords, category)\n3. Add row to central marketplace `README.md` version table\n4. Commit and push the central marketplace repo\n5. Verify: `claude plugin install my-plugin@xiaolai --scope project`\n\n**Pre-publish checks**: `claude plugin validate .`, verify no hardcoded paths (`grep -r '\u002FUsers\u002F' commands\u002F agents\u002F hooks\u002F`), verify all scripts executable, verify version matches in all 4 locations.\n\n## 10. Common Mistakes\n\n| Mistake | Impact | Fix |\n|---------|--------|-----|\n| Commands that do too much | Hard to maintain, unreliable | Split into focused commands |\n| Agents without examples | 40% trigger accuracy | Add 2-3 specific scenario examples |\n| Skills over 500 lines | Context bloat, slow loading | Extract to references\u002F subdirectory |\n| Hooks that block without explanation | Frustrating UX | Always include `permissionDecisionReason` |\n| No CLAUDE.md | Claude doesn't understand plugin architecture | Add architecture overview |\n| README documents internals | Users confused by implementation details | README = user guide, CLAUDE.md = internals |\n| Hardcoded paths | Breaks on other machines | Use `${CLAUDE_PLUGIN_ROOT}` everywhere |\n| No error handling in commands | Silent failures | Add explicit error cases |\n| Version not updated in all 4 places | Marketplace shows wrong version | Use the four-place update checklist |\n| Premature extraction into shared\u002F | Over-abstracted, harder to understand | Extract only when 3+ consumers exist |\n",{"name":5,"version":60,"description":7},"0.1.0","main","7850740bd837adb32f0a109ab2af82482196c6f2","skills\u002Fxiaolai\u002Fnlpm\u002Fskills\u002Fnlpm\u002Fwriting-plugins",1,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills","https:\u002F\u002Fzturnsgo.com","https:\u002F\u002Fgithub.com\u002Fshengdabai","https:\u002F\u002Fzturnsgo.com\u002F","AI × education creator — producer, not consumer. Taught 6,000+ learners; shipping learning tools & daily essays with Claude Code, practicing @xiaolai's way 🥋","2026-11-01 21:28:23",{"source":8,"skillName":5,"commands":72,"prompt":82,"zipAvailable":83},[73,76,79],{"tool":74,"command":75},"npx","npx skills add shengdabai\u002FTony-Claude-Code-Skills --skill writing-plugins",{"tool":77,"command":78},"bunx","bunx skills add shengdabai\u002FTony-Claude-Code-Skills --skill writing-plugins",{"tool":80,"command":81},"pnpm","pnpm dlx skills add shengdabai\u002FTony-Claude-Code-Skills --skill writing-plugins","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fxiaolai\u002Fnlpm\u002Fskills\u002Fnlpm\u002Fwriting-plugins\u002FSKILL.md",true,[],[86,95,103,111,119,127],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":90,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":94},"01M73H7XKBHE1ETQDZT94MF9HH","seedance-prompt-en","Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fseedance-prompt-en\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fseedance-prompt-en\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":99,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":94},"01M73GRE9998Q1DZWC71N41JWG","onepage-pdf","Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file\u002Freport\u002Fproposal into a \"single-page PDF\", \"long PDF\", \"不分页 PDF\", \"单页 PDF\", \"长图式 PDF\", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fonepage-pdf\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fonepage-pdf\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":107,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":94},"01M73GQG1KZDADVPV3MHAT1J5A","native-feel-cross-platform-desktop","Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include \"cross-platform desktop\", \"Electron alternative\", \"Tauri vs native\", \"WebView wrapper\", \"near-native performance\", \"Raycast architecture\", \"WebKit\u002FWebView2 quirks\", \"WKWebView\", \"system tray app\", \"global hotkey app\", \"launcher app\". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fnative-feel-cross-platform-desktop\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fnative-feel-cross-platform-desktop\u002FSKILL.md",[],[],{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":115,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":94},"01M73G87PDNSMKG2FHWCYER6N8","gstack","Router for the gstack skill suite. (gstack)","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fgstack\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fgstack\u002FSKILL.md",[],[],{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":123,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":94},"01M73G3EAQWKCM8DB8D0N0QSVG","fireworks-tech-graph","Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent\u002Fmemory, or concept map - and export as SVG+PNG. Trigger on: \"画图\" \"帮我画\" \"生成图\" \"做个图\" \"架构图\" \"流程图\" \"可视化一下\" \"出图\" \"generate diagram\" \"draw diagram\" \"visualize\" or any system\u002Fflow description the user wants illustrated.","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Ffireworks-tech-graph\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Ffireworks-tech-graph\u002FSKILL.md",[],[],{"skillNo":128,"name":129,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":133,"publishedAt":94},"01M73G086AXAH9DW1H5G5N3CPB","dbs-video-extract","接收抖音、小红书、微信视频号等短视频链接或分享文案，查询作品／账号数据并提取语音文字稿，按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用；运行前检查 TikHub 与轻抖使用凭证，缺少时用新手能理解的方式引导购买和安全配置。","https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002Fdbs-video-extract\u002FSKILL.md",[],[]]