custom-skills-doc-writer

Document Writer

The complete process is: investigation → writing card → document assembly → language and fact gatekeeping → final draft review → publication and maintenance. Finishing the draft does not mean completion; delivery occurs only after protected content, paths, links, indexes, evidence boundaries, and reader checks are all complete.

The goal of technical documentation is not to imitate human writing style, but to enable the target reader to obtain correct, sufficient, and verifiable information at the lowest comprehension cost. The priority order is:Correctness → task relevance → clarity → information density → logical coherence → consistency → naturalness. Do not break fixed structures, change the true number of enumerated items, replace fixed terminology, or add unnecessary personality and irregularity in order to reduce AI detectability.

Before starting, internally confirm the six stages and their respective outputs; there is no need to restate known information to the user for the sake of the process.

How to use

/custom-skills-doc-writer [type] [variant]

If the user specifies a type, use it directly. If not specified, first infer from the conversation and existing documents; confirm only when different choices would change the reader, purpose, retention method, or output location.

type	variant	Purpose
`plan`	`general`、`feature`、`refactoring`、`migration`、`rfc`	Plan work or propose a solution
`report`	`investigation`、`analysis`、`status`	Preserve investigation, analysis, or progress results
`research`	None	Organize external evidence, possibilities, and unknowns
`guide`	None	Complete a specific goal
`runbook`	None	Safely repeat operations that may change the system
`tutorial`	None	Learn a capability through one path that can be completed successfully
`reference`	None	Precisely look up fields, interfaces, limitations, or definitions
`explanation`	None	Understand principles, causes, relationships, and trade-offs
`record`	`meeting`、`incident`、`decision`、`changelog`	Preserve facts, events, decisions, or changes
`standard`	None	Define rules, exceptions, and checking methods

After selecting, read document-types.md the corresponding section. Do not load or fill in other types.

Stage 1: Investigation

First read the user's request, the project's AGENTS.md、CLAUDE.md, document index, documents on the same topic, and direct evidence. Skip any entry point the project does not have; do not create an empty structure on your own.

Organize four categories of information:

Facts that have been directly confirmed.
Inferences derived from evidence.
Questions that remain unknown and will affect the content.
The scope that cannot be modified, disclosed, or claimed in this instance.

The AI assistant should check on its own first. Ask only when the data cannot be found, official sources conflict with each other, or the answer requires the user to decide the goal, trade-offs, disclosure scope, and authorization.

Stage 2: Writing card

Create an internal card before starting to write. The card is used to decide the article; do not paste it unchanged into the final draft.

Who is the primary reader? What can it be assumed they already know?
What task are they trying to complete now, or what question are they trying to answer?
What should they know, decide, or be able to do after reading?
What is the primary answer, decision, or action?
What is evidence, what is inference, and what is unknown?
What is in scope? What should not go into this document?
Is this a snapshot of results at a point in time, or an entry point that is continuously maintained?

Next, list the three to five questions that readers must answer before completing the task. A simple document does not need to be forced to three questions; when there are more than five main questions, first check whether a second document purpose has been mixed in, or whether it should be split into an entry point and a details document.

Phase 3: Assemble the document

Start with a minimal skeleton

From document-types.md , get the question order for that type. Headings can be rewritten to fit the content; the key is that each section answers a real reader question.

When evidence grading, option comparison, safe operations, compatibility, or task links are needed, then read the corresponding content in content-blocks.md . Optional content is not a field to be filled in; omit content that has no evidence or does not affect this document's readers.

Write in the order of the answers

At the beginning, state the document's purpose, the current answer, or the action to take, then put the details after.
One section answers one main question. The first paragraph directly gives the answer, status, or action.
Each paragraph in a long body should have one main information responsibility; paragraphs with no identifiable responsibility should be deleted or merged into related paragraphs, and adjacent paragraphs with duplicate responsibilities should be merged first.
If adjacent sections or paragraphs have causality, dependency, comparison, time, or state changes, state the relationship directly and do not make readers infer it themselves.
Put conclusions in the summary and evidence in the body; do not repeat the same passage in the summary, findings, recommendations, and conclusion.
Use tables only for fixed-field comparison of multiple items or precise lookup. Prefer paragraphs for causes, processes, and arguments.
For content that already has an official entry point, use a link and do not copy a new version of the truth.
Treat this skill's process, checks, and safety rules as internal constraints for the Agent; they are not automatically facts about the target system, reader prerequisites, or body content. Write them into the final draft only when an official source also supports them, or when readers really need to execute that operational contract.
Clearly mark information that is temporarily unknown but does not affect the conclusion; if it would change the conclusion or operational safety, stop and ask.

High-risk content must not disappear because of concision

When an operation changes the system, data, services, traffic, permissions, or costs, it must retain the goal, execution identity, impact, non-goals, complete operation, pre-checks, preview, backup, success conditions, stopping points, verification, recovery, and audit records. For details, use the safe operation content in content-blocks.md .

Phase 4: Language and fact gatekeeping

For formal technical documents, especially mixed Chinese-English content, read language-and-fact-check.md. First list the technical strings and facts that must not be rewritten, then separately handle the rewritable Chinese and English explanatory text.

