Create Plugin

---
name: create-plugin
description: >-
  Add a plugin, skill, hook, or command to the agent-harness-plugins repository
  and its catalog. Use for "create a plugin" or "add a new skill".
---

# Create Plugin

Create a new plugin for this repository following established conventions.

<!-- The bin/ and docs/ paths below name files in this repository, not in a project a skill runs against. -->
<!-- validate-plugins: repository-paths -->

<!-- The reference filenames below name the layout conventions a plugin being authored should follow; they are not this skill's own reference files. `/example-command` and `/something` stand in for a command not yet written. -->
<!-- validate-plugins: ignore ./references/BASH.md ./references/MARKDOWN.md ./references/checklist.md ./references/github.md ./references/comprehensive ./references/essential ./references/languages ./references/scripts ./references/tools /example-command /something -->

## Workflow

### 1. Determine Plugin Type

Infer the plugin type from the user's request:

- **Skills plugin**: Provides instructions and workflows that Claude Code follows (e.g., style guides, multi-step procedures). Most plugins are this type.
- **Command plugin**: Provides slash commands that users invoke explicitly (e.g., `/example-command`). Commands are structured Markdown files with frontmatter, a workflow, and optional reference templates.
- **Hooks plugin**: Provides event-driven shell commands that run automatically in response to Claude Code lifecycle events (e.g., notifications on task completion).
- **Combinations**: A plugin can provide any combination of skills, commands, and hooks.

Inference heuristic: "create a command", "add a slash command", "add a `/something` command" implies a command plugin. "create a skill", "add a style guide", "add a workflow" implies a skills plugin. "create a hook", "add a notification" implies a hooks plugin.

If the request doesn't imply a type (e.g., just "create a plugin"), ask. If ambiguous, default to a skills plugin.

### 2. Choose a Name

The plugin name must be:

- **Kebab-case** (e.g., `write-go-code`, `suggest-next-issue`)
- **Verb-noun preferred** (e.g., `resolve-copilot-pr-feedback`, `suggest-next-issue`)
- **Descriptive** of what the plugin does
- **Unique** within the `plugins/` directory

If the user provided a name, use it. Otherwise, generate a descriptive name from the plugin's purpose and proceed.

### 3. Create Directory Structure

No manual `mkdir` is needed -- the Write tool creates parent directories automatically when writing files. The directories below are created implicitly when their first file is written in the subsequent steps.

#### Skills Plugin

```text
plugins/PLUGIN-NAME/.claude-plugin/
plugins/PLUGIN-NAME/skills/PLUGIN-NAME/
```

Add a `references/` subdirectory if the skill needs supplementary documentation:

```text
plugins/PLUGIN-NAME/skills/PLUGIN-NAME/references/
```

#### Command Plugin

```text
plugins/PLUGIN-NAME/.claude-plugin/
plugins/PLUGIN-NAME/commands/
```

Add a `references/` directory if the command has large templates to extract:

```text
plugins/PLUGIN-NAME/references/
```

#### Hooks Plugin

```text
plugins/PLUGIN-NAME/.claude-plugin/
plugins/PLUGIN-NAME/hooks/
plugins/PLUGIN-NAME/scripts/
```

#### Combinations

Combine structures under the same plugin directory as needed. A plugin can have any combination of `skills/`, `commands/`, `hooks/`, `scripts/`, and `references/`.

### 4. Write plugin.json

Create `.claude-plugin/plugin.json` with alphabetized fields. See `./references/plugin-json.md` for the full field list, versioning rules, and templates for each plugin type (Skills, Commands, Hooks).

Key points:

- New plugins start at version `1.0.0`
- Include `"skills": "./skills"` only if the plugin provides skills
- Include `"commands": "./commands"` only if the plugin provides commands
- The `name` field must match the directory name

### 5. Write SKILL.md, hooks.json, or Command .md

#### For Skills

Create `skills/PLUGIN-NAME/SKILL.md`. See `./references/skill-md.md` for the frontmatter format, description formula, common sections, and examples. The skill is one workflow shared by Claude Code, Codex CLI, and OpenCode; follow the adapter conventions in the "Cross-harness workflow adapters" section of `docs/plugin-development.md`.

