AGENTS.md

Contributor and agent contract for agent-skills. Follows the agents.md format. For the user-facing skill catalogue, see README.md.

Project Overview

A monorepo of reusable agent skills (a SKILL.md plus optional references) for AI coding assistants, installed via npx skills and compatible with Cursor, Claude Code, Codex, and 40+ agents. Each skill is self-contained and ships on its own. There is no application to build or server to run — the "product" is the skill files; the "tests" are benchmarks.

Repo structure (monorepo)

skills/<name>/                     a shippable skill: SKILL.md (+ optional references/, README.md)
benchmarks/<name>/                 benchmark for that skill — OUTSIDE skills/ so it doesn't ship on install
docs/                              contributor guides (this contract links into them)
.claude-plugin/marketplace.json    Claude Code plugin marketplace — one entry per skill in skills/
README.md                          user-facing skill catalogue + install

The closest AGENTS.md wins; this root file governs the whole repo.

Setup & commands

# install / use a skill (consumer side)
npx skills add a-tokyo/agent-skills                      # all skills
npx skills add a-tokyo/agent-skills --skill production-grade

# check every skill against the platform limits (run from repo root)
wc -l skills/*/SKILL.md                                  # whole-file lines (guideline: keep body < 500; this count includes frontmatter)
# full name + description check (handles folded YAML): see docs/skill-authoring.md

# run a skill's benchmark (from inside the repo)
cd benchmarks/<name> && cat README.md                    # method + reproduce steps

There is no root package.json; benchmarks carry their own toolchain (Node + uv/promptfoo).

Code Style — skill authoring

Full rules and the compliance check: docs/skill-authoring.md. The source of truth is Anthropic's best-practices and API guides — the table below is a mirror, confirm at the guide.

Beyond Anthropic's required name/description, every skill in this repo also carries version (semver) and license (MIT) in frontmatter — bump version when behaviour changes.

Plus: progressive disclosure (split into references/ before the body nears 500 lines), references one level deep from SKILL.md, a ## Contents TOC on any reference > 100 lines, fully-qualified MCP names (ServerName:tool_name), forward-slash paths, provide-a-default over a menu, and no time-sensitive wording. Naming is descriptive kebab-case (production-grade); consistency with the existing set beats the gerund default.

Testing — benchmarking

A new or materially changed skill ships a self-contained benchmark in benchmarks/<name>/. The standard is same-model uplift: the same model run with the skill vs. bare, on identical tasks, scored by executing the output. Full method and reproduce steps: docs/benchmarking.md.

Security

A skill that directs the agent to fetch third-party content (docs, web pages, MCP issue/ticket bodies, other repositories) must frame that content as untrusted data, not instructions — the indirect-prompt-injection posture. skills/production-grade/SKILL.md (rule M2) is the reference implementation. Never commit secrets; .env is git-ignored.

PR Guidelines

• Branch off main; never commit directly to main.
• Before pushing: run the limit check (above) and the relevant skill's benchmark if you changed a SKILL.md.
• Keep diffs surgical — one concern per PR; a rename ships separately from a feature.
• Bump the skill's version in its frontmatter when its behaviour changes.
• A new skill needs an entry in both the README table and .claude-plugin/marketplace.json (source: "./", skills: ["./skills/<name>"], strict: false). When you bump a skill's version, update that same skill's entry in marketplace.json to match — the two are independent fields Claude Code doesn't sync automatically.
• Commit subject in imperative mood; explain why in the body.