# Doc Coauthoring

> Doc Co-Authoring

- Skill: `mediar-ai/doc-coauthoring` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add mediar-ai/doc-coauthoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mediar-ai/doc-coauthoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mediar-ai (https://skillmd.com/u/mediar-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mediar-ai/doc-coauthoring

---

# Doc Co-Authoring

Structured workflow for co-authoring documentation including proposals, technical specs, decision docs, and similar content. Three stages: Context Gathering, Refinement & Structure, and Reader Testing.

## Prerequisites

- Clear understanding of document purpose
- Access to relevant context (channels, docs, stakeholders)
- Time for iterative refinement

## Instructions

### Stage 1: Context Gathering

1. **Ask Initial Questions**
   - What type of document? (technical spec, decision doc, proposal)
   - Who's the primary audience?
   - What's the desired impact?
   - Any template or format to follow?

2. **Encourage Info Dumping**
   - Background on project/problem
   - Related team discussions
   - Why alternatives aren't being used
   - Timeline pressures or constraints

3. **Ask Clarifying Questions**
   - Generate 5-10 questions based on gaps
   - Allow shorthand answers

### Stage 2: Refinement & Structure

1. **For Each Section:**
   - Ask clarifying questions about content
   - Brainstorm 5-20 options
   - User curates (keep/remove/combine)
   - Draft the section
   - Iterate with surgical edits

2. **Use `str_replace` for edits** - never reprint whole doc

3. **Quality Check** - After 3 iterations, ask if anything can be removed

### Stage 3: Reader Testing

1. **Predict Reader Questions** (5-10 questions)
2. **Test with Fresh Context** - no context bleed
3. **Check for:**
   - Ambiguity or unclear sections
   - Assumed knowledge
   - Internal contradictions
4. **Fix gaps** found during testing

## Error Handling

- If user wants to skip a stage, allow freeform work
- If context is missing, proactively ask
- Address gaps as they come up, don't accumulate

## Notes

- Quality over speed
- Each iteration should make meaningful improvements
- Goal: document that actually works for readers

Source: anthropics/skills