agentleFS
TitusKirchTitusKirch/skills/AGENTS.md

skills

AGENTS.md2 starsChanged 4 months agoMITView on GitHub

This repo publishes reusable agent skills — Claude Code, Codex, Cursor, OpenCode and friends. Skills live at skills/<category>/<skill>/ — categories are repo/, work/, docs/, meta/ — each self-contained: a SKILL.md (YAML frontmatter + body) plus optional assets. No runtime code ships except one file: scripts/resolve-config.sh, mirrored into every skill that reads the config. That is what test/ covers — the skill prose has no test/ suite, and none is wanted there. Skill quality is measured out of band instead, by…

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every file named below is the source of truth for what it configures.

    line 5
  2. Very specific:

    Create skills/<category>/<name>/SKILL.md, run pnpm skills:sync, commit as feat(<name>): add skill.

    line 60

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

CLAUDE.md

This repo publishes reusable agent skills — Claude Code, Codex, Cursor, OpenCode and friends. Skills live at skills/<category>/<skill>/ — categories are repo/, work/, docs/, meta/ — each self-contained: a SKILL.md (YAML frontmatter + body) plus optional assets. No runtime code ships except one file: scripts/resolve-config.sh, mirrored into every skill that reads the config. That is what test/ covers — the skill prose has no test/ suite, and none is wanted there. Skill quality is measured out of band instead, by the evals/ convention (skills/README.md): per-skill, with/without-baseline fixtures that are inert dev-only data a development tool runs, never test/, and stripped by packaging and skills:link.

Every file named below is the source of truth for what it configures. Read it rather than trusting a summary here — this file carries only what no file states outright.

Agent instruction files

CLAUDE.md and AGENTS.md are kept byte-identical. CLAUDE.md is what Claude Code reads; AGENTS.md is what vendor-neutral agent tools read — Codex, OpenCode, Cursor, Copilot, and whatever follows them. Two real files, deliberately not a symlink: not every tool resolves one.

After editing either file, copy it over the other — don't repeat the edit by hand:

cp CLAUDE.md AGENTS.md   # or the reverse, whichever you just edited

Retyping a change is exactly how the two drift; one reflowed line or reworded clause is enough. diff CLAUDE.md AGENTS.md must print nothing — pnpm test fails when it does. Fix it by letting one file win wholesale, never by merging them.

Commands

package.json has the full list. The ones with non-obvious behaviour:

CommandWhy it needs saying
pnpm verifyThe repo's gate — check + skills:check + typecheck + test, in CI's order, and the root verify key. CI runs the same commands as one step each, so one run reports every failure; test/ci-gate.test.ts fails if the two lists drift.
pnpm checkLint + format check only — a subset of the gate, not the gate. pnpm check:fix applies both fixers.
pnpm skills:syncRegenerates eleven artifacts from the skill folders. Run after touching any skill.
pnpm skills:checkThe CI guard for the above. Fails if any of them drifted.
pnpm typechecktsc --noEmit. erasableSyntaxOnly is on, so an enum fails here, not at runtime.
pnpm testnode --test over test/ — the resolver, the schema, skill self-containment, the CI-gate guard, the conformance-gate guard, the link destinations, and the CLAUDE.md/AGENTS.md mirror.
pnpm skills:linkSymlinks every skill into both ~/.claude/skills/ (Claude Code) and ~/.agents/skills/ (Codex, Cursor, OpenCode, Gemini CLI) for live local testing — whole-folder, except a skill carrying a dev-artifact dir (evals/) links entry by entry to leave the fixture out, per destination. pnpm skills:unlink clears both; the destination list lives once, in scripts/skills-lib.sh (ADR-0016).
pnpm skills:conformanceValidates every skill against the Agent Skills spec with skills-ref, pinned and run in Docker. Not in verify — the gate stays pnpm-only; this needs Docker. Its own workflow.
pnpm containers:auditOptional Docker + Trivy check, outside verify. Scans the current conformance image from the registry and the VHS renderer built from its template. Prints counts and JSON-report paths; exit 0 = no advisories, 1 = advisories, 2 = a check could not run.

