AGENT SKILL

technical-document-craftsmanship

Skill #37 — Technical Document Craftsmanship

License 许可
MIT
最近更新
2026-11-14
Stars
★ 18
Forks
6

01 前言 Front Matter

name
technical-document-craftsmanship
metadata
{ "original-index": 37, "short-description": "Skill #37 — Technical Document Craftsmanship" }
description
Skill #37 — Technical Document Craftsmanship

02 资源文件 1

03 SKILL.md 正文

Skill #37 — Technical Document Craftsmanship

Category: Process

Origin

PROJ-100 — Acme Corp Migration Evaluation TDD

Principle

The reader sees the final document, not the git history.

A technical document must read as a coherent, intentional artifact — not as a series of patches. Every section, term, and framing choice must be deliberate and consistent. If the document says "migrate" in one section and "consolidate" in another, the reader loses trust in the author's precision.

Why This Matters

  • ARB members, leadership, and cross-team stakeholders read the document once. They don't see our commits, our iterations, or our corrections.
  • Inconsistent terminology signals sloppy thinking. If we can't be precise about words, can we be precise about migration cost estimates?
  • Draft vs. final is invisible — the first version we share IS the final version in the reader's eyes. There are no "first drafts" once the document leaves our hands.

The Rules

1. Terminology Consistency

Pick one term and use it everywhere. If the action is "migrate," never write "consolidate," "move," "transition," or "convert" as synonyms unless each has a distinct, defined meaning in the glossary.

Example — PROJ-100:

Wrong (inconsistent) Right (consistent)
"Can we consolidate?" (§1) + "Can we migrate?" (§2.3.5) "Can we migrate?" everywhere — because that's the action being evaluated

2. Scope Alignment

Every statement must align with the document's declared scope. If the scope says "Migration Feasibility Study," don't frame questions as "consolidation" — that's a strategic decision above our scope.

Term Who Owns It Our Role
Migrate Engineering (us) Evaluate feasibility, cost, risk
Consolidate Leadership / ARB Strategic decision based on our evaluation

3. Section Independence

Each section should be readable in isolation. If someone jumps to §3.5.4 (Concurrency Model), they shouldn't need to read §1 to understand the framing. Don't rely on "we fixed this in a later section" — every section must stand on its own.

4. No Visible Iteration Artifacts

  • No "UPDATED:" or "FIXED:" markers in the document body
  • No "this was previously incorrect" — just write the correct thing
  • No change logs inside the document — that's what git is for
  • Headers like "The Question We Must Answer" appear exactly once, in the right place

5. Glossary as Contract

If a term appears in the document, it must be in the glossary. If it's in the glossary, it must be used consistently. The glossary is not a reference appendix — it's a contract with the reader about what words mean.

Checklist

# Check When
1 Is every key term used consistently across all sections? Before sharing
2 Does each section align with the declared scope? Before sharing
3 Can each section be read independently without confusion? Before sharing
4 Are there any iteration artifacts visible to the reader? Before sharing
5 Is every term in the glossary used consistently in the body? Before sharing
6 Would someone reading this for the first time see a coherent document? Before sharing

Anti-Patterns

Anti-Pattern Why It's Wrong Fix
Using "consolidate" and "migrate" interchangeably They mean different things and signal different ownership Pick one; define it in glossary
Duplicate headers in different sections Reader sees two "Questions We Must Answer" and doesn't know which is authoritative One canonical location per heading
Leaving placeholder text from iterations "TBD — will be updated" in a shared document undermines credibility Either fill it or remove the section
Framing our work beyond our scope "We recommend consolidation" when our scope is migration feasibility Stay in lane — evaluate, don't prescribe strategy

Relationship to Other Skills

Skill Relationship
#08 — Deep Grep Code Review Grep the document for inconsistent terms before sharing
#11 — Gap Analysis Pattern Same [OK]/[--]/[!!] discipline applies to document sections
#14 — Research Checklist Discipline Research the correct terminology before writing
#36 — GitHub Copilot Usage Policy AI-generated text must meet the same craftsmanship standard

Origin: PROJ-100 — Discovered when "consolidate" and "migrate" were used interchangeably in the Acme Corp TDD. The reader would have seen two different framings of the same question.

04 同仓库更多 Skills

CarlosCaPe
CarlosCaPe/octorato

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 18
CarlosCaPe
CarlosCaPe/octorato

wrangler

Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workspace-skill-discovery

Discover and include ALL skills across the workspace — not just global ones. Use at the start of every session or when the user asks about available skills. Ensures project-level skills (under .claude/skills/ or skills/ in any repo) are never missed.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workers-best-practices

Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

winui-app

Create, build and design WinUI 3 desktop apps with C# and the Windows App SDK following Microsoft's official guidance and CommunityToolkit. Covers XAML, navigation, theming, accessibility and deployment.

★ 18
CarlosCaPe
CarlosCaPe/octorato

windows-brain-script-portability

Scripts in ~/.claude/scripts/ that run on a Windows brain: use the python3.cmd shim and not bare python3, and reconfigure stdout to UTF-8 if you print symbols. Use it when writing a brain script or triaging a Windows-only crash.

★ 18