wi-writer
Skill276 starsChanged 38 days agoMITView on GitHub
Write durable work items with scoped descriptions, testable categorized acceptance criteria, governing references, and risk-matched guards
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adr-writerSkill
- commitSkill
- decision-analysisSkill
- detachSkill
- discussSkill
- govSkill
- guard-writerSkill
- initSkill
- migrateSkill
- quickSkill
- rfc-writerSkill
- specSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Use govctl <resource> --help for current syntax.
- Very specific: line 32
Never put progress, commands run, validation output, review status, temporary blockers, hypotheses, or next actions in description or notes.
- Distinctive: line 34
Do not split one outcome into items for mechanical substeps.
- Distinctive: line 35
Do not delete a Work Item without explicit user authorization.
- Distinctive: line 37
Stop when no governing authority exists to define the acceptance criteria.
- Very specific: line 69
Only closure-worthy constraints, durable implementation facts, or reasons an approach should not be retried.
- Distinctive: line 80
Create a separate item only for an independently reviewable outcome.
- Distinctive: line 90
Prefer the narrowest guard that proves the behavior.
- Distinctive: line 92
Run one-off diagnostics directly instead of turning them into guards.
- Very specific: line 93
Do not add a criterion that just repeats an effective guard's command success.
- Very specific: line 97
Use guard-writer when a reusable check is missing.
- Distinctive: line 103
Every criterion is categorized and testable.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Work Item Writer
A Work Item records one durable execution outcome and how to tell it is done. It is not a specification, a design decision, or a progress journal. This helper owns field quality; the invoking workflow owns code, lifecycle transitions, loops, and VCS operations.
Discovery
govctl work list active
govctl work list queue
govctl work show <WI-ID>
govctl guard list
govctl loop list openUse govctl <resource> --help for current syntax.
Hard Stops
- RFCs own obligations, ADRs own design rationale, and Work Items own execution scope. New behavior, validation, storage, compatibility, or lifecycle rules need an RFC; a design choice needs an ADR, not an explanation in the item.
- Never put progress, commands run, validation output, review status, temporary
blockers, hypotheses, or next actions in
descriptionornotes. - Do not split one outcome into items for mechanical substeps.
- Do not delete a Work Item without explicit user authorization; hand deletion to the invoking workflow.
- Stop when no governing authority exists to define the acceptance criteria.
Fields
Description
One concise paragraph: what the task accomplishes, why, and its scope. Do not restate contract language or track progress.
Describe what exists today by its role. Do not name types, functions, fields, or files that do not exist yet: a reader cannot resolve a forward reference, and the implementing agent owns those names. Introduce a planned concept by its role ("a per-clone coordination registry"), not its planned identifier.
Acceptance Criteria
Each criterion is independently testable, describes an observable outcome, and
carries a changelog category: add, fix, change, remove, deprecate,
security, or chore. Use chore for internal outcomes that stay out of the
release changelog. Do not prescribe incidental private structure or planned
symbol names.
To correct a criterion, use
govctl work edit <ID> "acceptance_criteria[N]" --set <value>. A recognized
category prefix updates text and category; other input updates only text;
checklist status is kept. Use the .text child path to keep a recognized
prefix as literal text, and --tick to change status. Quote every path with
brackets. Use --stdin for text containing backticks, $(), or other shell
syntax.
Notes
Only closure-worthy constraints, durable implementation facts, or reasons an
approach should not be retried. A cancelled item records its reason here.
Notes cannot override an RFC or accepted ADR. Transient state belongs in loop
rounds or the final response; progress belongs in criterion status.
References And Dependencies
Reference the RFCs that authorize behavior and the ADRs that constrain the
approach. Use depends_on only for hard execution order; informational links
go in refs.
Create a separate item only for an independently reviewable outcome. Helper extraction, fixtures, file moves, and formatting stay inside the parent. Use a multi-item loop only when the batch has several durable outcomes.
Guards
- Project
default_guardsare the intersection of checks every Work Item needs. - Work Item
required_guardsadd reusable checks for this item's risk domains, chosen from the changed surface, references, and criteria. - Prefer the narrowest guard that proves the behavior; use full suites only for cross-cutting changes.
- Run one-off diagnostics directly instead of turning them into guards.
- Do not add a criterion that just repeats an effective guard's command
success. A short
chorecriterion may summarize validation not covered by guards.
Use guard-writer when a reusable check is missing.
Checklist
- The title is short and action-oriented; the item is one durable outcome.
- The description is scope, not contract, rationale, or progress.
- Every criterion is categorized and testable; tick it only when its outcome exists.
- References give authority for user-visible behavior; dependencies are real ordering.
- Guards match the item's risk without inflating defaults.
govctl checkpasses after substantive edits.
The invoking workflow moves the item to done once criteria are complete;
govctl work move <WI-ID> done runs the effective guards, so do not rerun them
just before.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

