feat: mutation-flow composition hook (lighter alternative to PR #81)

.agents/skills/crafting-effective-readmes/README.md

@@ -0,0 +1,180 @@
+# Crafting Effective READMEs
+
+A skill for Claude Code that helps you write, update, and improve README files tailored to your specific project type and audience.
+
+## Purpose
+
+Not all READMEs are the same. An open-source library needs different documentation than a personal project or an internal tool. This skill provides:
+
+- **Audience-aware guidance** - Different readers need different information
+- **Project-type templates** - Ready-to-use structures for OSS, personal, internal, and config projects
+- **Task-specific workflows** - Whether creating, updating, adding to, or reviewing READMEs
+- **Quality checks** - Style guidance and section checklists to avoid common mistakes
+
+## When to Use
+
+Use this skill when you need to:
+
+- Create a README for a new project
+- Add a new section to an existing README
+- Update stale documentation after changes
+- Review and refresh README content
+- Choose the right sections for your project type
+
+**Trigger phrases:**
+
+- "Write a README for this project"
+- "Help me document this"
+- "Create documentation for..."
+- "Update the README"
+- "Review my README"
+- "What sections should my README have?"
+
+## How It Works
+
+The skill follows a three-step process:
+
+### Step 1: Identify the Task
+
+The skill determines what README task you are working on:
+
+| Task | When to Use |
+|------|-------------|
+| **Creating** | New project with no README yet |
+| **Adding** | Need to document something new in existing README |
+| **Updating** | Capabilities changed, content is stale |
+| **Reviewing** | Checking if README is still accurate |
+
+### Step 2: Gather Context
+
+Based on the task, the skill asks targeted questions:
+
+- **Creating**: What type of project? What problem does it solve? What is the quickest path to "it works"?
+- **Adding**: What needs documenting? Where should it go? Who needs this info most?
+- **Updating**: What changed? Which sections are stale?
+- **Reviewing**: Compares README against actual project state (package.json, main files, etc.)
+
+### Step 3: Generate and Refine
+
+The skill uses the appropriate template and follows up with: "Anything else to highlight or include that I might have missed?"
+
+## Key Features
+
+### Project Type Templates
+
+| Type | Audience | Template |
+|------|----------|----------|
+| **Open Source** | Contributors, users worldwide | `templates/oss.md` |
+| **Personal** | Future you, portfolio viewers | `templates/personal.md` |
+| **Internal** | Teammates, new hires | `templates/internal.md` |
+| **Config** | Future you (confused) | `templates/xdg-config.md` |
+
+### Section Checklist by Project Type
+
+| Section | OSS | Personal | Internal | Config |
+|---------|-----|----------|----------|--------|
+| Name/Description | Yes | Yes | Yes | Yes |
+| Badges | Yes | Optional | No | No |
+| Installation | Yes | Yes | Yes | No |
+| Usage/Examples | Yes | Yes | Yes | Brief |
+| What's Here | No | No | No | Yes |
+| How to Extend | No | No | Optional | Yes |
+| Contributing | Yes | Optional | Yes | No |
+| License | Yes | Optional | No | No |
+| Architecture | Optional | No | Yes | No |
+| Gotchas/Notes | Optional | Optional | Yes | Yes |
+| Last Reviewed | No | No | Optional | Yes |
+
+### Reference Materials
+
+The skill includes curated reference materials for deeper understanding:
+
+- **art-of-readme.md** - Philosophy behind great READMEs, cognitive funneling
+- **make-a-readme.md** - Practical, section-by-section guidance
+- **standard-readme-spec.md** - Formal specification for OSS consistency
+
+## Usage Examples
+
+### Creating a New README
+
+```
+User: I need a README for my new CLI tool
+
+Claude: What type of project is this - open source, personal, or internal?
+
+User: Open source, it's a Node.js package
+
+Claude: [Uses OSS template, asks about installation, usage, and contributing]
+```
+
+### Updating an Existing README
+
+```
+User: Update my README, I added a new feature
+
+Claude: [Reads current README, identifies where to add the new feature,
+        proposes specific edits]
+```
+
+### Reviewing for Accuracy
+
+```
+User: Check if my README is still accurate
+
+Claude: [Compares README against package.json, main files, etc.
+        Flags outdated sections and suggests updates]
+```
+
+## Best Practices
+
+1. **Always ask about audience** - Don't assume OSS defaults for everything
+2. **Show, don't just tell** - Include examples and code samples
+3. **Use structure** - Headers, tables, and lists improve scannability
+4. **Keep it current** - Add "last reviewed" dates for internal/config projects
+5. **Include installation steps** - Never assume setup is obvious
+6. **Write for YOUR audience** - Avoid generic tone
+
+## Common Mistakes to Avoid
+
+- No installation steps (never assume setup is obvious)
+- No examples (show, don't just tell)
+- Wall of text (use headers, tables, lists)
+- Stale content (add "last reviewed" date)
+- Generic tone (write for YOUR audience)
+
+## Essential Sections (All Types)
+
+Every README needs at minimum:
+
+1. **Name** - Self-explanatory title
+2. **Description** - What + why in 1-2 sentences
+3. **Usage** - How to use it (examples help)
+
+## Directory Structure
+
+```
+crafting-effective-readmes/
+  SKILL.md                 # Skill definition
+  section-checklist.md     # Quick reference for sections by project type
+  style-guide.md           # Common mistakes and prose guidance
+  using-references.md      # Guide to reference materials
+  templates/
+    oss.md                 # Open source project template
+    personal.md            # Personal/portfolio project template
+    internal.md            # Internal/team project template
+    xdg-config.md          # Configuration directory template
+  references/
+    art-of-readme.md       # README philosophy
+    make-a-readme.md       # Section-by-section guidance
+    standard-readme-spec.md        # Formal specification
+    standard-readme-example-minimal.md  # Minimal compliant example
+    standard-readme-example-maximal.md  # Full-featured example
+```
+
+## Related Skills
+
+- `writing-clearly-and-concisely` - For general prose quality, clear writing, and avoiding AI patterns
+
+## Attribution
+
+- Original skill by @joshuadavidthomas from [joshuadavidthomas/agent-skills](https://github.com/joshuadavidthomas/agent-skills) (MIT)

.agents/skills/crafting-effective-readmes/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: crafting-effective-readmes
+description: Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
+---
+
+# Crafting Effective READMEs
+
+## Overview
+
+READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
+
+**Always ask:** Who will read this, and what do they need to know?
+
+## Process
+
+### Step 1: Identify the Task
+
+**Ask:** "What README task are you working on?"
+
+| Task | When |
+|------|------|
+| **Creating** | New project, no README yet |
+| **Adding** | Need to document something new |
+| **Updating** | Capabilities changed, content is stale |
+| **Reviewing** | Checking if README is still accurate |
+
+### Step 2: Task-Specific Questions
+
+**Creating initial README:**
+1. What type of project? (see Project Types below)
+2. What problem does this solve in one sentence?
+3. What's the quickest path to "it works"?
+4. Anything notable to highlight?
+
+**Adding a section:**
+1. What needs documenting?
+2. Where should it go in the existing structure?
+3. Who needs this info most?
+
+**Updating existing content:**
+1. What changed?
+2. Read current README, identify stale sections
+3. Propose specific edits
+
+**Reviewing/refreshing:**
+1. Read current README
+2. Check against actual project state (package.json, main files, etc.)
+3. Flag outdated sections
+4. Update "Last reviewed" date if present
+
+### Step 3: Always Ask
+
+After drafting, ask: **"Anything else to highlight or include that I might have missed?"**
+
+## Project Types
+
+| Type | Audience | Key Sections | Template |
+|------|----------|--------------|----------|
+| **Open Source** | Contributors, users worldwide | Install, Usage, Contributing, License | `templates/oss.md` |
+| **Personal** | Future you, portfolio viewers | What it does, Tech stack, Learnings | `templates/personal.md` |
+| **Internal** | Teammates, new hires | Setup, Architecture, Runbooks | `templates/internal.md` |
+| **Config** | Future you (confused) | What's here, Why, How to extend, Gotchas | `templates/xdg-config.md` |
+
+**Ask the user** if unclear. Don't assume OSS defaults for everything.
+
+## Essential Sections (All Types)
+
+Every README needs at minimum:
+
+1. **Name** - Self-explanatory title
+2. **Description** - What + why in 1-2 sentences  
+3. **Usage** - How to use it (examples help)
+
+## References
+
+- `section-checklist.md` - Which sections to include by project type
+- `style-guide.md` - Common README mistakes and prose guidance
+- `using-references.md` - Guide to deeper reference materials