arda/skills
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add "It's working if" convention; flesh out PRD section

Browse source 
- 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>
This commit is contained in:
Matt Pocock 2026-07-01 11:05:35 +01:00
parent 77cc47773c
commit 340d01b145
2 changed files with 19 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

6
.agents/writing-docs.md
View file

@ -47,7 +47,11 @@ Optional — include only when the skill needs something in place to be function
One to three short sections, in the skill's *own vocabulary*, that make it click — choose whatever headings fit the skill: the loop it runs, the artifact it produces, the fork it makes, the one anti-pattern it kills. There is no prescribed heading; the skills are too heterogeneous for one.
The single non-negotiable: **surface the skill's leading word / load-bearing idea** — `tight` feedback loop, `deep module`, throwaway-code-answers-a-question, red-green. It pays off three ways: the reader learns what the skill *is*, learns the word they'll later think with to *reach for* it, and learns the word to *watch for in the agent's output* — if the leading words come out, the skill fired and is thinking in its own frame; if they don't, that's the tell something is off.
The single non-negotiable: **surface the skill's leading word / load-bearing idea** — `tight` feedback loop, `deep module`, throwaway-code-answers-a-question, red-green. It pays off twice: the reader learns what the skill *is*, and learns the word they'll later think with to *reach for* it.
## It's working if
Optional. A short, checkable list of the observable signals that tell the reader the skill is actually doing its job — what they should see when it fires, and by absence when it hasn't. Include it when a skill has crisp tells (e.g. `to-prd` writes without re-interviewing you; a leading word reappearing in the trace); omit the heading when the signals are vague. A few bullets, no more.
## Where it fits