AGENTS.md

This repository holds agent skills in the open Agent Skills format, grouped into categories that install as one unit. Read this file first. Open the linked files only when the task needs them.

Map

Rules

Skill format

• Frontmatter has exactly name, description, license, each a single key: value line. No other fields, no block scalars, no lists.
• name equals the directory name, kebab-case, unique across the repository.
• description says what the skill does and when to use it, names concrete artifacts rather than bare verbs, fits on one line under 1024 characters.
• A skill is self-contained: links stay inside its directory, and nothing in it assumes a particular harness, install path, or environment variable.
• A template that two skills need unchanged is copied byte for byte into each skill and listed in MIRRORS in scripts/validate.py, which fails when a copy differs from its source (0019). Change the source and every copy in the same commit, together with each skill's text that describes the template's inputs, results and limits, which the comment on its MIRRORS entry names.
• SKILL.md stays under 500 lines. Depth goes in references/, copyable files in templates/.

Layout

• SKILL.md lives only at skills/<category>/<skill>/SKILL.md. One skill belongs to one category.
• A category directory holds its skill directories, one CHANGELOG.md, and optionally one README.md, nothing else. The README's images live in visuals/<category>/, never in the category.
• Every category has a plugin entry in marketplace.json with the same name, listing all of its skills as ./skills/<category>/<skill> paths.

Commits and changelogs

• Conventional Commits, description in the imperative mood, lowercase, no trailing period. Scope is the category or the skill: feat(foundations): add …, fix(release-process): correct …. A breaking change carries ! and a BREAKING CHANGE: footer. Renaming or removing a skill, or moving it out of its category, is breaking for its plugin; renaming or removing a category is breaking for the marketplace: feat(foundations)!: ….
• Add the changelog entry under [Unreleased] in the same change, written for users, not from the commit subject. Anything inside a category, and that plugin's own entry in marketplace.json, goes in skills/<category>/CHANGELOG.md. The plugin catalog (plugins added, renamed, removed), install routes, release assets and repository tooling (validator, CI, decisions, evaluations) go in the root CHANGELOG.md. A change that spans both gets an entry in each. The root changelog's lines for plugin releases are written in the release commit, see Release.

Conduct

• Never commit, push, tag, open a pull request, or publish without explicit confirmation in the current conversation.
• Never rewrite a released changelog section or an accepted decision record. Add an entry, or supersede the record.

Release

Plugins and the marketplace are versioned independently, and every plugin release is also a marketplace release (0011). Cut a release with the release-process skill in skills/foundations/release-process/, in its independent-versions mode. The components are the plugins, with changelogs at skills/{component}/CHANGELOG.md, and the root is the marketplace.

• Every version equals the newest release in its changelog: 0.0.0 until the first release, which is 0.1.0. Before 1.0.0 a breaking change bumps the minor version.
• Plugin bumps: patch for fixes and wording in its skills, minor for a new skill, reference or template, major for renaming, removing or moving out a skill.
• Marketplace bumps: patch for catalog fixes and for every plugin release, minor for a plugin added or a new install route or asset type, major for a plugin renamed or removed or a changed marketplace name or install path.
• Every plugin release is also a marketplace release, in the same release commit. Releasing several plugins at once still makes one marketplace release. Its bump is the highest one its changes call for: patch for the plugin releases, raised to minor or major by unreleased marketplace entries that call for it, which ship with it.
• The marketplace section lists the plugins under ### Changed, as - Plugins released with this version: with one nested bullet each: `<category>` [X.Y.Z](https://github.com/theultimate-dev/skills/releases/tag/<category>--vX.Y.Z): and one line for users on what the release gives them. A plugin release cut without a marketplace release is listed under [Unreleased] and ships with the next one. The validator and the release workflow enforce this.
• A release commit, chore(release): …, touches only the released changelogs and the matching versions, with one annotated tag per released stream. main takes changes only through pull requests: merge the release commit's pull request with a merge commit, then push the plugin tags, then the marketplace tag, on that commit, by name and at most three per push; GitHub runs no workflow for larger tag pushes.

How to

Add a skill: check the name is free outside this repository too, on skills.sh and in widely installed packs, because flat installers put skills side by side by name. Then create skills/<category>/<name>/SKILL.md, add its path to the category's skills[] in marketplace.json, add it to the README categories table, add an entry to skills/<category>/CHANGELOG.md, run python3 scripts/validate.py.

Add a category: new directory under skills/ with a CHANGELOG.md whose [Unreleased] links https://github.com/theultimate-dev/skills/commits/main/skills/<category>, new plugin entry in marketplace.json with the same name and "version": "0.0.0", README row, an entry in both the new and the root changelog, and a decision record when the split changes how users install.

Rename, move or remove a skill: breaking for its plugin, and a move is minor for the plugin it joins. Update marketplace.json, the README table, and the changelog of each affected plugin.

Rename or remove a category: breaking for the marketplace. Add a renames entry to marketplace.json that maps the old name to the new one, or to null. A renamed category starts a new CHANGELOG.md whose first entry links the old changelog at its last tag. Log it in the root changelog.

Record a decision: use the decision-records skill in skills/foundations/decision-records/. Cut a release: see Release.

Dogfood: Claude Code reads this checkout as the theultimate-dev marketplace, the README's Route A pointed at the working tree. Set it up once from the repository root with claude plugin marketplace add "$PWD" and claude plugin install <plugin>@theultimate-dev for each plugin. Edits then apply at the next session or /reload-plugins, and every Claude Code session on the machine follows the branch checked out here. To go back to the releases, remove theultimate-dev from extraKnownMarketplaces in ~/.claude/settings.json, then run claude plugin marketplace add theultimate-dev/skills. Other agents get a copy through Route B: npx skills add . -g -a codex pi -y copies the skills into ~/.agents/skills, which Codex and Pi read. Re-run it after each edit. Name only the agents you use, never claude-code, or Claude Code lists every skill twice.

See also: README.md · CONTRIBUTING.md · SECURITY.md