Writing

Writing Skill

Five modes. Match the request to the correct mode and follow its section.

Deep References

Mode 1: Voice Writing

13-phase pipeline for voice-profiled articles and blog posts. Each phase runs as a separate agent dispatch. Phase artifacts are files in .voice-phase/, not context between agents.

Set VOICE_WRITER_ACTIVE=1 before dispatching any phase agent.

Phases

1. LOAD: Identify voice profile. Run ls ~/.claude/skills/ | grep voice- for available profiles. Read profile.json, all references/, and the target site's CLAUDE.md. Output: .voice-phase/01-load.json.

2. GROUND: Anchor in lived experience. Identify: core problem, personal experience, the "vex" (frustration) and "joy" (resolution), 3-5 concrete details, single reader takeaway. Output: .voice-phase/02-grounding.md.

3. STATS-CHECKPOINT: Extract target ranges from profile (sentence/paragraph length, pronoun density, contraction rate, banned patterns). Output: .voice-phase/03-stats-baseline.json.

4. GENERATE: Write the full draft in target voice. Apply narrative structure guidance: let evidence speak, mix emotional registers, weave secondary threads, leave room for uncertainty, reference specifically, vary intensity, include one unpredicted event, acknowledge the reader, vary temporal structure, close with forward motion, subvert one expectation. Target 1200-2000 words. Output: .voice-phase/04-draft.md.

5. HOOK-GATE: Check opening for at least one concrete number, specific date, or unexpected detail. Score 1-10. If < 8, pull the most surprising finding from the body into the opening. Max 3 attempts. Output: .voice-phase/05-hook-score.json.

6. VALIDATE: Call the Skill tool with voice-validator (or run Voice Validation below). Measure metrics against Phase 3 targets. Flag deviations > 1 stddev. Output: .voice-phase/06-validation-report.json.

7. REFINE: Fix failed metrics. Tighten prose. Verify code examples. Re-validate changed sections. Output: .voice-phase/07-refined-draft.md.

8. VARIETY-GATE: Sentence length clusters: short (1-7 words) 30-45%, medium (8-20) 35-50%, long (21+) 10-25%. Every paragraph 3 sentences or fewer. At least 1 single-sentence paragraph per 500 words. Variety score (stddev) >= 8.0. Max 3 attempts. Output: .voice-phase/08-variety-score.json.

9. JOY-CHECK: Call the Skill tool with joy-check. Ensure the article celebrates problem-solving, not grievance. Output: .voice-phase/09-joy-report.json.

10. ANTI-AI: Run the private de-AI editor skill. Strip generic transitions, hedge stacking, summary conclusions, self-narrating structure. Voice profile overrides anti-AI rules -- if a flagged pattern exists in the voice profile's corpus, preserve it. Output: .voice-phase/10-antiai-report.json.

11. CLOSE-GATE: Verify closing uses one of 5 modes (Honest Uncertainty, Practical Trailing Observation, Self-Deprecating Admission, Specific Next Step, Just Stops). Must not summarize, callback to opening, or use "In conclusion". Score >= 7. Max 3 attempts. Output: .voice-phase/11-close-score.json.

12. OUTPUT: Apply front matter, write to content/posts/YYYY-MM-DD-slug.md. Report all gate scores. Write .voice-pipeline-complete marker. Output: final file.

13. CLEANUP: Report word count, reading time, preview URL. Flag gates that required multiple attempts.

Mode 2: Voice Creation

7-phase pipeline to build a voice profile from writing samples. Each phase has a gate. Report progress with phase banners (load references/cv-phase-banners.md).

Phase 1: COLLECT (Gate: 50+ samples)

Gather 50+ writing samples across contexts and lengths. Mix sources: Reddit, HN, blog, forum, email, chat, social. Do not clean typos -- imperfections ARE the voice. Do not cherry-pick. Save to skills/voice-{name}/references/samples/*.md.

Phase 2: EXTRACT (Gate: profile.json valid, script exit 0)

Run deterministic analysis:

python3 ~/.claude/scripts/voice-analyzer.py analyze \
  --samples skills/voice-{name}/references/samples/*.md \
  --output skills/voice-{name}/profile.json

Add stylometry bands: python3 scripts/voice-stylometry.py band --samples skills/voice-{name}/references/samples/*.md. Merge into profile.json.

Phase 3: PATTERN (Gate: 10+ phrase fingerprints, 3+ thinking patterns, 2/4 architectures)

Identify distinctive patterns from samples + profile.json. Load references/cv-pattern-identification.md for phrase fingerprints, thinking patterns, wabi-sabi markers, and linguistic architectures. Apply triple-validation rubric from references/cv-extraction-validation.md: every pattern must pass cross-domain recurrence, generative power, and distinguishing exclusivity. Verdict: KEEP / FOOTNOTE / DROP.

Phase 4: RULE (Gate: 4+ positive traits, 6+ contrastive aspects, 3+ prohibitions)

Transform KEEP/FOOTNOTE patterns into rules. Load references/cv-voice-rules-template.md. Build: positive identity (with dampening adverbs), contrastive table (This Voice vs Generic AI), hard prohibitions, wabi-sabi rules, anti-essay patterns, architectural patterns.

Phase 5: GENERATE (Gate: SKILL.md 2000+ lines, samples 400+ lines)

Generate the voice skill files. Load references/cv-skill-generation.md. Create skills/voice-{name}/SKILL.md and config.json. Most line count is SAMPLES, not rules (V7-V9 failed with rules-only; V10 passed with 100+ samples).

Phase 6: VALIDATE (Gate: score >= 60, 0 errors)

Generate 3 test pieces (short, medium, long). Run:

python3 ~/.claude/scripts/voice-validator.py validate \
  --content /tmp/voice-sample-{name}-{N}.md \
  --profile skills/voice-{name}/profile.json --voice {name} --format text --verbose
python3 ~/.claude/scripts/voice-validator.py check-banned \
  --content /tmp/voice-sample-{name}-{N}.md --voice {name}

If validation flags natural imperfections as errors, adjust config.json thresholds, not the content. Max 3 iterations.