core-writing

name	core-writing
description	Activate when the turn's deliverable is substantial prose — docs, copy, proposals, feedback, commit/PR text, or UI strings. Provides copywriting frameworks, tone guidance, and editing workflow for clear, persuasive, polished output.
user-invocable	false

Skill: core-writing

Follow Brief → Structure → Draft → Polish for every writing task.

Companion Templates

When the current task matches a trigger below, Read the named companion from this skill's directory (path provided in the activation header). Companions are not pre-loaded — pull them on demand.

Trigger	Companion
Writing or rewriting a project README	templates/readme.md
Drafting a git commit message	templates/commit-message.md
Documenting a function, endpoint, or CLI command	templates/api-doc.md

Workflow

1. Brief & Audience

• Who is reading this? What do they already know? What do they need to know?
• What outcome should this writing achieve?
• What tone fits: technical, persuasive, instructional, conversational?

2. Structure & Outline

• Technical docs: Problem → Solution → Usage → API → Examples
• Persuasive writing: Hook → Context → Evidence → Resolution → CTA
• Instructional: Goal → Prerequisites → Steps → Verification → Troubleshooting
• One idea per paragraph. Lead with the conclusion. Use transitions.

3. Draft

• Write freely. Don't edit while drafting.
• Apply the chosen structure. Fill in evidence and examples.
• Use active voice. Be specific over vague.

4. Polish & Edit

• Omit needless words. Every word must earn its place.
• Check flow: read aloud. Fix awkward transitions.
• Verify accuracy: facts, code samples, references.
• Proof: spelling, grammar, consistent terminology.

Copywriting Formulas

Formula	When to Use	Structure
AIDA	Marketing, proposals, feature announcements	Attention → Interest → Desire → Action
PAS	Bug reports, problem-solving docs	Problem → Agitate → Solution
Inverted Pyramid	News, announcements, summaries	Conclusion → Key details → Background
Before-After-Bridge	Change proposals, migration guides	Current → Desired → How to get there
FEBC	Technical decisions	Fact → Explanation → Benefit → Conclusion

Tone Matrix

Audience	Tone	Characteristics
Developers	Technical, precise	Specific terms, code examples, no fluff
Product managers	Outcome-oriented	Problem → impact → timeline → trade-offs
End users	Friendly, clear	Simple language, concrete examples, next steps
Executives	Concise, strategic	Recommendation first, TL;DR, business impact

Quality Checklist

Before finalizing:

• Does the first paragraph convey the main point?
• Can any sentence be shortened without losing meaning?
• Are all claims supported by evidence?
• Is the tone appropriate for the audience?
• Would this still make sense if read in isolation?