Use the broad principles of ASD-STE100 for English, and use cross-language principles of clear expression for Chinese. These principles are not equivalent to a formal compliance determination; people, times, numbers, commands, conditions, states, scope, or uncertainty must not be changed because of simplification.

First complete the rule-based rewriting of plain technical prose: retain necessary technical terms, and prefer ordinary, direct, and concrete language for other explanations; when a concrete verb can be used, do not package the action in an abstract noun; delete filler, promotional language, vague attribution, synonym loops, excessive qualification, and generic endings.

humanizer-zh-tw It is an optional natural-tone polish, not a fixed completion condition. Use it only when rewritable Chinese explanations still have obvious translationese, customer-service tone, excessive formality, or unnatural syntax.reference、runbook、standard With factual record By default, do not rewrite additionally just to be "more like a real person"; if a humanizer is used, doc-writer's precision, fixed structure, true enumeration counts, format scannability, terminology consistency, evidence boundaries, and safety conditions always take priority. After organizing, re-compare technical strings and facts, and only then run the optional machine check on the final draft.

If the user simultaneously provides the absolute path to a legally obtained ASD-STE100 PDF and the absolute path to a locally approved checker executable explicitly approved by the user or project, automatically execute it according to the reference document's fixed interface. If either is missing, do not run the machine check and still complete the principle-based review. Do not search for, download, or install PDFs, dictionaries, or checkers on your own.

Phase 5: Final Draft Check

When the user specifies line count, word count, format, or required fields, first list them as completion conditions and actually measure them in a reproducible way before delivery. If limits are exceeded, first delete duplicate and irrelevant content; do not delete evidence boundaries, safety conditions, or required information just to shorten it.

According to review-checklist.md check by gate, without mixing all issues into one pass:

Purpose, main line, and information utility.
Paragraph responsibility and coherence.
Evidence and action.
Language, facts, and technical strings.
Format and lifecycle.

For long, cross-layer, or high-risk documents, complete and correct the previous gate before moving to the next. Short documents may combine adjacent checks, but content correctness and reader tasks still take priority over tone and format.

For long, cross-layer, or high-risk documents, also conduct an unfamiliar-reader trial read: pick three to five real questions and have an AI assistant or real person with no conversational context answer based only on the document. Record correct answers, incorrect answers, guesses, failures to find, and citation locations.

AI trial reads can only be labeled "AI comprehensibility check" and cannot replace real-user usage results, command tests, program tests, peer review, or formal approval. Short documents, simple value lookups, or documents with only one clear step do not trigger an additional trial read.

Phase 6: Publishing and Maintenance

Project conventions take priority. When judgment is needed for the knowledge base location, read knowledge-base-organization.md。

Paths and filenames

Choose according to the project's existing structure docs/<type>/<topic>/ or an existing location; do not create a whole set of empty directories for a single document.
Use for point-in-time evidence such as investigations, phases, events, meetings, execution results, and short-term plans YYYYMMDDhh-NN-<title>.md。
Use stable filenames for architecture, specifications, indexes, status boards, reference materials, and long-term operational entry points.
NN is the serial number for the entire project that day; scan all filenames for the day and take the maximum value plus one.

Frontmatter and Index

New Markdown documents include by default title、type、date、author、status; when project rules differ, follow the project. For large knowledge bases, also add the actually consulted topic、related_topics、supersedes or superseded_by, and do not create fields that no one maintains.

When a new document creates a new topic, replaces an old document, or makes a list difficult to browse, update the most recent index and replacement relationship that can help readers find it. There is no need to mechanically update every level of index.

Complete Delivery

When replying to the user, explain:

Which documents were created or modified.
Main conclusions, usage, or decisions.
Which format, link, content, and behavior verifications were performed.
Whether the technical document undergoes an ASD check; the result is not checked, no reminders, reminders present, or tool failure.
What remains unknown, has not yet been performed, or requires manual confirmation.
If there is an operation manual, which section of which document to return to and continue from after success.

Stop conditions

Stop first in the following situations, and do not expand the scope on your own:

The reader or document purpose cannot be determined from the available information, and different choices would change the content.
Authoritative sources conflict with each other on the main conclusions, and this cannot be reasonably explained.
Information is missing that would affect safety, public scope, recovery, or acceptance.
The user lists machine-language checks as required acceptance, but the PDF/checker path is invalid, the tool fails, or the output cannot be interpreted.
The new document would create a second task state, formal specification, or duplicate source of truth.
Historical documents must be batch-moved or unrelated documents must be modified in order to apply the new structure.

When stopping, explain the facts already confirmed, what is missing, the available options, and the impact of each option, then ask the user to decide.

Resource index

Resource	When to read
document-types.md	After selecting the document type, read the corresponding section
content-blocks.md	When the document needs evidence, options, safety, compatibility, or task information
language-and-fact-check.md	When using formal technical documentation, mixed Chinese-English content, or the optional ASD checker
review-checklist.md	After the draft is completed
knowledge-base-organization.md	When a path, index, topic, or lifecycle needs to be determined