Adds a docs page for every promoted skill that lacked one, following
.agents/writing-docs.md and using docs/engineering/to-prd.md as the
worked exemplar. Covers all of engineering/ (bar to-prd, already done),
productivity/, and misc/.
Each page states its load-bearing constraint, its invocation mode and
trigger boundary, surfaces the skill's leading word, and routes back to
ask-matt so the set forms a connected router with no dead ends.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Replace the inline "watch for the leading words" line with an
optional `## It's working if` section — a short list of observable
signals the skill is doing its job. Keeps observability from being
hammered onto leading words specifically.
- Build out to-prd's "What the PRD includes" with proper casing and a
one-line explainer per section.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reframe docs pages around cognitive-load relief: most skills are
user-invoked, so the human is the index that must remember when to
reach for each one. Each page's job is to make one skill memorable
and situate it in the system.
Template changes (.agents/writing-docs.md):
- Quickstart block: install + `npx skills update`, install-first
- New `## When to reach for it` (invocation mode + trigger boundary)
- New optional `## Prerequisites` (workspace/state, prior setup, tooling)
- Free-form middle with one firm rule: surface the leading word
(also an observability signal in the agent's output)
- `## Where it fits`: role-based, absorbs "Pairs well with", links ask-matt
- No H1; every cross-link absolute
Nest docs under bucket folders (docs/<bucket>/<name>.md); the
published URL stays skills-<name> regardless. Re-sync to-prd as the
worked exemplar.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Some blockers are neither a decision, a prototype, nor research — just
literal manual work (moving data, signing up for a service, provisioning
access) that must happen before discussion can move forward.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Relocate this repo's ADRs and invocation.md from docs/ to .agents/,
and update the CLAUDE.md reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Revert Sketch back to Prototype to mesh with the /prototype skill and
existing vocabulary, keeping the generalized function-first definition.
- Move the `## Notes` block from the top of the map to the end.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Decouple the skill from engineering so it plans any domain (e.g. course
content) without specializing toward it. Domain specifics live in the map,
not the skill body.
- Add an optional `## Notes` block to the map: declares the domain + skills
to consult, plus freeform standing preferences. Loaded into every session,
honored by every session, accrues as it emerges.
- Rename the Prototype ticket type to Sketch and define it by function —
raise the fidelity of the discussion with a cheap concrete artifact to
react to (/prototype is one medium among outline/rough-take/stub).
- Note that validation is the thread through all three types, not a type.
- Resolve step now consults skills named in Notes.
The session machinery (one ticket per session, claiming, parallelism,
handoff) is unchanged — it follows from the AI agent's smart/dumb zones, not
the domain.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a header note clarifying that link-skills.sh is a dev-only script for
maintainers, not a supported installer, and that modifications or requests
for modification will not be approved.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Each smell now reads what-it-is → how-to-fix, telegraphic style — the fix
is the actionable half a reviewer needs, kept to a clause.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds Refactoring ch.3 "Bad Smells in Code" into the in-progress `review`
skill. The skill stays two-axis: smells layer into the Standards axis as a
fixed, always-on baseline alongside a repo's documented standards, rather
than a third axis.
Because the baseline is needed on every run it lives inline in SKILL.md.
Each smell is one line — its name carries the definition (the names are
strong leading words) plus a diff-specific cue. Curated to ~12 high-signal
smells; vague ones (Comments, Loops) and tooling-caught ones (Long
Parameter List) are deliberately dropped.
Two rules bind the baseline: a documented repo standard always overrides
it, and every smell is reported as a judgement call, never a hard
violation. The Standards sub-agent prompt now carries the baseline and
these rules.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Refactoring belongs to the review stage, not the implementation loop.
Remove the refactor rule and the now-orphaned refactoring.md (its home is
the review skill), and point the loop's rule at the review skill so it
isn't re-added.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The red → green → refactor loop is anchored by leading words the model
already holds, so the step-by-step Workflow mostly restated the loop and
duplicated the horizontal-slicing anti-pattern. Drop the Workflow and
per-cycle checklist; fold their durable idea (vertical slices / tracer
bullets) into Anti-patterns and a short Rules-of-the-loop list.
Introduce **seam** as the leading word for where tests go, collapsing the
old Philosophy "public interfaces" prose and the Planning "confirm
interface / behaviors" handshake into one rule: test only at pre-agreed
seams, confirmed with the user before any test is written.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tests whose assertion is recomputed the way the code computes it pass by
construction and give zero confidence. Add it as a peer of the existing
implementation-coupling anti-pattern: a Philosophy principle, a per-cycle
checklist gate, and a BAD/GOOD example pair in tests.md. Includes a patch
changeset.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace numeric ticket ids (#1, #2…) with short, token-efficient
dash-case slugs (e.g. relational-db) that read as mini-titles. Update
the Structure example, the next-ticket selection rule (lowest-numbered →
first in document order), the optional-arg wording, and the Handoff
copy-paste examples accordingly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add `publish: npx changeset tag` to the release workflow and enable
tagging for private packages in the changesets config, so merging a
Version PR creates a git tag and GitHub release.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add changesets for tracking and versioning skill changes:
- package.json (private) + @changesets/cli and @changesets/changelog-github
- .changeset/config.json using the GitHub release-style changelog
- release workflow that opens a version PR on push to main (no npm publish)
- initial changeset recording recent skill updates
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
