| name | core-writing |
| description | Activate when the turn produces substantial prose — docs, copy, proposals, feedback, commit/PR text, or UI strings. Includes documents that record technical work: an ADR, RFC, design doc, postmortem, or migration guide is a written deliverable and needs this alongside whichever skill covers its subject. Provides copywriting frameworks, tone guidance, and an editing workflow. |
| 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
- A structure named in the request overrides every default below. If the ask specifies sections, an order, heading levels, a per-item element ("a before/after code block for each change"), or a closing element ("end with the upgrade command"), that list is the spec. Write it down as a checklist before drafting, and keep the request's own wording and order — do not re-title, re-order, merge, or "improve" the sections.
- 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, Read the file back — check the bytes on disk, not the draft in your head:
- Is every section the request named present, at the named heading level, in the named order?
- Does every per-item requirement hold for every item (all N changes have their code block, all N options have their trade-off)? "Most of them" is a failure.
- Is the closing element there (checklist, command, next step) if one was asked for?
- 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?
