Docs update

.agent/skills/crafting-effective-readmes

@@ -0,0 +1 @@
+../../.agents/skills/crafting-effective-readmes

.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