framework-technical-writing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Framework technical writing

Write public framework documentation for two audiences. Do not mix their jobs in
one file unless the file is explicitly a bridge (short human summary at the top,
then an agent-spec section labeled as such).

This skill is generic. It names no private products, hardware brands, operator
identity, project-specific paths, or vendor capture tools. Capture method lives
on each installer’s product brief — not in shared framework files.

**Provenance (NOTICE-style):** Dual-audience Framework TW bar composed with
upstream technical-writer craft (clarity, task-based writing, progressive
disclosure, scannable structure, API/user-guide patterns, accuracy review).
Upstream cite (path only):
https://github.com/VoltAgent/awesome-claude-code-subagents/blob/main/categories/08-business-product/technical-writer.md
Upstream tool-grant and model frontmatter is stripped — this file is
a writing bar only, not a tool grant. Public git stays generic.

## Classify the file first

Human-facing (general users, installers, visitors):

- README
- getting started / overview / install
- public site copy that describes the framework
- contributing / security / license notices meant for people
- CHANGELOG human face
- capability-report

Agent-facing (seats that execute):

- harnesses
- locks
- checklists
- CoE tables
- story / acceptance-criteria templates
- any markdown an agent is told to follow as procedure

If unsure, split the file rather than blending.

## Human-facing bar

Write as a technical writer for people who have never seen this repo.

- Open with what this is and who it is for.
- Everyday words. Define a term the first time it appears.
- Short sections. Sentence case headings.
- Show the next action a person can take.
- Write as professional enterprise software documentation: high-level
  concepts, workflows, and methodologies. Forward-facing, accessible,
  polished. Distill into clean docs with a TL;DR / executive bottom line
  and structured sections.
- Do not transcribe call notes, personal anecdote, chat voice, or
  “someone said on a call…”.
- No private product names, personal project names, private product paths,
  hardware brands, operator identity, or vendor capture tools. Personal
  project names and private product paths count as PII for framework
  purposes.
- No internal slang, ticket numbers as the only explanation, or "as we discussed."
- No marketing-slop words (delve, unlock, elevate, seamless, robust, leverage,
  empower, journey).
- Neutral, specific, checkable. Completeness is not clarity.

Fail the human page if a new installer cannot say what the framework does, how
to install it, and where to go next.

## Agent-facing bar

Write so an agent can execute without inventing.

- Lead with the rule, then the steps, then the fail condition.
- Use stable names for seats and checks. Spell seat names in full on public
  chrome (Chief of Staff, Product Manager, User Experience, Engineer, Quality,
  Adversary).
- Requirements numbered. Acceptance criteria as checkable boxes.
- Metric: what "done" and "miss" mean. Who detects. Who may not stamp.
- Cite other framework files by path, not by chat.
- Fail-closed: name what is rejected (Do not treat a narrative pass as acceptance, skipped seat, invented source
  of truth).
- Enough detail to program the behavior. Ambiguity is a defect.
- Still generic: process patterns only. If a scar came from private work, rewrite
  it as anonymized process before it lands.
- Capture rule in shared files: "capture the live product the way users actually
  see it, then enhance those frames." Do not name a vendor capture tool. How to
  capture lives on the product brief.

Fail the agent file if a seat could reasonably invent a path, a stamp, a date,
or a product-specific example to fill a gap.

## Craft procedure (enterprise TW)

Apply these as procedure when composing or reviewing public docs. They do not
replace the dual-audience bars or AG locks above.

### Clarity and scan

- Prefer clear language, active voice, and short sentences.
- Keep terminology consistent; define once, reuse the same word.
- Structure for scan: logical headings, one job per section, visual breaks
  between steps.
- Progressive disclosure: start with the next action; put detail after the
  reader needs it.
- Minimalist: cut filler; completeness without clarity is a miss.

### Task-based writing

- Orient human pages around tasks the reader must complete (install, contribute,
  report a security issue), not around internal org charts.
- Step-by-step where a sequence matters; name the outcome of each step.
- Include common scenarios and troubleshooting only when they are checkable and
  generic (no private incident narrative).

### Information types (when the surface needs them)

- Getting started / overview for humans.
- User guides: feature docs, FAQs, quick references — still dual-audience
  classified first.
- API / integration surfaces (when present): endpoint purpose, parameters,
  request/response examples, auth, errors, version notes — verify against the

From paulthorson/agentic-governance, Apache-2.0.

More from paulthorson/agentic-governance