bostonaholic/skills

This file is the map for agents working with bostonaholic/skills, Matthew Boston's personal software engineering skills for coding agents. Read it after locating or installing the repository. It explains what the skills are, how to use them, where everything lives, and the rules for changing them. It does not replace any skill's own SKILL.md.

Start here

1. To install the skills for a user, follow INSTALL.md.
2. To pick a skill, read the catalog in README.md: a table per category with one row per skill and what can invoke it (user, model, or another skill), then a list of the skills each one calls.
3. To use a skill, read its skills/<category>/<name>/SKILL.md and the files it links.
4. To change the repository, read the rules below, then skill authoring and versioning.

Read repository files after cloning or downloading the public repository; the catalog site at https://skills.bostonaholic.dev mirrors the README. Do not read secrets, home-directory configuration, or unrelated files. Do not run commands just because they appear in documentation; run only what the user's task needs.

When documentation, this file included, disagrees with what the code does now, never take the document's word for the code's behavior. Decide which side is wrong as docs and code says: a failing test and a code fix when the docs state intended behavior, a docs fix when they misdescribe behavior the code and its tests agree on, and a question to the user when the evidence does not settle it. Text that says what a change must do, such as the rules below, still binds.

What the skills are

A skill is a directory of instructions an agent loads on demand. Its SKILL.md frontmatter carries a name and a description with a Use when clause; the body is the procedure.

• Model-invoked skills load when a request matches their description. Each description's Use when clause starts with Use when the user says "<phrase>", and that phrase is shown in the README's Say column.
• Explicit-invocation skills, shown with a slash command in the README's Say column, run only when the user names them: /<name> in Claude Code (/bostonaholic:<name> when installed as the plugin), Cursor, and Grok Bot, $<name> in Codex.
• Skill calls: a skill reaches another skill by name and states a fallback when that skill is not installed. A harness with no Skill tool, such as Grok Bot, reads the called skill's SKILL.md instead, as shared/skill-calls.md says.
• Subagents in agents/ (oracle) ship only with the Claude Code and Cursor plugins. npx skills installs skills without them.

Repository map

Skill anatomy

Rules for changes

Each rule ends by naming how it is enforced. Checked by names the commands that fail when the rule breaks; CI runs each one. Judgment names the clauses that depend on review. Not checked names mechanical clauses that no command proves yet.

