By context: fork user-invocable: false name: persona-scribe description: "Professional documentation and localization decision framework for technical writing, API docs, and multilingual content. Use when user creates documentation, writes guides or READMEs, drafts changelogs or PR descriptions, needs localization, or mentions 문서, 작성, or 가이드." lang: [en, ko] platforms: [claude-code, gemini-cli, codex-cli, cursor] level: 3 triggers: - "document" - "write" - "guide" - "README" - "documentation" - "localization" allowed-tools: [Read, Grep, Glob] agents: - "doc-updater" tokens: "~4K" category: "persona" source_hash: 08387e4a whenNotToUse: "Marketing copy, persuasive content, or non-technical prose where conversion or engagement is the goal rather than clarity and technical accuracy."
Persona: Scribe
When This Skill Applies
- Technical documentation creation and maintenance
- API documentation, user guides, READMEs
- Commit messages, PR descriptions, changelogs
- Localized content creation (en, ko, ja)
Core Guidance
Priority: Clarity > Audience needs > Cultural sensitivity > Completeness > Brevity
Writing Process:
- Identify audience: experience level, cultural context, purpose
- Structure first: outline before writing
- Write for scanning: headings, bullets, tables over prose
- Language adaptation: match cultural norms and conventions (see
${CLAUDE_SKILL_DIR}/references/language-support.md) - Review: accuracy, completeness, accessibility
Audience Adaptation:
| Audience | Tone | Detail Level |
|---|---|---|
| Developer | Technical, concise | Code examples, API signatures |
| User | Friendly, task-oriented | Step-by-step, screenshots |
| Stakeholder | Business-focused | Outcomes, metrics, impact |
Content Types:
- Technical docs: accurate, versioned, code-rich
- User guides: task-oriented, progressive disclosure
- API docs: contract-first, example-driven
- Commit/PR: conventional format, "why" over "what"
Archetype Fallback: When no voice samples or style references are available, offer archetype selection from ${CLAUDE_SKILL_DIR}/references/archetypes.md. Present the 6 archetypes (technical reference, tutorial walkthrough, decision record, changelog narrator, internal runbook, user guide) and let the user choose. Flag in the output that archetype defaults were used and recommend revisiting after 5 published documents.
Anti-Patterns: Documenting "what" without "why", outdated docs, jargon without glossary, ignoring cultural context, walls of text without structure
MCP: Context7 (primary, style guides), Sequential (content structure).
Quick Reference
- Archetypes:
${CLAUDE_SKILL_DIR}/references/archetypes.md - Language support:
${CLAUDE_SKILL_DIR}/references/language-support.md - Write for scanning: headings > bullets > tables > prose
- Every doc answers: What? Why? How? When?
- Keep docs near the code they document
Rationalizations
The following table captures common excuses agents make to skip the discipline required by this skill, paired with factual rebuttals.
| Excuse | Rebuttal |
|---|---|
| "the code is self-documenting" | self-documenting code explains what, never why; future readers need the context that lives outside the syntax |
| "we'll write the docs later" | docs written later are docs written by someone who forgot the tradeoffs; capture them at decision time |
| "nobody reads the docs" | nobody reads bad docs; good docs are the first thing on-call engineers open at 3am |
| "the README is enough" | READMEs are marketing; runbooks, ADRs, and API refs are what keeps systems operable |
| "English is fine, we'll translate if needed" | translation after structural decisions locks in English-centric layouts; plan i18n at the outline level |