juanmarchetto/doc-standards-skill
Developer tools이 페이지는 AI로 자동 번역되었습니다. 기술적인 세부 사항은 원문을 확인하세요. 원문 보기
Claude Code skill: five-layer documentation quality standards (ASD-STE100, Google/Microsoft style, ISO 24495, AI readability) with a machine-checkable lint gate
개요
A Claude Code skill that makes documentation pass professional writing standards — and proves it with a lint gate. Documentation written by an LLM has a smell: synonym rotation, subordinate clauses, filler, hedging. This skill removes it with the constraints professional documentation systems already use. The idea started from a post by @dcoderio about ASD-STE100, then grew into a five-layer criteria stack. Copy the doc-standards folder into your skills directory: Claude Code picks it up automatically. The skill triggers on requests such as "write docs", "document this", "improve the README", or "the docs smell AI-written". check_docs.py needs only Python 3. It checks sentence length, passive voice, banned words, terminology drift, heading hierarchy, and relative-link integrity: When you install Vale and add a .vale.ini to the project, the script defers its style checks to Vale and keeps only the structural checks.
README
원문 README의 일부입니다. 원문 보기.
doc-standards
A Claude Code skill that makes documentation pass professional writing standards — and proves it with a lint gate.
Documentation written by an LLM has a smell: synonym rotation, subordinate clauses, filler, hedging. This skill removes it with the constraints professional documentation systems already use. The idea started from a post by @dcoderio about ASD-STE100, then grew into a five-layer criteria stack.
The five layers
| Layer | Question it answers | Source standard |
|---|---|---|
| 1. Structure | Which document am I writing, for whom? | Diátaxis + ISO 24495-1 |
| 2. Controlled language | Is each sentence unambiguous? | ASD-STE100 |
| 3. House style | Is it consistent with developer-docs convention? | Google / Microsoft style guides |
| 4. AI readability | Can an agent retrieve and use each section alone? | llms.txt + retrieval practice |
| 5. Verification | Can a machine enforce layers 2–4? | Vale or the bundled checker |
Install
Copy the doc-standards folder into your skills directory:
cp -r doc-standards ~/.claude/skills/doc-standards
Claude Code picks it up automatically. The skill triggers on requests such as “write docs”, “document this”, “improve the README”, or “the docs smell AI-written”.
What is inside
doc-standards/
├── SKILL.md # workflow: structure → draft → style → AI pass → gate
├── references/
│ ├── ste100.md # ASD-STE100 digest: word, sentence, and safety-text rules
│ ├── style-guides.md # Google + Microsoft house-style digest
│ ├── ai-readability.md # self-contained sections, llms.txt format
│ └── vale-setup.md # Vale install, per-project config, CI
├── scripts/
│ └── check_docs.py # zero-dependency lint gate
└── evals/
└── evals.json # test prompts for the skill-creator eval loop
The lint gate
check_docs.py needs only Python 3. It checks sentence length, passive voice,
banned words, terminology drift, heading hierarchy, and relative-link integrity:
python3 doc-standards/scripts/check_docs.py docs/
When you install Vale and add a .vale.ini to the project, the script
defers its style checks to Vale and keeps only the structural checks. The exit code is 1
when any error-level finding exists, so the gate drops into CI as-is.
Terminology drift is the check that catches the strongest LLM tell. When a document uses “verify”, “check”, and “confirm” interchangeably, the gate reports it and the skill prescribes the fix: a terminology table with one approved term per concept.
Does it work?
추천 도구
다른 키워드를 입력하거나 필터를 제거해 보세요.
설치
npx skillfish add juanmarchetto/doc-standards-skill