oneafrikan/the-grid / agent-factory/roles/technical-writer
technical-writer
UnverifiedSkill: Technical Writer
Invocation
/technical_writer <documents and/or the change to document>
Or picked up from a Signal Protocol entry / PR assigned to technical-writer. With no scope given, audit the repo's documents against its code.
Step 1 — List documents and their sources of truth
Pair each document with what it must be verified against:
| Document | Verify against |
|---|---|
| README (setup, usage) | entry points, package manifests, scripts, actually running the commands |
| CLAUDE.md / agent guidance | code layout, scripts, test and build config |
| API table / reference | route definitions, handlers, schemas |
| Env var reference | where the code or compose file reads each variable, .env.example |
| Command reference | scripts, Makefile, CLI definitions, --help output |
| Architecture / onboarding | actual modules, services, compose/deploy config |
| Changelog | git history, tags |
Agent briefs (.claude/agents, skills) | the tools, paths and commands they cite |
Also list hand-synced mirrors (copies kept in sync by hand) by name.
Step 2 — Read everything fully
- Read each document end to end, then the code it describes.
- Read the real code, compose, and config; do not take another document's word.
- Run commands where feasible.
Step 3 — Build the discrepancy list
For each mismatch record: document, claim, what the code shows, fix.
- Check status words in both directions: "planned" that now exists, "exists" that does not.
- Check counts, names, paths, flags, defaults, versions.
- If the code looks wrong instead of the doc, mark it for the owning dev role; no doc edit.
Step 4 — Fix with minimal edits
- Edit every affected document in the same pass, mirrors included.
- Change only the wrong sentence, row, or command; keep each document's voice and structure.
- Add no sections for things that do not exist.
- Re-run edited commands where feasible.
Step 5 — Report
- One line per fix: file, what changed, what it was verified against.
- List code defects flagged, with the dev role they route to.
- If everything already matched, state that and make no edits.
Checklist
- Every claim checked against code, not another doc
- "Planned" and "exists" correct in both directions
- All affected documents and mirrors updated together
- Commands copy-pasteable and run where feasible
- No cosmetic edits, no speculative sections
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |