{
  "$schema": "https://humangarden.ai/.well-known/skill-spec.schema.json",
  "canonical_url": "https://humangarden.ai/skills/doc-coauthoring/spec.json",
  "slug": "doc-coauthoring",
  "last_tested": "2026-06-05",
  "tested_by": "humangarden",
  "verdict_one_line": "prompt-only workflow (no code, no install) — a tight three-stage protocol that earns its overhead on substantive docs and silently wastes time on thin ones; Reader Testing via subagents is the real differentiator",
  "fires_when": [
    "user wants to draft a decision doc, RFC, PRD, technical spec, design doc, or proposal",
    "user mentions \"write a doc\", \"draft a proposal\", \"create a spec\", \"write up\"",
    "skill author or PM is starting a substantive piece of writing where blind spots will be costly",
    "user has rich context to transfer and wants Claude to interview them out of it",
    "user has access to subagents (Claude Code) and wants a fresh-Claude reader test before sending the doc"
  ],
  "skip_when": [
    "user just wants a short-form doc, a quick template, or one-shot prose (workflow overhead exceeds value)",
    "user has no substantive context to transfer (\"write me a generic doc\") — Stage 1 has no documented short-circuit and will burn turns before it figures this out",
    "user is in a runtime with no artifact/file write surface AND no markdown working directory (the \"create the scaffold\" branches both assume one or the other)",
    "reader-testing the doc with a fresh Claude is the explicit non-goal (e.g. the doc is private or contains secrets that should not enter a subagent context)"
  ],
  "inputs": [
    {
      "type": "prompt",
      "format": "natural-language",
      "constraint": "an opening request to write a doc + iterative chat for context-gathering, brainstorming, curation, and refinement"
    },
    {
      "type": "text",
      "format": "info-dump",
      "constraint": "user's raw context (background, history, politics, constraints, related threads); pasted prose, no schema required"
    },
    {
      "type": "file",
      "format": "template",
      "constraint": "optional — an existing doc template the user wants to follow (workflow uses it to skip the \"suggest sections\" branch in Stage 2)"
    }
  ],
  "outputs": [
    {
      "type": "file",
      "format": "markdown",
      "quality_note": "a multi-section document built section-by-section with explicit clarify → brainstorm → curate → draft → refine cycles; in our run produced a 1,950-word decision doc with sharper structure than a one-shot prompt would have given"
    },
    {
      "type": "text",
      "format": "reader-test-findings",
      "quality_note": "when subagents are available (Claude Code), Stage 3 produces a real gap report from a fresh-Claude read of the finished doc — in our run it caught 3 gaps the author hadn't noticed (missing DRI, undefined acronym, vague analytics migration plan)"
    }
  ],
  "installation": {
    "pip": [],
    "npm": [],
    "system": {
      "notes": "Nothing to install. This skill is a prompt-only workflow — a SKILL.md the agent reads and follows. The only 'runtime requirement' is the host being able to write markdown files (or render artifacts) for the section-by-section drafting loop, and ideally subagent access for Stage 3."
    },
    "notes": "No requirements.txt, no scripts, no fixtures. The entire skill is one ~16 KB SKILL.md. Capability gating is documented inline ('If access to artifacts is available...' / 'If access to sub-agents is available...') — Claude Code gets the full experience; claude.ai web gets a manual variant of Stage 3."
  },
  "artifacts": [
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/doc-coauthoring/before-user-context-dump.md",
      "caption": "BEFORE — the user's opening prompt, answers to Stage 1's five meta-questions, and the raw info dump that the workflow turned into a structured doc",
      "role": "input",
      "hero": true
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/doc-coauthoring/after-final-doc.md",
      "caption": "AFTER — the finished decision doc (1,950 words). Built section-by-section through 5 brainstorm/curate/draft/refine cycles + a subagent reader-test pass",
      "role": "output",
      "hero": true
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/doc-coauthoring/transcript.txt",
      "caption": "Full ~51-minute workflow transcript — every stage, every brainstorm list, every str_replace edit, the 7-question subagent reader test, and the 3 gaps it caught",
      "role": "reference",
      "hero": false
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/doc-coauthoring/prompt.txt",
      "caption": "The opening user message that triggered the workflow — matches the \"write a doc / decision doc\" trigger phrase",
      "role": "input",
      "hero": false
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/doc-coauthoring/edge-case-thin-prompt.txt",
      "caption": "Edge-case probe — \"write me a doc\" with no real context. Workflow has no documented short-circuit; spends 6 minutes of Q&A to produce a generic template that a one-shot prompt would have given in 3 seconds",
      "role": "reference",
      "hero": false
    }
  ],
  "caveats": [
    "no install at all — the skill is a SKILL.md and nothing else. Good (zero deps) but means there is also nothing to lint, no version pin, no schema check; the workflow lives or dies on the agent following it faithfully",
    "Stage 1 has no documented exit branch for \"user has no substantive context to transfer.\" On thin prompts (\"write me a doc\") the workflow loops through 5 meta-questions, an info-dump request, and 5-10 clarifying questions before producing a generic template — high overhead with no payoff. SKILL.md should add an early-exit detector",
    "Stage 3 (Reader Testing) is gated on subagent access. In Claude Code it runs automatically and is the most valuable piece of the workflow — in our run it surfaced 3 real gaps the author had missed. On claude.ai the user must do it manually by opening a fresh chat, which most users will skip",
    "the \"use create_file / use str_replace\" guidance assumes a host that exposes those tools as artifact primitives; in environments that only have raw file I/O the workflow still works but the \"provide artifact link after every change\" instructions become no-ops",
    "no integrations were available in our run (no Slack/Drive MCP). The SKILL.md branches for those cases (cleanly), but the linked threads and prior RFCs the user mentioned could not be pulled in, only described — a real loss of fidelity. The skill correctly nudges the user to enable connectors but cannot itself install them",
    "no token / latency cost guidance. A full run is ~50 minutes of chat and probably 30-60k input tokens by the time Reader Testing finishes. For short docs that ratio is bad; SKILL.md should warn users to use the workflow for docs that will be read by more than one person",
    "\"never reprint the whole doc\" / \"always use str_replace\" is good guidance but unenforced — an agent that ignores it will burn context fast on long docs without anything in the skill catching the regression"
  ],
  "needs_credentials": [],
  "source_repo": "https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring",
  "human_review_url": "https://humangarden.ai/skills/doc-coauthoring/"
}