Skip to content
Skills Library
AI & agents · Building & coding

plugin-authoring

/plugin-authoring

Use when creating, modifying, or debugging Claude Code plugins. Triggers on .claude-plugin/, plugin.json, marketplace.json, commands/, agents/, skills/, hooks/ directories. Provides schemas, templates, validation workflows, and troubleshooting.

Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when creating, modifying, or debugging Claude Code plugins. Triggers on .claude-plugin/, plugin.json, marketplace.json, commands/, agents/, skills/, hooks/ directories. Provides schemas, templates, validation workflows, and troubleshooting.

Original author description

Use when creating, modifying, or debugging Claude Code plugins. Triggers on .claude-plugin/, plugin.json, marketplace.json, commands/, agents/, skills/, hooks/ directories. Provides schemas, templates, validation workflows, and troubleshooting.

How it works

  1. Triggers & Scope
  2. Flow of Operation
  3. Quick Links (Progressive Disclosure)
  4. Checklists
  5. Red Flags (STOP If You're About To...)
  6. Why Validation Matters
  7. Playbooks
  8. Common Workflows
  9. Notes
Original SKILL.md headings · 132 lines, 779 words
SKILL.md preview
---
name: plugin-authoring
description: Use when creating, modifying, or debugging Claude Code plugins. Triggers on .claude-plugin/, plugin.json, marketplace.json, commands/, agents/, skills/, hooks/ directories. Provides schemas, templates, validation workflows, and troubleshooting.
allowed-tools: Read, Grep, Glob
---

# Plugin Authoring (Skill)

You are the canonical guide for Claude Code plugin development. Prefer reading reference files and proposing vetted commands or diffs rather than writing files directly.

**Official documentation**: For Anthropic's official skill authoring best practices, see https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/skill-authoring-best-practices

## Triggers & Scope

Activate whenever context includes `.claude-plugin/`, `plugin.json`, `marketplace.json`, `commands/`, `agents/`, `skills/`, or `hooks/`.

## Flow of Operation

1. **Diagnose** current repo layout (read-only)
2. **Propose** the minimal safe action (scaffold, validate, or review)
3. **Execute** via `/plugin-development:...` commands when the user agrees
4. **Escalate** to the **plugin-reviewer** agent for deep audits
5. **Guardrails**: default to read-only; ask before edits

## Quick Links (Progressive Disclosure)

- **Schemas**: [schemas/plugin-manifest.md](schemas/plugin-manifest.md), [schemas/hooks-schema.md](schemas/hooks-schema.md), [schemas/marketplace-schema.md](schemas/marketplace-schema.md)
- **Templates**: [templates/](templates/)
- **Examples**: [examples/](examples/)
- **Best practices**: [best-practices/](best-practices/)
- **Common mistakes**: [best-practices/common-mistakes.md](best-practices/common-mistakes.md)
- **Testing this skill**: [testing-plugin-authoring.md](testing-plugin-authoring.md)

## Checklists

### Component Checklist

```
□ .claude-plugin/plugin.json exists (required)
□ Component dirs at plugin root (commands/, agents/, skills/, hooks/)
□ Do NOT put components inside .claude-plugin/ directory
□ Commands use kebab-case naming
□ Skills have valid frontmatter (name + description required, optional: model, allowed-tools)
□ Skills name validation:
  - Matches directory name
  - Lowercase letters, numbers, hyphens only
  - Max 64 characters
  - No reserved words ('anthropic', 'claude')
  - No XML tags
□ Hooks use ${CLAUDE_PLUGIN_ROOT} for paths (not relative paths)
□ All scripts are executable (chmod +x)
```

### Release Checklist

```
□ plugin.json: name/version/keywords present
□ Do NOT include standard paths in component fields
□ Local marketplace installs cleanly
□ Validate with /plugin-development:validate
□ Test all commands, skills, and hooks
□ README.md exists with usage examples
```

## Red Flags (STOP If You're About To...)

- Put `commands/`, `agents/`, `skills/`, or `hooks/` inside `.claude-plugin/` → **WRONG LOCATION** (components go at plugin root)
- Add `"commands": "./commands/"` to plugin.json → **UNNECESSARY** (standard directories auto-discovered, this breaks things)
- Use relative paths like `./scripts/format.sh` in hooks → **USE** `${CLAUDE_PLUGIN_ROOT}/scripts/format.sh`
- Skip `/plugin-development:validate` before testing → **ALWAYS VALIDATE FIRST**
- Forget `chmod +x` on hook scripts → **Scripts won't execute (silent failure)**
- Use 'claude' or 'anthropic' in skill names → **RESERVED WORDS (will be rejected)**

**All of these cause silent failures. When in doubt, validate.**

For detailed explanations: [best-practices/common-mistakes.md](best-practices/common-mistakes.md)

## Why Validation Matters

| Skip This | What Happens |
|-----------|--------------|
| Validate manifest | Plugin won't load, no error message |
| chmod +x scripts | Hooks silently fail |
| ${CLAUDE_PLUGIN_ROOT} | Works in dev, breaks on install |
| Standard directory rules | Components not discovered |

**Running `/plugin-development:validate` catches 90% of issues before debugging starts.**

## Playbooks

- **Scaffold** → `/plugin-development:init <name>` then fill templates
- **Add a component** → `/plugin-development:add-command|add-skill|add-agent|add-hook`
- **Validate** → `/plugin-development:validate` (schema & structure checks)
- **Test locally** → `/plugin-development:test-local` (dev marketplace)

## Common Workflows

### Creating a New Plugin

1. Run `/plugin-development:init <plugin-name>` to scaffold structure
2. Edit `.claude-plugin/plugin.json` with your metadata
3. Add components using `/plugin-development:add-command`, etc.
4. Validate with `/plugin-development:validate`
5. Test locally with `/plugin-development:test-local`

### Adding a Slash Command

1. Run `/plugin-development:add-command <name> <description>`
2. Edit `commands/<name>.md` with instructions
3. Add frontmatter: `description` and `argument-hint`
4. Test: `/plugin install` your plugin, then `/<name>`

### Adding a Skill

1. Run `/plugin-development:add-skill <name> <when-to-use>`
2. Edit `skills/<name>/SKILL.md` with your instructions
3. **Frontmatter requirements**:
   - `name`: lowercase letters, numbers, and hyphens only, max 64 chars (required). Cannot contain reserved words 'anthropic' or 'claude'. Cannot contain XML tags.
   - `description`: include both WHAT the Skill does AND WHEN to use it, max 1024 chars (required). Cannot contain XML tags.
   - `model`: specify which Claude model to use, e.g., `model: claude-sonnet-4-20250514` (optional, defaults to conversation's model)
   - `allowed-tools`: comma-separated list of tools (optional). Tools listed don't require permission to use when Skill is active. If omitted, Skill doesn't restrict tools.
4. Keep SKILL.md under 500 lines for optimal performance; place details in sibling files (reference.md, examples.md, scripts/)

### Troubleshooting

- **Plugin not loading?** Check `plugin.json` paths are relative to plugin root. Do NOT include `commands`, `agents`, `skills`, or `hooks` fields for standard directories.
- **Commands not showing?** Verify `commands/` directory exists at plugin root with `.md` files. Do NOT add `commands` field to `plugin.json` for standard paths.
- **Hooks not running?** Ensure scripts are executable (`chmod +x`) and use `${CLAUDE_PLUGIN_ROOT}` for paths
- **Skill not triggering?** Check `name` matches directory and uses lowercase letters, numbers, and hyphens only (max 64 chars). Ensure `description` includes both what and when to use (max 1024 chars). Neither field can contain XML tags.

## Notes

- Prefer templates & scripts over freeform generation for deterministic tasks
- If writes are needed, propose a command or a PR-style diff first
- For complex audits, delegate to `/agents plugin-reviewer`
- Always validate with `/plugin-development:validate` before testing
Files in this package (15)
  • SKILL.md 7 KB
  • testing-plugin-authoring.md 6 KB
  • best-practices/common-mistakes.md 7 KB
  • best-practices/naming-conventions.md 8 KB
  • best-practices/organization.md 9 KB
  • examples/simple-plugin.md 3 KB
  • examples/testing-workflow.md 5 KB
  • schemas/hooks-schema.md 13 KB
  • schemas/marketplace-schema.md 10 KB
  • schemas/plugin-manifest.md 10 KB
  • templates/agent-template.md 1 KB
  • templates/command-template.md 1 KB
  • templates/marketplace-manifest.json 1 KB
  • templates/plugin-manifest.json 1 KB
  • templates/skill-template.md 2 KB

Versions

RepositoryScoreLicence
This page · arcblock/agent-skills100MIT
asgeirtj/system_prompts_leaks100CC0-1.0
laurigates/claude-plugins100MIT
claude-dev-suite/claude-dev-suite100MIT
ivan-magda/claude-code-plugin-template100MIT
rashadansari/myagents90MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version d93ddc1cc992 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100claude-plugins
    Reference for building and distributing Claude Code plugins — plugin.json and marketplace.json structure, bundling commands, agents, skills and hooks, versioning, and publishing a marketplace. Use when creating or packaging a plugin, setting up a marketplace, or debugging why a…
  • 100plugin-creator
    This skill should be used when creating, modifying, or managing Claude Code plugins and plugin marketplaces. Trigger when working with plugin manifests (plugin.json, marketplace.json), creating plugin directory structures, adding plugin components (commands, skills, agents,…
  • 100claude-plugins
    Guide for creating and validating Claude Code plugin.json files. Use when creating plugins, validating plugin schemas, or troubleshooting plugin configuration.
  • 95plugin-writer
    Create new Claude Code plugins from scratch with proper directory structure (.claude-plugin/plugin.json, skills/, agents/), or add existing plugins to marketplace.json. Use when creating a plugin, setting up plugin metadata, configuring MCP servers, or adding plugins to a marketplace.
  • 100plugin-conventions
    ACTIVATE when creating a Claude Code plugin, writing plugin.json, marketplace.json, hooks.json, a hook script, or an evals/evals.json file. ACTIVATE for 'Claude plugin', 'plugin.json', 'marketplace.json', 'hooks.json', 'CLAUDE_PLUGIN_ROOT', 'permissionDecision', 'evals.json'.…
  • 90Claude Code Plugin Builder
    Creates Claude Code plugins with proper manifest structure, directory layout, and components (commands, agents, skills, hooks, MCP servers). This is for Claude Code plugins (`.claude-plugin/plugin.json`) — for Codex plugins (`.codex-plugin/plugin.json`) use the `plugin-creator`…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.