document-writing

Files (114)

• SKILL.md
• README.md · evals/
• design-system-selection-evals.json · evals/
• evals.json · evals/
• approved-feedback.md · evals/fixtures/approved-feedback-routing/
• foundations.md · evals/fixtures/approved-feedback-routing/
• governance.md · evals/fixtures/approved-feedback-routing/
• index.md · evals/fixtures/approved-feedback-routing/
• patterns.md · evals/fixtures/approved-feedback-routing/
• renderer.ts · evals/fixtures/approved-feedback-routing/
• result-a.svg · evals/fixtures/design-direction-feedback/
• result-b.svg · evals/fixtures/design-direction-feedback/
• incident-exceptions.md · evals/fixtures/design-system-collision/
• index.md · evals/fixtures/design-system-collision/
• request-access.md · evals/fixtures/design-system-collision/
• index.md · evals/fixtures/design-system-existing-update/
• integration-contract.md · evals/fixtures/design-system-existing-update/
• team-notes.md · evals/fixtures/design-system-existing-update/
• tokens.md · evals/fixtures/design-system-existing-update/
• asset-system.md · evals/fixtures/design-system-review-only/
• brand-notes.md · evals/fixtures/design-system-review-only/
• index.md · evals/fixtures/design-system-review-only/
• galaxy-store.md · evals/fixtures/design-system-review-only/stores/
• approved-change.md · evals/fixtures/design-system-warning-update/
• alert.md · evals/fixtures/design-system-warning-update/components/
• button.md · evals/fixtures/design-system-warning-update/components/
• foundations.md · evals/fixtures/design-system-warning-update/
• index.md · evals/fixtures/design-system-warning-update/
• tokens.md · evals/fixtures/design-system-warning-update/
• brand-approval.md · evals/fixtures/expressive-approved-assets/
• collage-template.svg · evals/fixtures/expressive-approved-assets/
• pollen-mark.svg · evals/fixtures/expressive-approved-assets/
• index.md · evals/fixtures/storefront-existing-noncanonical/
• release-coordination.md · evals/fixtures/storefront-existing-noncanonical/
• play-store-assets.md · evals/fixtures/storefront-existing-noncanonical/stores/
• mobile-growth-blog.md · evals/fixtures/supplied-unknown-storefront/
• orbit-market-publisher-guide.md · evals/fixtures/supplied-unknown-storefront/
• action-button.ts · evals/fixtures/supported-implementation/
• approved-contract.md · evals/fixtures/supported-implementation/
• legacy-example.md · evals/fixtures/supported-implementation/
• tokens.json · evals/fixtures/supported-implementation/
• production-suite.json · evals/
• trigger-evals.json · evals/
• validate_existing_update.mjs · evals/validators/
• validate_noncanonical_store.mjs · evals/validators/
• validate_preservation.mjs · evals/validators/
• validate_warning_update.mjs · evals/validators/
• analysis-report-authoring.md · references/document-types/analysis-report/
• analysis-report-overview.md · references/document-types/analysis-report/
• analysis-report-review.md · references/document-types/analysis-report/
• analysis-report-structure.md · references/document-types/analysis-report/
• component-design-contract.md · references/document-types/design-system/
• design-direction-workflow.md · references/document-types/design-system/
• design-rule-contract.md · references/document-types/design-system/
• design-system-authoring.md · references/document-types/design-system/
• design-system-overview.md · references/document-types/design-system/
• design-system-review.md · references/document-types/design-system/
• platform-adaptation.md · references/document-types/design-system/
• app-store-page.md · references/document-types/design-system/prebuilts/
• default.md · references/document-types/design-system/prebuilts/
• …and 54 more

SKILL.md (first lines)

# Document Writing

Create documents that help a specific reader understand, act, decide, comply, recover, or reconstruct what happened. The skill routes first and writes second: a polished document built from the wrong document contract is still wrong.

Document structure, writing style, and review methods are defined in this package. Use `SKILL.md` and its package-local references as the complete working instructions; do not fetch external writing guides or methodological articles to apply the skill. Research needed to verify facts about the requested document's subject follows the source-grounding workflow.

## Scope

This skill supports eleven target document types:

1. Explanatory overview
2. Action guide
3. Reference or specification
4. Proposal
5. Analysis report
6. Policy or rules
7. Troubleshooting runbook
8. Record or meeting notes
9. Feature Design Doc (FDD)
10. Design System Document
11. Software project documentation (README and usage profiles)

The document type describes the artifact being created or assessed. Words appearing only as the subject do not select a type. For example, "write a guide to authoring FDDs" targets a guide, while "write an FDD for saved filters" targets an FDD.

## Workflow

### 1. Identify the requested operation

Identify each separately requested document deliverable and determine whether the user wants to create, update, rewrite, review, fact-check, or normalize it. When an existing document is involved, inspect it before deciding how to proceed. Apply the workflow independently to each deliverable, preserving dependencies and shared source facts; a report and a proposal requested together keep separate document contracts. Do not split one document merely because it contains supporting explanation, recommendations, or steps.

Review is an operation, not a proposal type. A request such as "review this policy" routes to the policy type with the review operation.

Review and fact-check are non-mutating unless the user separately requests an update. They may inspect and research, but must not create, rename, or edit document files. Create, update, rewrite, and normalize are mutating operations within the requested document scope.

### 2. Identify the target artifact

Use evidence in this order:

1. The artifact the user explicitly asks to create or change
2. Existing document metadata, path, title, and headings
3. The reader's primary outcome
4. The content shape implied by the request

If an explicit label conflicts with the requested outcome and the choice materially changes the structure, ask one concise clarification question. Put that question directly in the user-facing response and phrase it so the user can answer the single unresolved choice; a decision note inside an artifact is not a substitute for the question.

### 3. Select exactly one document type per deliverable

| Type | Select when the primary reader outcome is | Do not select when | Start with |
| --- | --- | --- | --- |
| Explanatory overview | Understand a concept, context, or meaning from a readable narrative | The reader needs exact lookup, ordered action, or a design decision source | [explanation-overview.md](references/document-types/explanation/explanation-overview.md) |
| Action guide | Complete a known task from a normal starting state | The starting state is an incident or unknown failure | [guide-overview.md](references/document-types/guide/guide-overview.md) |
| Reference or specification | Look up exact definitions, fields, states, options, or contracts non-linearly | The reader needs a conceptual introduction or whole-feature design | [reference-specification-overview.md](references/document-types/reference-specification/reference-specification-overview.md) |
| Proposal | Choose, approve, fund, or commit to a future action | The document only reports findings or defines an approved feature's design | [proposal-overview.md](references/document-types/proposal/proposal-overview.md) |
| Analysis report | Understand evidence, findings, implications, and limitations | The primary value is chronology or an explicit approval request | [analysis-report-overview.md](references/document-types/analysis-report/analysis-report-overview.md) |
| Policy or rules | Follow durable obligations, permissions, prohibitions, and exceptions | The document is a one-time procedure or a single feature's full design source | [policy-rules-overview.md](references/document-types/policy-rules/policy-rules-overview.md) |
| Troubleshooting runbook | Diagnose and recover from an abnormal state | The reader is following a normal installation or usage path | [troubleshooting-runbook-overview.md](references/document-types/troubleshooting-runbook/troubleshooting-runbook-overview.md) |
| Record or meeting notes | Reconstruct past events, statements, agreements, and chronology | The document interprets evidence as a report or defines current product design | [record-minutes-overview.md](references/document-types/record-minutes/record-minutes-overview.md) |
| Feature Design Doc | Use one product feature's behavior, flows, policies, scope, and alternatives as a design decision source for implementation | The artifact is a feature introduction, guide, interface specification, performance report, or build-approval proposal | [feature-design-doc-overview.md](references/document-types/feature-design-doc/feature-design-doc-overview.md) |
| Design System Document | Use a durable source for product UI foundations, tokens, components, and patterns, or for any digital storefront's visual asset rules | The user wants UI code, a mockup, generated images or assets, or a system or architecture design | [design-system-overview.md](references/document-types/design-system/design-system-overview.md) |
| Software project documentation | Assess an actual software project, install or access it, achieve first use, or find its recurring tasks and configuration | The filename merely wraps another document contract, or the artifact is a standalone API specification, single-task guide, or design decision source | [software-project-overview.md](references/document-types/software-project/software-project-overview.md) |