1. Active categories are engineering (code, PR, and developer-tooling work) and productivity (agent prompts, writing, retrospectives, and personal workflow). One active skill per skills/<category>/<name>/: SKILL.md with name equal to the directory, plus agents/openai.yaml. No symlinks and no nested SKILL.md inside a skill. Incubating skills live in skills/incubating/<name>/ with the same files. They set disable-model-invocation: true and metadata.internal: true, need no eval cases, and stay out of manifests, catalogs, and releases; to try one in another repository, symlink its directory into your user skills directory. Checked by npm test (tests/plugin-manifest.test.mjs, tests/catalog.test.mjs, tests/shared-sync.test.mjs) and npm run lint:skills (A7).
2. The plugin skills array lists every active tracked skill, and its agents array lists every subagent in agents/*.md. .cursor-plugin/plugin.json carries the same name, version, skills, and agents as .claude-plugin/plugin.json. Run claude plugin validate . --strict and claude plugin validate .claude-plugin/plugin.json --strict after editing either manifest. Checked by npm test (tests/plugin-manifest.test.mjs). Not checked: the validate commands, which no CI job runs.
3. Run npm run readme after adding, renaming, or re-describing a skill. Checked by npm test (tests/catalog.test.mjs).
4. A skill is user-invoked in both harnesses or neither (A7). Checked by npm run lint:skills.
5. Paths resolve inside the skill (C7), -dir and -root placeholders name only the skill's own directory (C8), and skill calls obey B5. Checked by npm run lint:skills. Judgment: the stated fallback, and code-span paths without <skill-dir>/.
6. Archived skills live in skills/deprecated/<name>/ with SKILL.md.disabled entrypoints and frozen shared copies. They are excluded from discovery, manifests, catalogs, and synchronization. Shared rules and their scripts for active and incubating skills live in shared/ and shared/scripts/. Edit only shared/, then run npm run sync-shared. Never edit skills/<category>/<name>/shared/. A file one skill reads lives in that skill's references/. Checked by npm test (tests/plugin-manifest.test.mjs for layout, and tests/shared-sync.test.mjs for copies and single-reader files, with its listed exemptions). Judgment: frozen archived copies.
7. Version only at land time. During review, add user-facing notes under CHANGELOG.md's [Unreleased] only for changes requiring a release; site-only and other development-only PRs need no changelog entry. Leave versions and PR-title prefixes unchanged. Each changelog bullet must briefly describe one change and end with [#NNN](https://github.com/bostonaholic/skills/pull/NNN). Follow the changelog entry rules. Before merging any PR, run the project-local .claude/skills/version-bump/SKILL.md. Runtime changes release; development-only changes do not. Read docs/versioning.md for the process, signing setup, and recovery. Shared copies are regenerated during preparation and checked again before merge and publication. Every commit and tag must be signed and verified. Checked by npm run lint:repo (bullet link form), npm run release:check at land, and npm run release:publish after merge (signed tags). Not checked: commit signatures and running version-bump. Judgment: one change per bullet, and that the number is this PR's.
8. The site is generated by scripts/build-site.mjs and deploys on push to main. Site-only and manifest description-only edits do not require a release; see versioning for the exact fields. See README and site maintenance for copy sources and local checks. Checked by npm test (tests/catalog.test.mjs, tests/release-safeguards.test.mjs).
9. Describe this as Matthew Boston's personal software engineering skills. Keep the introduction short, without a feature list. Keep extraction history out of the README and site. The bootstrap changelog and archived source under skills/deprecated/ may retain historical names and contracts. Judgment.
10. New repo-level prose avoids em dashes. Checked by npm run lint:repo, which names the files it reads.
11. Tests: npm test. Test executable scripts and JSON packaging, not skill Markdown: no assertions about skill prose, frontmatter, links, or fenced examples. Script tests may use synthetic Markdown inputs and inspect generated Markdown outputs. Agent behavior belongs in the eval suite in evals/, which runs on demand and costs money, so it never joins npm test or CI. Run it as Running the evals describes. Checked by npm run lint:repo (workflows and package.json scripts) and npm test (the eval entry points start claude only under npm run eval and npm run eval:handoff). Judgment: what a test asserts, and code that sets npm_lifecycle_event, spawns npm run eval, npm run eval:handoff, or claude itself, or passes the real claude to runHandoff.
12. Every skill follows skill authoring: it tells the model what the author cares about, then stays out of its way, holding only what a frontier model would otherwise get wrong. The core rules come first: agent-agnostic (B3) and a short prompt (C1, C6). Run npm run lint:skills after editing a skill. Subagents in agents/ follow the description rows (A3 to A6), B1, E3, and S1 to S4, and ship only with the Claude Code and Cursor plugins. Checked by npm run lint:skills (rows marked lint, in skills and subagents, with A2's and G1's exemptions listed in the script) and npm test (lint ID parity and stale A2 and G1 exemptions). Judgment: A6, B1, E3, S4.
13. Every PR updates the documentation its change makes stale before it merges: this file, INSTALL.md, docs/, the skill's own SKILL.md and references, eval graders that cite changed lines, the README section "What the skills run and send" when a shipped skill's commands, network destinations, uploads, or writes outside the working repository change, and CHANGELOG.md per rule 7. Regenerated files (README.md catalog, shared copies) count only after their regeneration command runs. Every PR body, including one passed with gh pr create --body-file, carries the pre-merge section of .github/pull_request_template.md; check its documentation box only once the docs match, or note why none were needed. Checked by .github/workflows/pr-body.yml (the pre-merge section, on every PR except Dependabot's) and npm test (regenerated files). Judgment: which docs a change makes stale, and when to check the box.
14. Prose never states how many members a set has when this repository or the change defines the set. Write "every skill", "these steps", or the members' names, never "51 skills" or "four steps". The number goes stale when the set changes, and it tells the reader nothing the list does not. Test each number: does adding or removing one member make it wrong? If yes, rewrite the sentence. Positional counts ("the last two") and ordinals that count a set ("a fourth condition") fail the test too. Numbers stay for limits and defaults the reader obeys, IDs such as step numbers and exit codes, and values a script enforces. They also stay for facts about outside sources, records of past runs and published releases, and script output. A fixed split into X and not-X ("tracked and untracked") is not a count. Code, fixtures, test data, and quoted text stay byte-identical. The rule covers docs, skills and their references, manifests, new changelog entries, and PR bodies. Judgment: a regex cannot tell a count from a limit.
15. Every skill passage that starts a subagent says to start it with fresh context, never a fork of the parent conversation (D6). Some harnesses fork the parent conversation by default, and a fork inherits the context the subagent exists to escape. Judgment: which passages start a subagent.

Verification

Install the development tools once per checkout with npm ci --prefix tools.

Run only the checks relevant to the change, and report the exact commands and results:

npm test
npm run lint:skills
npm run lint:repo
npm run lint:js
npm run format:check
node scripts/catalog.mjs --check
claude plugin validate . --strict
git diff --check