docs
Use when writing, editing, or organizing documentation, when planning what docs a feature needs, and whenever planning or implementing a new feature or change in a repo (docs ship with the code). Triggers on "write docs for X", "document this feature", "add a guide", "update the docs", "reorganize the docs", "plan feature X", "implement X", or /docs.
AlemTuzlak · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add AlemTuzlak/skills --skill docs技能说明
name: docs description: Use when writing, editing, or organizing documentation, when planning what docs a feature needs, and whenever planning or implementing a new feature or change in a repo (docs ship with the code). Also use when tempted to write docs without showing the discovered readers to the user, without asking for tone, or without loading simple-english and i-have-adhd. Triggers on "write docs for X", "document this feature", "add a guide", "update the docs", "reorganize the docs", "plan feature X", "implement X", or /docs.
docs
Write docs a real person wants to read. Short, plain, built around someone trying to do a real thing.
"Document feature X" is not the job. "Help someone do Y with X" is the job.
Work in two phases. First plan the story: who reads this, what they want, and how many pages it should be. Then write.
The plan is not private. The user must see the readers and must choose the tone before any page is written.
Find docs
→ read neighbors
→ Phase 1: readers + pages
→ PERSONA GATE (show the list, then stop)
→ TONE GATE (ask, then stop) [when writing pages]
→ load simple-english + i-have-adhd [when writing pages]
→ Phase 2: write
A doc-impact list in a feature plan still runs the persona gate. It does not run the tone gate or load the writing skills until pages are actually written.
When to run
Docs ship with the code. Run this skill at three moments, not only when asked.
- Someone asks for docs. Write them.
- Planning a feature or change in a repo. Before the plan is done, list which docs are new and which need updating. This doc-impact list is part of the plan, the same as the code changes. Name the reader for each page.
- Finishing an implementation. Write or update those docs before you call the work done. A change to how something behaves that ships no doc change is not finished.
Required skills for the final pages
simple-english and i-have-adhd are prerequisites. They apply to the documentation pages, not to this planning chat.
Load both immediately before writing page content. Use the Skill tool if this harness has one. If it does not, Read each skill's SKILL.md from the local skills directory. Do not write pages from memory of those skills.
If either skill is missing, stop and tell the user. Do not write the pages without them.
How they compose:
- This skill owns who the page is for, the page split, problem-then-fix, show-don't-tell, no history leak, forbidden glyphs, and neighbor structure.
simple-englishowns the sentences. Use pragmatic mode. Run its self-check before you call a page done.i-have-adhdowns the shape of the page: next action first, numbered steps, lists capped at 5 (split must vs later, or split the page), no preamble, a visible win at the end.
When i-have-adhd is loaded from this skill, apply it to the pages only. Do not switch the rest of the session into ADHD mode. The persistence section of i-have-adhd does not apply here.
Find the docs first
Before writing anything, find where docs live.
- Look for a docs folder. Check
docs/first, thendocumentation/,content/docs/,site/,website/docs/. - Found nothing? Ask the user where docs should go. Do not guess and do not create a folder on a hunch.
- Open 2 or 3 existing pages near where the new content belongs. Read them for copy, structure, frontmatter fields, and components. Note the apparent tone as a candidate for the tone gate. Do not adopt it yet.
- Note which components the site already uses (steps, tabs, callouts, cards, accordions, code groups, and so on). Different sites have different ones.
- Reuse those components to tell the story. If the site has a steps component, use it for walkthroughs. If it has tabs, use them for framework variations. If the site has none, use plain markdown. Never invent a component the site does not have.
If there is no page like the one you are about to write, read the closest one you can find and match it.
What "match the neighbors" covers, and what it does not
Matching neighbors is about copy, structure, frontmatter, and components: whether headings are sentence case, how much setup a section gets, which components carry the walkthrough, how code samples are introduced, what the frontmatter fields are.
It is not a substitute for the tone gate. Neighbors can suggest a default. They cannot answer for the user.
It is not permission to copy a neighbor's bad habits. Everything in Forbidden and every rule in this skill still applies to the content you write, no matter what the surrounding pages do. An existing page full of em dashes does not license one more.
So: never reason "the other pages do it, so I will too" about a rule this skill states. If existing pages break a rule and you think the whole set should be brought in line, that is a separate cleanup to raise with the user, not something to settle by quietly matching the violation.
Phase 1: plan the story
Do this before you write a word of content.
- List who reads this and what each one wants. A person building on a React SPA, a person on a server-rendered app, someone who just wants a quick demo, someone extending the internals. Do not stop at the first reader.
- Write one user story per reader: "As a X, I want to Y, so I can Z."
- Turn stories into pages. One journey is one page. Different journeys are different pages. A feature with three real journeys is three pages plus maybe a short overview, not one giant page.
- Check every reader has a path. A reader with no page is a hole in the plan. Add a page or a route for them.
The page split comes out of this step. Do not skip it.
Gate: show the personas
After step 4, send a message that contains only:
- Each reader, one user story, and the page you will write for them.
- One qu