git:20260609.78c9d67 to git:20260609.002eb29

# Agent Instructions

## Scope

- Repository: `axiom`.

- Product: Claude Code plugin marketplace.

- Marketplace catalog: `.claude-plugin/marketplace.json`.

- Plugins live under `plugins/<plugin>`. Do not assume a default current plugin;

infer the relevant plugin from the user request or changed files.

- Claude compatibility file: `CLAUDE.md` imports this file.

## Repository Map

```text

.claude-plugin/marketplace.json

plugins/<plugin>/.claude-plugin/plugin.json

plugins/<plugin>/README.md

plugins/<plugin>/CHANGELOG.md

plugins/<plugin>/package.json

plugins/<plugin>/release.config.js

plugins/<plugin>/skills/<skill>/SKILL.md

plugins/<plugin>/skills/<skill>/evals/evals.json

plugins/<plugin>/skills/<skill>/reference.md

dev/<plugin>/

.github/workflows/

.github/scripts/

package.json

package-lock.json

```

## Canonical Sources

- `.claude-plugin/marketplace.json` owns marketplace plugin order, plugin names,

plugin descriptions, categories, and `source: "./plugins/<plugin>"`.

- `plugins/<plugin>/.claude-plugin/plugin.json` owns shipped plugin manifest

metadata. Semantic-release owns its `version`.

- `plugins/<plugin>/README.md` owns plugin-level docs and must include a

non-empty `## Eval history` section.

- `plugins/<plugin>/skills/<skill>/evals/evals.json` owns shipped eval scenario

coverage for that skill.

- `dev/<plugin>/` owns eval run output, grading artifacts, benchmark workspaces,

and other non-shipped eval data.

- The root `README.md` is partly generated from the sources above. Do not treat

generated root README content as canonical data.

## Edit Rules

- Keep plugin names, skill names, and directories lowercase kebab-case.

- Use directory-format skills only: `skills/<skill>/SKILL.md`.

- Register each plugin in `.claude-plugin/marketplace.json` with

`source: "./plugins/<plugin>"`.

- Treat `package.json` and `package-lock.json` as release and lint tooling only.

Shipped plugins must not depend on root npm packages at runtime.

- Do not hand-edit `plugins/<plugin>/.claude-plugin/plugin.json` `version`.

- Do not hand-edit `plugins/<plugin>/CHANGELOG.md`.

- Semantic-release owns plugin version bumps, changelog entries, tags, and

GitHub Releases.

- Do not modify `dev/` or `plugins/` unless the user explicitly asks. Read them

only as needed for validation, packaging context, or release wiring.

- Ignore local scratch unless explicitly requested:

`.DS_Store`, `*.local.md`, `.claude/settings.local.json`, `.claude/plans/`,

`DEMO-file-example-spec.md`, `DEMO-skill-creator-evals.md`,

`skill-evals-showcase.html`, and `what-is-a-skill.png`.

- Keep eval run output under `dev/<plugin>/`. Do not move eval run data into a

shipped plugin directory.

- Do not hand-edit generated root `README.md` regions. Update their canonical

sources, then run `npm run docs:readme`.

## Generated README Regions

The root `README.md` has three generated marker blocks:

- `plugin-badges`: generated by `.github/scripts/sync-readme-badges.mjs` from

`.claude-plugin/marketplace.json` and plugin manifests.

- `eval-index`: generated by `.github/scripts/sync-readme-evals.mjs` from

marketplace entries, shipped skill eval manifests, and plugin README eval

history sections.

- `plugin-list`: generated by `.github/scripts/sync-readme-plugins.mjs` from

marketplace entries and plugin manifests.

Use these commands for generated README work:

```bash

npm run docs:readme

```

```bash

npm run docs:readme:check

```

If a generated block is wrong, fix the source data or generator. Do not patch

the generated block directly.

## Adding A Plugin

When adding a shipped plugin:

- Create `plugins/<plugin>/` using lowercase kebab-case.

- Add `plugins/<plugin>/.claude-plugin/plugin.json`; do not hand-edit

`version` after creation.

- Add `plugins/<plugin>/README.md` with a non-empty `## Eval history` section.

- Add at least one directory-format skill under

`plugins/<plugin>/skills/<skill>/SKILL.md`.

- Add shipped eval coverage under

`plugins/<plugin>/skills/<skill>/evals/evals.json`.

- Put eval run output, grading, and benchmarks under `dev/<plugin>/`, not under

`plugins/<plugin>/`.

- Register the plugin in `.claude-plugin/marketplace.json`; marketplace order is

root README display order.

- Run `npm run docs:readme` after changing marketplace entries, plugin

manifests, plugin READMEs, or shipped eval manifests.

## Release Inputs

- PR squash commit title must be a valid Conventional Commit.

- Version impact:

- `feat:` gives a minor release.

- `fix:` and `perf:` give a patch release.

- `feat!:` or a `BREAKING CHANGE:` footer gives a major release.

- `chore:`, `ci:`, `docs:`, `refactor:`, `test:`, `style:`, and `build:` do

not release.

- The type is the header prefix (stock Conventional Commits) — nothing precedes

it. A gitmoji, if used, goes immediately after the colon as the start of the

subject (`feat(scope): ✨ subject`), never before the type (`✨ feat:`). The

`Conventional Commit title` PR check enforces this.

## Validation

Run the smallest relevant check set for the files changed.

For generated root README blocks:

```bash

npm run docs:readme:check

```

For JavaScript tooling changes:

```bash

npm run lint

```

```bash

npm run lint:fix

```

For marketplace entries, shipped plugin layout, skill directories, or shipped

eval manifests:

```bash

npm run check:repo

```

For plugin manifest or shipped plugin structure changes, validate the specific

plugin. If multiple shipped plugins changed, run `npm run check:plugins:local`

instead.

```bash

claude plugin validate ./plugins/<plugin>

```

For workflow, Dependabot, pre-commit, or repository YAML changes:

```bash

npm run lint:yaml

```

For GitHub Actions or pre-commit security hook changes:

```bash

npm run check:precommit:security

```

For spelling-sensitive docs/config changes:

```bash

npm run lint:spelling

```

For Markdown edits that add or change links:

```bash

npm run lint:links

```

For broad pre-commit parity before handing off a cross-cutting change:

```bash

npx prek run --all-files

```

For Markdown edits, run the targeted Markdown quality pass in

[Markdown Rules](#markdown-rules).

```bash

npx -y markdownlint-cli2 --fix path/to/file.md

```

## Markdown Rules

- Every fenced code block must include an explicit language tag.

- Use `text` for plain output, logs, paths, directory trees, errors, and

unstructured snippets.

- For nested fenced code blocks, the outer fence must use more backticks than

the deepest inner fence.

- After editing Markdown, run a targeted quality pass on the edited files:

```bash

npx -y markdown-table-formatter path/to/file.md

```

```bash

npx -y markdownlint-cli2 --fix path/to/file.md

```

- If `npx` cannot write to its cache, rerun the failed command with a temp

cache:

```bash

npm_config_cache=/private/tmp/codex-npm-cache npx -y markdownlint-cli2 --fix path/to/file.md

```

- Inspect the targeted Markdown diff after formatting:

```bash

git diff -- path/to/file.md

```

- Quote markdownlint-cli2 globs.

- Negate markdownlint-cli2 globs with `#`, not `!`.

- Use explicit file paths for targeted Markdown fixes.

- Do not rewrite unrelated Markdown sections to satisfy unrelated lint findings.