Eleven artifacts are generated — never hand-edit them: the root README.md skills table, each skills/<category>/README.md, .claude-plugin/plugin.json, skills.sh.json's groupings, the <skills-config> block mirrored into each skill that hosts it — with templates/resolve-config.sh copied into each skill that names it, which is every host plus the two queue skills that delegate the prose and still run the script (source: scripts/config-block.md and scripts/resolve-config.sh), the <skills-authority> / <skills-authority-reduced> author-authority block mirrored into each skill that reads third-party text (source: scripts/authority-block.md), the <skills-verify> / <skills-verify-isolated> check-command block mirrored into each skill that runs the repo's gate (source: scripts/verify-block.md), the <skills-worklock> single-flight-lock spec mirrored into the two work-loop unit skills — the two *-queue skills name their worker's REFERENCE for it instead, which is what lets them skip both this block and the config one (source: scripts/worklock-block.md, roster in test/isolation.test.ts), the <skills-plan> plan-presentation rule mirrored into each skill that puts a plan in front of a human (source: scripts/plan-block.md, roster in test/isolation.test.ts), the <skills-tldr> report-lead rule mirrored into each skill whose run ends in a report — a strict subset of the plan roster, since a skill leads with a result only where it closes by reporting one (source: scripts/tldr-block.md, roster in test/isolation.test.ts), and the <skills-forge> forge/host resolution rule mirrored into each skill that drives a forge — the same two *-queue skills name their worker's REFERENCE for this one too (source: scripts/forge-block.md, roster in test/isolation.test.ts). A new category also needs an entry in CATEGORIES in scripts/gen-skills.ts, or the sync fails loudly.

Non-obvious tooling

  • pnpm is mandatory — packageManagerStrict: true plus the packageManager pin. npm/yarn are rejected outright.
  • pnpm-workspace.yaml holds every pnpm setting. pnpm 10+ reads only auth/registry from .npmrc; anything else placed there is silently ignored. There is no .npmrc.
  • A release-age gate is active (minimumReleaseAge in pnpm-workspace.yaml). Packages published inside that window will not install, and pnpm taze reports them as "up to date" rather than as withheld — so "up to date" never proves nothing newer exists.
  • oxfmt formats markdown, JSON and YAML too, not just JS — see lint-staged.config.js. Markdown is the point here; JS is incidental.
  • oxlint and oxfmt are pinned exactly (no ^), which drops them out of taze's default scope entirely — absent from its table, not reported as current. -l brings them back in and composes with the mode (taze minor -w -l). Don't reach for latest to move a pin: it spans majors and will happily propose a 0.x major or a prerelease.
  • scripts/toolchain-versions.json owns the OpenCode pin used by the workflow and integration test. Runtime and CLI consumers read their owner rather than duplicating literals. Eval/test manifests are excluded from workspace discovery and taze; they are development data, never packages to update.
  • Husky runs lint-staged and commitlint on every commit. Don't --no-verify unless asked.
  • Conventional Commits are enforced. Scope by skill name when changing one skill: feat(write-readme): ….
  • release-please cuts releases from main with bump-minor-pre-major, so a pre-1.0 breaking change bumps the minor. Only feat/fix/breaking reach the changelog — typing a user-visible change as chore or refactor silently drops it from the release.

CI gotchas

.github/workflows/ is authoritative. Four behaviours that mislead if unknown:

  • CI runs on: pull_request only, so a commit pushed straight to dev is never checked by CI. The AI work loop is configured branch:dev — it commits to the shared branch with no PR — which makes pnpm verify, run locally before the push, the only automated gate between such a change and the release branch. That is why the root verify key is the full gate and not just lint plus format: nothing downstream would catch a broken test, a type error, or a drifted generated artifact until the rollup PR.
  • Every PR workflow skips drafts, and that is now load-bearing rather than incidental — a draft's check list is not a pass. work-implement opens its PRs as drafts on purpose and work-review marks one ready only once it would accept, so CI is spent once per finished instead of once per push (The draft gate in work-implement's REFERENCE). Each of the three therefore needs both halves: the draft gate and ready_for_review in its trigger types, or the un-draft fires nothing. All three gate on the job, so a draft reports one skipping row per gated job rather than an empty list — which is why anything reading those checks must discard skipping outright instead of treating a non-failing list as green.
  • CodeQL runs on every PR to main/dev, markdown-only ones included — codeql.yml carries no paths: filter, so both matrix legs (actions, javascript-typescript) analyse every pull request; only the draft gate above holds it back. It is not the cheap no-op a path-scoped workflow would be, and the work loop's CI read depends on knowing which workflows a head actually triggers, so this is worth having right.
  • The skill conformance check is a separate workflow, scoped to skills/** and its own script — so it does not run on a PR that touches neither, and, like everything else here, never on a push straight to dev. It re-tiers the deliberate disallowed-tools (ADR-0007) instead of failing on it; test/conformance-gate.test.ts pins that list to validate-skills' prose. Running it locally needs Docker, which is why pnpm verify does not.

Adding a skill

Create skills/<category>/<name>/SKILL.md, run pnpm skills:sync, commit as feat(<name>): add skill. The frontmatter contract and layout live in skills/README.md; the full workflow in CONTRIBUTING.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.