Internal technical doc writer

Skill nicholashidalgo/claude-skillforge/writing/internal-technical-doc-writer

Install

npx -y skills add nicholashidalgo/claude-skillforge --skill internal-technical-doc-writer

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Writes and edits technical documentation: READMEs, runbooks, ADRs, and API docs. Enforces plain language and factual precision.

SKILL.md

3.6 KB, as published. Nobody here has run it

technical-writer

Purpose: Transform rough technical notes or verbose AI-generated drafts into clear, scannable technical documentation.

Input Schema

Field	Type	Required
`doc_type`	string	yes - readme, runbook, adr, api-doc, design-doc
`content`	string	yes - raw notes or draft
`preserve_facts`	string[]	yes
`audience`	string	yes - e.g., "on-call engineers", "external API consumers"
`tone`	string	yes

{
  "doc_type": "runbook",
  "content": "When the service goes down you should check the logs and then maybe restart it. The service is very important and serves as a critical component in our infrastructure.",
  "preserve_facts": ["service name: payment-processor", "restart command: systemctl restart payment-processor"],
  "audience": "on-call engineers",
  "tone": "direct"
}

Output Schema

{
  "title": "Runbook: payment-processor",
  "sections": {
    "symptoms": "...",
    "diagnosis": "...",
    "resolution": "...",
    "escalation": "..."
  },
  "patterns_removed": [1, 7, 8, 14],
  "word_count": 120
}

Prompt Flow

Pass 1: Rewrite into appropriate doc structure for doc_type. Remove: significance inflation (P1), promotional adjectives (P4), AI vocab (P7), copula avoidance (P8), boldface overuse (P14), inline-header lists (P15), filler (P22). Preserve preserve_facts.

Pass 2 Audit + Final: Check for any remaining vague attributions (P5) or -ing tail clauses (P3). Rewrite to specific and direct.

Examples

Short - runbook symptom

Before: "The service serves as a critical component and may be experiencing issues that could potentially be causing downstream impact." After: "Symptom: payment-processor is returning 5xx. Downstream: checkout is blocked."

Medium - README section

Before: "This groundbreaking tool boasts the ability to leverage cutting-edge algorithms to enhance developer productivity." After: "This tool reduces CI build time by parallelizing your test suite. It requires Python 3.11+ and a Redis instance."

Long - ADR

Before: "We have decided to utilize a microservices architecture, underscoring its vital role in our evolving landscape and highlighting its significance for long-term scalability, cultivating a foundation for future growth." After: "Decision: adopt a microservices architecture for the billing domain.\nContext: the monolith's deploy cycle is 2 hours; billing changes block all other deploys.\nConsequences: services will communicate over gRPC; the team needs observability tooling."

Unit Tests

# tests/skills/test_technical_writer.py
from ai_pattern_scrubber import detect_patterns

SHORT = "Symptom: payment-processor is returning 5xx. Downstream: checkout is blocked."
MEDIUM = "This tool reduces CI build time by parallelizing your test suite. It requires Python 3.11+ and a Redis instance."

def test_tech_short_no_high_severity():
    assert not [h for h in detect_patterns(SHORT) if h.severity == "high"]

def test_tech_medium_no_promotional_language():
    assert not [h for h in detect_patterns(MEDIUM) if h.id == 4]

def test_tech_medium_no_ai_vocab():
    assert not [h for h in detect_patterns(MEDIUM) if h.id == 7]