@maestria/codex 0.2.0

package/skills/writer/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: writer
+description: Structured documentation workflow for READMEs, API docs, architecture documents, changelogs, and decision records.
+---
+
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+You write documentation.
+
+## Structure
+
+1. **Purpose** - Why this exists (not what it does)
+2. **Usage** - How to use it (quickstart, examples)
+3. **Details** - How it works (optional, for deeper understanding)
+
+## Principles
+
+- Platform guarantees must be checked against the adapter; do not invent isolation or lifecycle enforcement.
+
+- Write for humans - clear over clever
+- Complete over concise (but don't repeat yourself)
+- Use code examples liberally
+- Follow the project's existing doc style
+- One concept per section
+- Document guard rails and constraints explicitly
+
+## Format
+
+- Use tables for lists; group under section headers
+- Keep descriptions concise - one line
+- Match tone of surrounding docs
+- Progressive disclosure: high-level first, details on demand
+
+## Document Patterns
+
+### README
+
+- Purpose, quickstart, installation, setup
+- Usage examples, config options, links to detailed docs
+
+### API Documentation
+
+- Endpoint/purpose, request/response format
+- Error codes and handling, example calls, auth requirements
+
+### Architecture Decision Records (ADRs)
+
+- Context/problem, decision/rationale
+- Consequences (positive and negative), alternatives, status
+
+### Changelogs
+
+- Version, date, categories (added/changed/deprecated/removed/fixed/security)
+- Issue/PR links, migration notes for breaking changes
+
+## Check
+
+- **Termination condition:** links checked, examples runnable, tone matches docs, proofread once.
+- **!!! Mandatory Proofread** - verify links, examples runnable, tone matches style.
+- **!!! Scope Ambiguity → Document Assumption** - document with rationale; `$maestria:reviewer` validates.
+
+- **Parallelization:** writer tasks on different docs can run in parallel. Same doc is single-writer.
+
+## Skill Prescription
+
+### Always load
+
+- `writing-clearly-and-concisely` - clear prose for all writing
+- `humanizer` - remove AI writing markers
+
+### Load on trigger
+
+- `backend-to-frontend-handoff-docs` - API docs for frontend
+- `brand-guidelines` - brand/style guide docs
+- `copy-editing` - in-place copy editing
+- `crafting-effective-readmes` - README creation
+- `doc-coauthoring` - collaborative writing
+- `docx` - `.docx` generation
+- `domain-modeling` - domain glossary/ubiquitous language
+- `frontend-to-backend-requirements` - frontend data requirements
+- `pdf` - `.pdf` generation
+- `pptx` - slide deck creation
+- `writing-great-skills` - SKILL.md creation/editing
+- `xlsx` - spreadsheet creation
+
+### Defer to specialist
+
+- `internal-comms` → out of scope - not code/doc work
+- `professional-communication` → out of scope - emails/messaging
+- `template-skill` → out of scope - skill creation workflow
+- `skill-creator` → out of scope - skill creation workflow
+- `copywriting` → out of scope - marketing copy
+
+### Skip if
+
+- Output is short prose (1-paragraph note); no skill load needed
+- User wants a quick rewrite, not a full document