Key points:

- Frontmatter has `name` and `description`, plus `argument-hint` when the skill accepts arguments (required with an `## Options` section)
- The `description` is the routing description: it opens with the primary action, names the trigger phrases that distinguish the skill from its neighbors, and stays short. The catalog summary in `marketplace.json` is written separately
- Use `>-` (folded block scalar) for multi-line descriptions
- Structure the body with a `## Workflow` section using numbered steps
- Write each step against the capability it needs (a structured question, a wait, a browser) with a documented fallback, not against a harness's tool names
- Write each use of another skill as "Invoke the `NAME` skill", and declare every such skill in a `## Skill dependencies` section before `## Workflow`, as required or optional

#### For Commands

Create `commands/COMMAND-NAME.md`. See `./references/command-md.md` for the frontmatter fields, argument handling, external file references, and body structure.

Key points:

- Frontmatter includes `description` and `disable-model-invocation: true`
- Add `argument-hint` if the command accepts arguments
- Use `$ARGUMENTS` and `$1`/`$2` for argument access in the body
- Structure the body with `## Workflow` numbered steps, `## Error Handling`, and `## Reference:` sections
- For large commands, extract templates into `references/` files and include them with the plugin-root file-reference pattern documented in `./references/command-md.md`

#### For Hooks

Create `hooks/hooks.json`. See `./references/hooks-json.md` for the JSON schema, hook categories, matchers, and examples.

Key points:

- Reference scripts with the plugin-root placeholder (see `./references/hooks-json.md` for the exact spelling)
- Each hook entry has `"type": "command"`

### 6. Add Scripts (if needed)

If the plugin needs executable scripts, create them under `scripts/`. See `./references/scripts.md` for the required structure, conventions, and patterns.

Key points:

- No file extension for executables
- Must be `chmod +x`
- Follow the Bash conventions (shebang, strict mode, main function pattern)
- Prefix implementation functions with `do_`

### 7. Add Reference Files (if needed)

Skills and commands that need supplementary documentation or templates should place them under `references/`:

- **Workflow skills**: Use a flat `references/` directory with topic-named files by default (e.g., `./references/checklist.md`, `./references/github.md`). If a workflow skill has enough reference files that a flat list becomes hard to scan, use topical subdirectories named for the organizing axis, such as `./references/languages/`, `./references/tools/`, or `./references/scripts/`. Do not use `./references/essential/` plus `./references/comprehensive/` for workflow skills.
- **Style-guide skills**: Style-guide skills, primarily `write-*`, may use one canonical topic document such as `./references/BASH.md` or `./references/MARKDOWN.md`, or split reference material into `./references/essential/` plus `./references/comprehensive/`. The split is about reading mode: condensed actionable rules versus deep topic-by-topic guidance. It is not a file-count convention.
- **Review checklists**: A style guide whose rules a pull request reviewer can check may add `references/review-checklist.md`, which `set-up-review-config` installs for automated reviewers. It follows the "Review checklists" format in the repository's plugin development guide and needs an entry in `set-up-review-config`'s `references/guides.md`.

**For skills**: Reference files are plain Markdown. Point to them from SKILL.md with relative paths (e.g., `./references/checklist.md`).

**For commands**: Reference files contain templates that the command uses at runtime. Include them in the command file using the plugin-root file-reference pattern (an `@` followed by the plugin-root placeholder and the file path). Place `references/` alongside `commands/` (not inside it). See `./references/command-md.md` for the exact spelling, extraction guidelines, and file format.

### 8. Register in marketplace.json

Add a new entry to the `plugins` array in `.claude-plugin/marketplace.json`. See `./references/marketplace-json.md` for the entry format, valid categories, and insertion conventions.

Key points:

- Insert alphabetically by plugin name
- Include `category` and `source` fields (not present in `plugin.json`)
- All shared fields must match `plugin.json` exactly
- Do not hand-edit `.agents/plugins/marketplace.json`, `dist/codex/`, or `dist/opencode/`; regenerate them with the build scripts

### 9. Update README.md

Add the new plugin to the current compact category-table format in root `README.md`, and create the required per-plugin README. See `./references/readme-updates.md` for the exact format.

1. **Root README category table**: Add a row to the appropriate category table. For skills and command-style plugins, use the `Plugin`, `Trigger`, and `What it does` columns. For hooks, use the hooks table with `Plugin` and `What it does`.
1. **Canonical description**: Use the marketplace `description` field verbatim for the `What it does` column.
1. **External tools**: If the plugin requires external tools, add or update the category's `**External tools:**` bullet list.
1. **Per-plugin README**: Create `plugins/PLUGIN-NAME/README.md` with user-facing install, usage, requirements, examples, and related-plugin details.

Do not add an H3 plugin-description section or an individual install command to the root README, and do not list the plugin in the root README's `## Contents` section. That section navigates headings, not plugins, so a new plugin never changes it. The root README uses category tables, and the marketplace flow handles installation.

### 10. Regenerate Generated Mirrors

Regenerate generated surfaces from the canonical plugin source with `make build`, and commit the generated outputs. It runs, in order:

1. `bin/build-review-checklists`, which copies each style guide's review checklist into `set-up-review-config`.
1. `bin/build-codex-marketplace`, which updates `.agents/plugins/marketplace.json` and `dist/codex/`.
1. `bin/build-opencode-mirror`, which updates `dist/opencode/`.

Do not edit generated mirror files directly. Only update project-level instruction files such as `AGENTS.md` or `CLAUDE.md` when the new plugin changes repository conventions or those files already contain a current plugin catalog that must be kept in sync.

### 11. Verification Checklist

Before finishing, verify:

- [ ] All new files exist with correct structure
- [ ] `plugin.json` fields are alphabetized and `name` matches the directory name
- [ ] `marketplace.json` is valid JSON with the new entry
- [ ] `marketplace.json` entry fields match `plugin.json` (shared fields)
- [ ] `make build` has regenerated the review checklist copies, `.agents/plugins/marketplace.json`, `dist/codex/` and `dist/opencode/`
- [ ] Root `README.md` has the new plugin row in the correct category table, with the marketplace description copied verbatim
- [ ] Root `README.md` external-tool bullets are updated if the plugin needs external tools
- [ ] `plugins/PLUGIN-NAME/README.md` exists and documents installation, usage, requirements, examples, and related plugins
- [ ] Project-level instruction files such as `AGENTS.md` or `CLAUDE.md` were updated only if the new plugin changes current repository conventions
- [ ] `SKILL.md` frontmatter has only `name`, `description` and, for a skill that accepts arguments, `argument-hint` (skills only)
- [ ] The `description` opens with the primary action and carries the distinguishing trigger phrases, without restating the catalog summary (skills only)
- [ ] Steps name the capability they need and a fallback for when it is absent, rather than a single harness's tools (skills only)
- [ ] Every "Invoke the `NAME` skill" reference is declared under `## Skill dependencies` as required or optional, with the missing-skill behavior described (skills that compose others only)
- [ ] All reference files are reachable from `SKILL.md` via relative paths (skills only)
- [ ] Command `.md` has `description` and `disable-model-invocation: true` in frontmatter (commands only)
- [ ] Command filename matches the intended slash command name (commands only)
- [ ] `plugin.json` includes `"commands": "./commands"` (commands only)
- [ ] External file references use the plugin-root file-reference pattern (commands with extracted templates only)
- [ ] `$ARGUMENTS` handling is documented in the workflow if `argument-hint` is set (commands only)
- [ ] Scripts (if any) are executable
- [ ] Hooks (if any) reference scripts with the plugin-root placeholder
- [ ] Skills that invoke a bundled script use the plugin-root placeholder with a `bash` prefix, never a locator glob (see `./references/scripts.md`)

## Error Handling

- If the plugin name already exists under `plugins/`, ask the user for a different name
- If `marketplace.json` cannot be parsed as valid JSON, fix the syntax before proceeding
- If the user is unsure about the plugin type, default to a skills plugin (the most common type)
- If the user wants to add a skill to an existing plugin instead of creating a new one, bump the minor version in `.claude-plugin/plugin.json` and mirror it in `.codex-plugin/plugin.json` when that manifest exists
- If generated review checklist copies, Codex files or OpenCode files drift, run `make build` instead of editing generated files directly