Claude Skill

docs

Write or revise technical documentation around one reader job: reference, operation, review, decision, or product alignment. Use for READMEs, API docs, operational how-tos, RFCs, product design docs, architecture proposals, and ADRs.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download kriscard-skills-skills_writing_docs-08395f4.zip · 11 KB

Install

skills CLI npx skills add https://github.com/kriscard/Skills/tree/main/skills/writing/docs
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kriscard-skills@llmmart
Git git clone https://github.com/kriscard/Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kriscard/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Technical Documentation Writer

Write for the reader's job: what they came to understand, decide, or do. A technically correct doc that does not serve that job is still a failed doc.

Boundaries

  • Use blog for publishable articles with an argument, story, or public-facing lesson.
  • The user-invoked teach skill owns persistent learning workspaces and HTML lessons.
  • Use this skill for reference docs, team proposals, decision records, READMEs, API docs, and how-to docs whose primary purpose is work, review, or operation.

Workflow

1. Name the doc type and reader job

Identify the document type before drafting: README, API docs, how-to, RFC or architecture proposal, product design doc, or ADR.

Complete when:

  • the doc type is named
  • the primary audience is named
  • the reader job is stated as Reader needs to <do/decide/understand> so they can <outcome>
  • missing inputs are requested before drafting

2. Load the matching reference

Use the routing table below. Load every reference whose condition applies before writing. The technical-style reference is additive: load it only when the prose needs sentence-level clarity work, not merely because the document is technical.

Complete when every applicable reference has been loaded, or no reference applies and that is stated.

3. Gather the minimum context

Ask only for context needed by the reader job:

  • current state and desired outcome
  • constraints, dependencies, and owners
  • concrete examples, commands, APIs, or decisions
  • known errors, risks, alternatives, or non-goals

Complete when every required placeholder in the selected template has either source material or an explicit TBD/question for the user.

4. Draft for use, review, or decision

Lead with what the reader needs first. Show before explaining when the reader must do something; state the decision or proposal before deep rationale when the reader must decide.

Complete when:

  • the opening answers the reader job
  • every section exists to help the reader do, decide, or understand something
  • examples are realistic and include required setup/config/error handling when relevant
  • uncertainties are marked instead of invented

5. Run the quality gate

Before delivering, verify:

  • First sentence says what this is or what decision/proposal is being made
  • Code examples or commands were run when an environment is available; otherwise marked unverified
  • Required config, inputs, env vars, and permissions are documented
  • Common errors or risks include what to do next
  • Links referenced in the doc were checked when accessible
  • Terminology is consistent: one name per concept
  • No "simple" / "just" / "easy" for user actions

Complete when all applicable checks pass or failures are called out explicitly.

References

Priority Load when Reference
1 Decision already made; capture context, decision, and consequences references/adr-template.md
1 Change not decided; solicit review, including system design with migration concerns references/rfc-template.md
1 Scoping new product work with goals, non-goals, user stories, and metrics references/design-doc-template.md
2 Creating or revising a README references/readme-guide.md
2 Creating or revising API documentation references/api-docs-guide.md
2 Creating or revising a task-oriented how-to guide references/how-to-guide.md
3 Technical prose needs sentence-level clarity work: reader-mode boundaries, condition/action order, common-path ordering, technical names, link text, modifier scope, or list introductions references/technical-style.md
Files (skills)
  • references
    • adr-template.md 2.4 KB
      Loading…
    • api-docs-guide.md 883 B
      Loading…
    • design-doc-template.md 3.5 KB
      Loading…
    • how-to-guide.md 864 B
      Loading…
    • readme-guide.md 855 B
      Loading…
    • rfc-template.md 3.6 KB
      Loading…
    • technical-style.md 4.7 KB
      Loading…
  • SKILL.md 3.9 KB
    ---
    name: docs
    description: "Write or revise technical documentation around one reader job: reference, operation, review, decision, or product alignment. Use for READMEs, API docs, operational how-tos, RFCs, product design docs, architecture proposals, and ADRs."
    ---
    
    # Technical Documentation Writer
    
    Write for the reader's job: what they came to understand, decide, or do. A technically correct doc
    that does not serve that job is still a failed doc.
    
    ## Boundaries
    
    - Use `blog` for publishable articles with an argument, story, or public-facing lesson.
    - The user-invoked `teach` skill owns persistent learning workspaces and HTML lessons.
    - Use this skill for reference docs, team proposals, decision records, READMEs, API docs, and
      how-to docs whose primary purpose is work, review, or operation.
    
    ## Workflow
    
    ### 1. Name the doc type and reader job
    
    Identify the document type before drafting: README, API docs, how-to, RFC or architecture proposal,
    product design doc, or ADR.
    
    Complete when:
    
    - the doc type is named
    - the primary audience is named
    - the reader job is stated as `Reader needs to <do/decide/understand> so they can <outcome>`
    - missing inputs are requested before drafting
    
    ### 2. Load the matching reference
    
    Use the routing table below. Load every reference whose condition applies before writing. The
    technical-style reference is additive: load it only when the prose needs sentence-level clarity work,
    not merely because the document is technical.
    
    Complete when every applicable reference has been loaded, or no reference applies and that is stated.
    
    ### 3. Gather the minimum context
    
    Ask only for context needed by the reader job:
    
    - current state and desired outcome
    - constraints, dependencies, and owners
    - concrete examples, commands, APIs, or decisions
    - known errors, risks, alternatives, or non-goals
    
    Complete when every required placeholder in the selected template has either source material or an
    explicit `TBD`/question for the user.
    
    ### 4. Draft for use, review, or decision
    
    Lead with what the reader needs first. Show before explaining when the reader must do something;
    state the decision or proposal before deep rationale when the reader must decide.
    
    Complete when:
    
    - the opening answers the reader job
    - every section exists to help the reader do, decide, or understand something
    - examples are realistic and include required setup/config/error handling when relevant
    - uncertainties are marked instead of invented
    
    ### 5. Run the quality gate
    
    Before delivering, verify:
    
    - [ ] First sentence says what this is or what decision/proposal is being made
    - [ ] Code examples or commands were run when an environment is available; otherwise marked unverified
    - [ ] Required config, inputs, env vars, and permissions are documented
    - [ ] Common errors or risks include what to do next
    - [ ] Links referenced in the doc were checked when accessible
    - [ ] Terminology is consistent: one name per concept
    - [ ] No "simple" / "just" / "easy" for user actions
    
    Complete when all applicable checks pass or failures are called out explicitly.
    
    ## References
    
    | Priority | Load when | Reference |
    | --- | --- | --- |
    | 1 | Decision already made; capture context, decision, and consequences | `references/adr-template.md` |
    | 1 | Change not decided; solicit review, including system design with migration concerns | `references/rfc-template.md` |
    | 1 | Scoping new product work with goals, non-goals, user stories, and metrics | `references/design-doc-template.md` |
    | 2 | Creating or revising a README | `references/readme-guide.md` |
    | 2 | Creating or revising API documentation | `references/api-docs-guide.md` |
    | 2 | Creating or revising a task-oriented how-to guide | `references/how-to-guide.md` |
    | 3 | Technical prose needs sentence-level clarity work: reader-mode boundaries, condition/action order, common-path ordering, technical names, link text, modifier scope, or list introductions | `references/technical-style.md` |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.