The repeated "The load-bearing constraint:" opener on every page read
as an agent tell. Strip the label across all skill pages and let the
constraint stand as a plain declarative sentence; update the
writing-docs template so it isn't regenerated.
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>
