writing

name	writing
description	Document creation and proofreading based on Pyramid Principle + marginal utility. Supports both new creation and editing of existing text.
user-invocable	true

Writing Skill

Argument Parsing

Treat $ARGUMENTS as the task content. If omitted, use AskUserQuestion to prompt the user for input.

Template keywords: if $ARGUMENTS starts with dvq or rfc, load the corresponding template from ~/.claude/skills/writing/templates/ and use it as structural guidance in Step 1. Strip the keyword from the arguments before passing the remainder as the task content.

• dvq [topic] — strategic vision document (DVQ template)
• rfc [topic] — technical decision document (RFC template)

Preparation: Load Personas and Templates

Read the following 2 files using the Read tool:

1. ~/.claude/skills/writing/personas/document-writer.md - Writer persona
2. ~/.claude/skills/writing/personas/marginal-utility-editor.md - Editor persona

If a template keyword was detected, also read the matching template:

• ~/.claude/skills/writing/templates/dvq.md for dvq
• ~/.claude/skills/writing/templates/rfc.md for rfc

Japanese language gate: judge whether the prose you will write or edit is primarily Japanese (auto-detect from the task content / target document — English identifiers or code snippets inside a Japanese document still count as Japanese; skip for English documents). If Japanese, also read the AI-slop references:

• ~/.claude/skills/writing/references/phrases.md - banned vocabulary
• ~/.claude/skills/writing/references/structures.md - structural anti-patterns
• ~/.claude/skills/writing/references/examples.md - before/after contrast cases

Workflow

Execute 3 steps sequentially. Each step is delegated to an independent agent via the Agent tool.

Step 1: Plan (Structure Design)

Launch Agent tool (subagent_type: "general-purpose"):

• Persona: include document-writer content in the prompt
• Instructions:
  • Analyze the task and determine mode (new creation or proofreading)
  • If a template was loaded, use its structure as the starting point instead of designing from scratch
  • Identify the reader: who they are, what they already know, and what decision or action this document supports
  • Design structure based on Pyramid Principle: conclusion (1 sentence) → arguments (MECE-grouped) → evidence/data
  • Verify each argument answers "why?" or "how?" from the conclusion
  • Keep hierarchy to 3 levels or fewer
  • Decide document format (short / medium / long)

Step 2: Write (Drafting)

Launch Agent tool:

• Persona: include document-writer content in the prompt
• Pass the structure design from Step 1 as prior context
• Instructions:
  • Write the document following the structure design
  • State the conclusion first
  • Open each paragraph with a topic sentence
  • Use narrative prose (minimize bullet points)
  • Use concrete numbers and facts instead of adjectives and adverbs
  • Output the completed draft only

Step 3: Edit (Marginal Utility Editing)

Launch Agent tool:

• Persona: include marginal-utility-editor content in the prompt. If the document is Japanese, ALSO include the full contents of references/phrases.md, references/structures.md, and references/examples.md in the prompt — sub-agents do not share the orchestrator's Read cache, so these must be re-injected exactly like the persona, not merely read in Preparation.
• Pass the draft from Step 2
• Instructions:
  • Verify Pyramid Principle structure (conclusion first, topic sentences, MECE grouping, hierarchy depth)
  • Apply marginal utility test (evaluate each sentence's reason to exist against the intended reader)
  • Check expression (adjectives → numbers, passive → active voice, eliminate "you can"/"there is" padding)
  • Reader-level adaptation: if the identified reader is non-technical, flag every technical term that lacks a definition on first use
  • Scannability: no paragraph exceeds 5 sentences; headings contain the key conclusion word (not vague labels); parallel grammatical structure in any remaining lists
  • Japanese AI-Slop Check (Japanese documents only): apply the editor persona's ### 5. Japanese AI-Slop Check using the injected references. Run the 5-axis 採点 (立場/リズム/主体性/具体性/削減, 1–10, report EACH axis sub-score), then repair in priority order 立場→主体(false agency)→構造→語彙→記号 (fixing 記号 before 立場/主体 leaves the slop intact). Apply the cluster rule (a single isolated tell is not slop). Include the per-axis score table in the editing report.
  • Check information volume (body max 6 pages; excess to appendix)
  • Output editing report + edited draft

Step 3 Decision

If the editor determines "revision needed", return to Step 1 with the editor's feedback included. For Japanese documents, a 採点 total below 35/50 OR any single axis below 5/10 counts as "revision needed". Maximum 3 cycles. Upon reaching 3 cycles, output the best draft at that point as the final version.

Final Output

Present the editor-approved draft (or the final draft upon reaching 3 cycles) to the user.