plugin-authoring
/plugin-authoring
Add, modify, or delete a skill or plugin in this repo — frontmatter shape, the seven metadata files a plugin touches, and the create/delete checklists. Use when creating a new skill or plugin, removing one, or asking which files a plugin change must update.
- Author
- laurigates ↗
- Repository
- claude-plugins ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Add, modify, or delete a skill or plugin in this repo — frontmatter shape, the seven metadata files a plugin touches, and the create/delete checklists. Use when creating a new skill or plugin, removing one, or asking which files a plugin change must update.
Arguments
/plugin-authoring (no args)
Original author description
Add, modify, or delete a skill or plugin in this repo — frontmatter shape, the seven metadata files a plugin touches, and the create/delete checklists. Use when creating a new skill or plugin, removing one, or asking which files a plugin change must update.
How it works
- Creating New Skills
- Creating User-Invocable Skills
- Plugin Lifecycle
- Development Workflow
- Verify
- Related
SKILL.md preview
---
name: plugin-authoring
description: Add, modify, or delete a skill or plugin in this repo — frontmatter shape, the seven metadata files a plugin touches, and the create/delete checklists. Use when creating a new skill or plugin, removing one, or asking which files a plugin change must update.
allowed-tools: Read, Edit, Write, Grep, Glob, Bash(mkdir *), Bash(jq *), Bash(git log *), Bash(bash scripts/check-docs-index.sh *), Bash(bash scripts/plugin-compliance-check.sh *), TodoWrite
argument-hint: (no args)
created: 2026-07-29
modified: 2026-10-09
reviewed: 2026-07-29
---
# /plugin-authoring
The authoring procedures for this marketplace: how to create a skill, how to
create a plugin, what to update when either changes, and how to delete one
without leaving dangling metadata.
Promoted out of `CLAUDE.md` (issue #2140) because all four are **procedures with
a clear trigger** — they do not need to be resident when the user is debugging a
hook. `CLAUDE.md` keeps only the repo blurb, the rules index, and the gotchas.
Detailed patterns live in the rules this skill names; it is the sequence, not a
second copy of them.
## Creating New Skills
See `.claude/rules/skill-development.md` for detailed patterns.
> **Note (Claude Code 2.1.157):** plugins placed in `.claude/skills` are now auto-loaded without a marketplace entry — handy for local or quick one-off plugins. This repo's *published* plugins still use the full marketplace + release-please lifecycle described in Plugin Lifecycle below.
### Quick Start
1. Create skill directory: `mkdir -p <plugin>/skills/<skill-name>`
2. Create `skill.md` with YAML frontmatter:
```yaml
---
name: <Skill Name>
description: <1-2 sentence description>
allowed-tools: Bash, Read, Grep, Glob, TodoWrite
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
---
```
3. Follow content structure: Core Expertise → Commands → Patterns → Quick Reference
4. Include agentic optimizations table
5. Update all metadata files (see Plugin Lifecycle section)
### Skill Granularity Decision
| Choose... | When... |
|-----------|---------|
| Single skill | Operations are related and share context |
| Multiple skills | Distinct workflows, different user intents |
Example: `bun-package-manager` (deps) vs `bun-development` (run/test/build)
## Creating User-Invocable Skills
Skills are invocable via `/plugin:skill-name` syntax. See `.claude/rules/skill-naming.md` for naming conventions.
1. Create skill directory: `mkdir -p <plugin>/skills/<skill-name>`
2. Create `SKILL.md` with YAML frontmatter:
```yaml
---
name: <skill-name>
description: What it does. Use when...
args: <arg-spec>
allowed-tools: Bash, Read
argument-hint: human hint
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
---
```
3. Include: Context → Execution → Post-actions
## Plugin Lifecycle
### Files to Update
When creating, modifying, or deleting a plugin, update these files:
| File | Location | Action |
|------|----------|--------|
| `plugin.json` | `<plugin>/.claude-plugin/plugin.json` | Create/update plugin manifest |
| `README.md` | `<plugin>/README.md` | Create/update plugin documentation |
| `marketplace.json` | `.claude-plugin/marketplace.json` | Add/update/remove plugin entry |
| `release-please-config.json` | Root | Add/remove plugin package config |
| `.release-please-manifest.json` | Root | Add/remove plugin version entry |
| `PLUGIN-MAP.md` | `docs/PLUGIN-MAP.md` | Add/remove plugin from navigation map |
| `settings.json` | `.claude/settings.json` | Add/remove the plugin in `enabledPlugins` (`<plugin>@laurigates-claude-plugins`) — enforced by the `Plugin: Enablement drift` check |
`docs/CATALOG.md` is generated from `marketplace.json` and the plugin dirs, so it
is not on this list: the `generate-catalog` pre-commit hook rewrites it, or run
`just catalog`. CI fails a PR whose committed catalog is stale.
### Creating a New Plugin
> **Quick scaffold (Claude Code 2.1.157):** `claude plugin init <name>` scaffolds a new plugin in `.claude/skills` (auto-loaded, no marketplace entry needed). Use it for local/quick plugins; for plugins published from this repo, follow the full marketplace + release-please steps below.
1. Create plugin directory structure (see Project Structure in `CLAUDE.md`)
2. Create `.claude-plugin/plugin.json`:
```json
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "new-plugin",
"version": "1.0.0",
"description": "Plugin description",
"author": {
"name": "Lauri Gates"
},
"license": "MIT",
"keywords": ["keyword1", "keyword2"]
}
```
`license` (from the allowlist `["MIT"]`) and `author.name` are required here and in the marketplace entry below; `bash scripts/plugin-compliance-check.sh --license-only` fails the PR without them. The repo-root MIT `LICENSE` covers every plugin, so no per-plugin `LICENSE` file is needed.
3. Create `README.md` with plugin documentation
4. Add entry to `.claude-plugin/marketplace.json` (under the `plugins` array), carrying the same `author` and `license` as the plugin's `plugin.json`:
```json
{
"name": "new-plugin",
"source": "./new-plugin",
"description": "Plugin description",
"version": "1.0.0",
"author": {
"name": "Lauri Gates"
},
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"category": "category-name"
}
```
Note: marketplace.json has structure `{ "name": "...", "plugins": [...] }` — add to the `plugins` array. `python3 scripts/sync-plugin-configs.py --fix` generates this entry from the manifest.
5. Add to `release-please-config.json`:
```json
"new-plugin": {
"component": "new-plugin",
"release-type": "simple",
"extra-files": [
{"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"}
],
"changelog-sections": [
{"type": "feat", "section": "Features"},
{"type": "fix", "section": "Bug Fixes"},
{"type": "perf", "section": "Performance"},
{"type": "refactor", "section": "Code Refactoring"},
{"type": "docs", "section": "Documentation"}
]
}
```
6. Add to `.release-please-manifest.json`:
```json
"new-plugin": "1.0.0"
```
7. Enable it in `.claude/settings.json` so the repo dogfoods it:
```json
"enabledPlugins": { "new-plugin@laurigates-claude-plugins": true }
```
The `Plugin: Enablement drift` check (`scripts/check-enabled-plugins-drift.sh`) fails CI if a marketplace plugin is left disabled.
### Deleting a Plugin
1. Remove plugin directory
2. Remove entry from `.claude-plugin/marketplace.json`
3. Remove package from `release-please-config.json`
4. Remove version from `.release-please-manifest.json`
5. Remove the `<plugin>@laurigates-claude-plugins` key from `.claude/settings.json` `enabledPlugins`
## Development Workflow
1. **Research documentation** - Use context7, web search
2. **Plan skill structure** - Decide granularity, scope
3. **Write skills** - Follow standard structure
4. **Update all metadata files** - See Plugin Lifecycle section
5. **Commit early** - Use conventional commit format (see `.claude/rules/conventional-commits.md`)
6. **Test** - Verify skills load and work
7. **Create PR** - Use conventional commit format for title (drives automation)
## Verify
After a plugin add or delete, the two guards that catch dangling metadata:
```
bash scripts/check-docs-index.sh
bash scripts/plugin-compliance-check.sh
```
`check-docs-index.sh` cross-checks the plugin set and per-plugin skill/agent
counts against disk across `README.md`, `docs/PLUGIN-MAP.md`, and the d2
diagram — use `/docs-refresh` to repair count drift it reports. It also gates
two name-level invariants at ERROR severity (`--strict` therefore fails CI):
the **committed** `docs/diagrams/plugin-relationships.svg` must render the same
per-plugin labels its `.d2` source states (re-render with
`d2 docs/diagrams/plugin-relationships.d2 docs/diagrams/plugin-relationships.svg`
— never hand-edit the `.svg`), and every leading-cell `/<ns>:<name>` row in a
plugin README must resolve to a skill directory (#2453).
## Related
- `.claude/rules/skill-development.md` — skill creation patterns
- `.claude/rules/skill-naming.md` — namespace conventions for user-invocable skills
- `.claude/rules/skill-quality.md` — size limits, required sections, quality checklist
- `.claude/rules/plugin-structure.md` — plugin.json schema and directory layout
- `.claude/rules/release-please.md` — version management and changelog automation
- `.claude/rules/conventional-commits.md` — the commit/PR-title format that drives release-please
- `.claude/rules/skill-consolidation.md` — merging or deleting skills (distinct from the plugin-level checklist here)
- `/docs-refresh` — repairs catalog count drift after a skill or plugin lands
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · laurigates/claude-plugins | 100 | MIT |
| asgeirtj/system_prompts_leaks | 100 | CC0-1.0 |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| arcblock/agent-skills | 100 | MIT |
| ivan-magda/claude-code-plugin-template | 100 | MIT |
| rashadansari/myagents | 90 | MIT |
Database snapshot: 13.11.2026 · package version b34d7c9f17d2 (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
- 100marketplace-authoring
Add, modify, or delete a skill or plugin in this repo — frontmatter shape, the seven metadata files a plugin touches, and the create/delete checklists. Use when creating a new skill or plugin, removing one, or asking which files a plugin change must update. - 100update-skill
Create or update skills by generating, editing, or refining SKILL.md files in this repository. Use when authoring new skills or revising the structure, frontmatter, or guidance for existing ones. - 85update-plugin
Inspect, edit, or extend custom plugins the user owns or has permission to edit. Use when the user asks to change a plugin's instructions, skills, tools, app UI, Extensions, metadata, assets, or configuration, delete packaged files, or inspect a previous version. - 100plugin-best-practices
This skill should be used when the user asks to "validate plugin structure", "review manifest files", "check frontmatter compliance", "verify tool invocation patterns", "explain plugin component types", or needs Claude Code plugin architectural guidance. - 90skill-authoring
Create, edit, or review a skill in the ramottamado/skills repository (a repo with skills/<name>/SKILL.md and a .claude-plugin/marketplace.json). Use when the user asks to add a new skill, rewrite a skill's description or triggers, split a skill into references, or check a skill… - 100create-plugin
This skill should be used when the user asks to "create a plugin", "make a GitHub plugin", "turn my repo into a plugin", "create a Claude Code plugin", "create a Codex plugin", "publish my skills as a plugin", or "set up a plugin marketplace". Scaffolds the complete file…