For software project documentation, the overview owns README/usage profile selection, combined roles, and package-level destinations. Filenames alone do not change the document contract: a design-system index named `README.md` retains its set's contract, and a guide about writing READMEs remains an action guide.

### 4. Apply the Design System Document gate and select prebuilts per output set

Select Design System Document only when a requested artifact governs reusable visual or interaction decisions across product UI or any digital storefront's listing assets. A request whose only deliverable is UI, a mockup, images, video, or other produced assets is a production task, not this document type.

For each output set, choose exactly one prebuilt from semantic intent:

| Prebuilt ID | Select when the document governs | Default output root |
| --- | --- | --- |
| `default` | Product UI foundations, tokens, components, content, accessibility, and patterns | `docs/design-system` |
| `app-store-page` | A digital storefront listing's visual assets, using whatever asset vocabulary and media types its operator defines | `docs/design-system-visual-assets` |

The requested output path never changes a prebuilt. Resolve each root in this order: a user-specified directory for that set, the location of the existing document set being changed or reviewed, then the selected prebuilt's default output root. A user-specified directory replaces only the prebuilt root; it does not collapse a multi-file set into `README.md` or another single file. Read only the prebuilt reference for that output set.

Read the selected type's [overview](references/document-types/design-system/design-system-overview.md) and follow its operation-specific references. The ordered decision table in [design-direction-workflow.md](references/document-types/design-system/design-direction-workflow.md#authoring-decision-order) owns when to ask, write, stop, or report a partial result. Apply it independently to each set; it distinguishes new or direction-changing work, focused revisions, read-only review, and unresolved conditional branches.

Inspect available evidence before asking. For an existing set, inventory the entire tree—not only writable files—and follow its index and approval/change/decision owners before saying that an approved value is unavailable.

If the user explicitly requests both product UI and storefront visual asset systems, split the request into two coordinated Design System Document output sets and apply `default` and `app-store-page` independently. Use their separate default roots unless the user supplies one directory for each; ask once before writing if one custom root does not establish the two destinations.

Two sets for the same product and brand may share an approved upper-level direction when authoritative evidence supports it, but validate and document each set's contextual adaptations independently.

For `app-store-page`, follow [storefront-research.md](references/document-types/design-system/storefront-research.md) for each actually included target. It owns inclusion and identity resolution, official research, operation-specific writes, and capability-limited fallback, including the whole-set stop when neither online research nor sufficient identity evidence is available.

When a request combines a document with actual UI, image, or video production, keep the document portion under this skill and route the production portion to the appropriate capability as a separate deliverable. Do not let either portion suppress or silently replace the other. In the completion report, label document outputs and production outputs separately and attribute each to its owning workflow; do not imply that document authoring itself produced a binary asset.

For product UI, the selected prebuilt defines component-level design contracts and the workflow to include in the document for presenting new UI previews. Document-only work records that workflow; an authorized mixed request also delivers the actual preview through its production capability.

Before reporting a new saved set as complete, follow the structural verification instructions in [design-system-authoring.md](references/document-types/design-system/design-system-authoring.md#structural-verification). A structural pass does not establish direction approval or semantic quality.

### 5. Apply the FDD gate

Select FDD only when all of these are true:

- The subject is one product feature.
- The artifact defines what the feature is and why, including material behavior, flow, policy, scope, or alternative decisions.
- Implementers or code agents should treat the artifact as the current design decision source.

The word "feature" or "FDD" appearing as background is not enough. If the artifact teaches how to write an FDD, route to a guide. If it lists an API contract for a feature, route to reference or specification.

### 6. Resolve generic boundary cases

When no explicit target type settles the choice, use the reader's final action:

- Learn or understand: explanatory overview
- Complete a normal task: action guide
- Retrieve an exact fact or contract: reference or specification
- Approve or choose: proposal
- Interpret evidence: analysis report
- Comply with durable rules: policy or rules
- Recover from failure: troubleshooting runbook
- Reconstruct the past: record or meeting notes
- Govern reusable product UI or digital storefront visual asset decisions: Design System Document
- Evaluate and begin using a software project, or find tasks in its usage manual: software project documentation

Recommendations do not automatically make a report a proposal. Steps do not automatically make a policy a guide. Choose the type that controls why the document exists.

From buYoung/skills, MIT.

More from buYoung/skills