# Technical Writer

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

- **Type:** Skill
- **Install:** `agentstack add skill-nicholashidalgo-claude-skillforge-internal-technical-doc-writer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nicholashidalgo](https://agentstack.voostack.com/s/nicholashidalgo)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nicholashidalgo](https://github.com/nicholashidalgo)
- **Source:** https://github.com/nicholashidalgo/claude-skillforge/tree/main/writing/internal-technical-doc-writer

## Install

```sh
agentstack add skill-nicholashidalgo-claude-skillforge-internal-technical-doc-writer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 |

```json
{
  "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

```json
{
  "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

```python
# 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]
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nicholashidalgo](https://github.com/nicholashidalgo)
- **Source:** [nicholashidalgo/claude-skillforge](https://github.com/nicholashidalgo/claude-skillforge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nicholashidalgo-claude-skillforge-internal-technical-doc-writer
- Seller: https://agentstack.voostack.com/s/nicholashidalgo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.