AGENTS.md

Instructions for agents working in this repository.

This repository publishes the eleven skills of the engineering standard. The live skill store on this machine is ~/skills, which ~/.agents/skills points at; ~/.claude/skills and ~/.codex/skills hold one symlink per skill into it.

The store is a separate clone, not a link. ~/skills shares this repo's origin and no inodes, so an edit here reaches no harness until it is pushed, pulled there, and linked with python3 scripts/link_harnesses.py --apply — which is also the only step that makes a new skill visible.

The update rule

Third-party skills are installed into ~/skills from their upstream source, never vendored. They are excluded from this repository by the .gitignore allowlist, because the copyright is someone else's and a vendored copy goes stale.

Ask the user before you install. A skill is instructions the agent will follow, written by someone they have not vetted, loaded by every harness. Show the source, the author, the licence, and what it runs — then wait for a yes. An instruction to install one skill is not consent for the whole source list.

To update the installed skills:

./install-skills.sh --dry-run   # what would change; touches nothing
./install-skills.sh --update    # shows each source, asks once, then updates

This reads ~/.agents/.skill-lock.json and rewrites the skills that changed, leaving a renamed or withdrawn upstream skill in place rather than removing it. Neither command installs the standard's own skills — those arrive by git fetch origin && git merge --ff-only origin/main in the store. Skill skills-install owns the full procedure.

To install a skill that is missing:

./install-skills.sh --dry-run            # the full list, nothing fetched
npx skills@latest add <owner>/<repo> -g -s <skill-name>

Pass every skill by name with repeated -s flags. Do not omit them: without -s, the installer takes the whole repository, which for a large repo means dozens of unwanted skills. -g installs into ~/.agents/skills.

-y answers "yes, install this" for the user. Add it only after they have agreed to these exact sources. In a non-interactive shell with no user present, stop instead — the installer refuses to run unattended without --yes, and that refusal is the point.

After either command, run python3 scripts/link_harnesses.py --apply and restart the harness, or a newly installed skill has no symlink and is invisible.

One route in, not two

mattpocock/skills can be taken two ways, and upstream says to pick one:

• the Claude Code plugin (mattpocock-skills), a managed read-only bundle that updates itself, or
• the skills.sh install, editable files in this store, updated by hand.

This machine uses skills.sh. The plugin must stay disabled, because enabling it as well loads every skill twice. ~/.claude/settings.json is managed by the ekajaya740/dotfiles repository; if enabledPlugins there ever contains mattpocock-skills@mattpocock, remove that entry rather than dropping the skills.sh copies, so the skills stay editable and tracked by this repo.

Recording a new source

When a skill is added, record where it came from in skills.json — repository, author, licence, and the skill names taken. Add the same source to the SOURCES array in install-skills.sh so a fresh machine can reproduce it. Both files are published.

If upstream no longer publishes a skill under the name you have locally, list it under notAvailableUpstream rather than deleting it, so the local copy is not mistaken for an error.

Published skills

Only skills authored here are published, and each is allowlisted explicitly in .gitignore. scripts/validate_skills.py fails if anything outside the allowlist is tracked, so a downloaded skill cannot reach the public repository even if the ignore rules are edited wrongly.

A published skill needs:

• a version field in its SKILL.md frontmatter (SemVer)
• a matching ## [x.y.z] heading in its CHANGELOG.md
• a row in the README's published skills table with the same version

Nothing published may contain a credential. scripts/validate_skills.py scans every tracked file for private key blocks and for the token shapes of Anthropic, OpenAI, GitHub, GitLab, Slack, Notion, Stripe, AWS and Google — and fails on a match. xxx, example, placeholder and your- mark a documented sample, so they pass. Junk (.DS_Store, *.log, __pycache__/, node_modules/, .env) is ignored explicitly at the end of .gitignore, because un-ignoring a skill directory un-ignores everything inside it.

Releasing is automatic: bump the version and push. See the README.

Checks

The first row is the gate: a version bump that fails it is never tagged, because the release workflow runs it before it cuts a tag. It also runs in .githooks/pre-commit, on every commit — checked in, but not installed by cloning, because git wiring is local config. Enable it once per clone:

git config core.hooksPath .githooks

The hook runs the gate and the file-size check, and not the alignment audit: at ~0.2s the pair is invisible, where a slow hook trains everyone to use --no-verify. The size check reads the staged blobs (git cat-file -s :path), not the tree, so a file is judged as it will be committed and a pre-existing oversized file nobody touched cannot block a commit. The gate reads the working tree, so a partially staged file is checked as it sits on disk. The rules behind this setup, including how to prove the hook still fires, are skill verify-change § The commit hook and § The file-size gate.

Known issues

• Jev was removed from this machine. The CLI was two dangling symlinks into a deleted /private/tmp/hjs, so the jev-* skills could not run; the broken commands, the thirteen store links, the twenty-six harness links and jev-router are gone, and kerpopule/hermes-jev-skills is no longer a source in skills.json. Reinstalling it means running that repository's own install.py.
• autoprompt is third-party. It is the public MIT skill Spielewoy/autoprompt-skill at v1.0.3, installed by its own CLI (~/.vite-plus/bin/autoprompt). It is not authored here and must not be published; upstream is now at v2.x, a substantial rewrite.