Building a README with Claude Code Skills — Full Issue Lifecycle

# README Design Decisions (Issue #10)

## Q001: Should the root README be the single comprehensive document, or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md. The issue asks to "add meat" — but meat can live in one place or be distributed. This decides the overall information architecture and affects every other question.

Options:
A) Single comprehensive README - Everything in one scrollable document. Beginners don't have to click around. GitHub renders it on the landing page. Downside: could get long (200+ lines).
B) Hub-and-spoke - Root README covers intro, quick start, and philosophy. Link out to skills/README.md for reference and a new docs/workflows.md (or similar) for the advanced scenarios. Keeps each file focused.
C) Progressive disclosure in one file - Comprehensive README but with heavy use of GitHub's `<details>` collapse blocks so the page loads clean and users expand what interests them.

Recommendation: A - A single comprehensive README is the most welcoming. GitHub renders it on the landing page, so visitors see everything without navigating. The content we're planning (intro, quick start, workflow walkthrough, philosophy, reference) is substantial but not unwieldy — probably 300-400 lines. That's normal for a well-documented project. Collapsible sections (option C) can feel clunky and hide value.

A001:  A

---

## Q002: What tone and voice should the README use?

Context: Tone sets the first impression. This is a personal open-source project with real daily use — the voice should reflect that authenticity. It affects how welcoming beginners feel and how seriously advanced users take the content.

Options:
A) Casual and personal - First person ("I built these because..."), conversational, occasional humor. Feels like a blog post or a friend showing you their setup.
B) Professional but warm - Third person or "you"-focused ("These skills help you..."), clean and direct, no jokes but not stiff. Feels like well-written project docs.
C) Tutorial-style - Second person imperative ("Install the skills. Try this command. Notice how..."), teaching tone throughout. Feels like a workshop guide.

Recommendation: A - This is your personal toolkit, battle-tested over many iterations. Casual first-person voice makes it authentic and approachable. It also differentiates it from generic tool documentation — people connect with "here's what I actually use every day" more than impersonal docs.

A002:  A

---

## Q003: How should the "real workflow" scenario be presented?

Context: The scratchpad plan identifies a full issue lifecycle walkthrough as the centerpiece of the README. The issue itself asks for "redacted/safe prompts from my day-to-day." This question decides whether to use fabricated examples or adapt real ones.

Options:
A) Fabricated but realistic - Invent a plausible scenario (e.g., "add CSV export to a reporting tool") and walk through the full lifecycle with made-up but realistic commands and outputs. Easy to control, no redaction needed.
B) Redacted real examples - Take actual prompts and outputs from your daily use, redact proprietary details, and present them. More authentic but requires careful scrubbing.
C) Hybrid - Use a fabricated scenario for the main walkthrough but include a "From My Actual Usage" sidebar or section with short redacted real snippets showing specific moments (a particularly useful breadcrumb, a well-structured question file, a side-quest that saved time).

Recommendation: C - The fabricated walkthrough keeps the narrative clean and followable, while real snippets add credibility and show that these aren't theoretical tools. The real snippets can be short and focused — a 5-line excerpt from a breadcrumbs file, a question file showing how Q&A actually flows, etc.

A003: Option C sound appropriate. Could you build it from the current back-n-forth you and I are having in the current context ? Nothing sensitive here and noting to redact; we could transparently share our whole conversation. This would be a great "eat your own dog food" demo. In order to demo a more complete flow, we can leave https://github.com/couimet/my-claude-skills/issues/10 as bare as it got created and we'll build a full-cycle demo: use /scratchpad to build a draft for a GitHub issue to create, use /start-issue to kick the process off, use /tackle-scractchpad-block for the iterative commits, etc... We could also introduce an error on purpose and cross our fingers that https://coderabbit.ai/ will pick it up so we can demo out /tackle-pr-comment works. We'll ismply need to think about a way to collect all the generated artefacts (that are usually ephemeral) as part of our branch and have them long-live in the GitHub repo. We could simply copy the files to a demo folder that we persist in git -- with the full log from our conversation in the `claude-code` terminal in a he-said-she-said visual ? What about `/demo/real-life/issues-10` folder to match https://github.com/couimet/my-claude-skills/issues/10 ? You'be in charge of constantly updating those files -- with sequentially-versioned names every time you change a generate file from one of our skill to capture the changes and your improvements from one iteration to another ? Can you install temporary hooks from your context to implement this so I do not need to manually do it ? You'd need to do it until I tell you to stop. If the temporary hook is not possible, can you always answer through temporary files (sequentially named) and the terminal window becomes a minimal way for you to tell me you're done and look at <this new file> and I reply I edited/replied and we keep looping ? 

---

## Q004: Should the README include inline sample output (showing what generated files look like)?

Context: Beginners won't understand what `/scratchpad` or `/question` produces without seeing it. But inline samples add significant length. This decides how much "show don't tell" to include.

Options:
A) Full inline samples - Show a complete sample scratchpad (with JSON steps), question file, and commit message directly in the README using fenced code blocks. Adds ~80-100 lines but makes the README self-contained.
B) Abbreviated inline + link to examples - Show a short excerpt (10-15 lines) of each format inline, with a "see full example" link to an examples/ directory in the repo.
C) No inline samples - Describe the formats in prose and link to the SKILL.md files for format details. Keeps the README shorter but forces navigation.

Recommendation: B - Short excerpts give beginners enough to understand the format at a glance without bloating the README. Full samples are available for anyone who wants to dig deeper. An examples/ directory also serves as a living reference that can evolve independently of the README.

A004: B feels appropriate with the "Abbreviated inline" suggestion; for more details available at the fingertips, we could use the GitHub summary/details approach with collapsible sections to provide more details. This keeps everything in one place and decrease the friction of following links to navigate to examples. I went back to add a significant amount of additional details to A003 above; it should help you.

---

## Q005: How should the skills reference section be structured?

Context: The current skills/README.md has three tables (foundation, non-invocable, composite). The root README needs a reference section but shouldn't just duplicate the skills README. This decides how to present the skill inventory to different audiences.

Options:
A) Unified table with categories - One table with a "Type" column (Foundation / Auto / Composite), one-liner descriptions, and links to each SKILL.md. Replace skills/README.md content with a redirect to the root README.
B) Two groups only - "What You Type" (invocable skills with `/command` syntax) and "What Works Automatically" (non-invocable). Simpler mental model for newcomers. Keep skills/README.md as the detailed architecture reference.
C) Visual dependency map - Replace tables with an ASCII or text-based diagram showing how composite skills call foundation skills, with brief descriptions alongside. More engaging but harder to maintain.
D) Minimal in root, full in skills/ - Root README has a simple bulleted list ("14 skills across 3 tiers — see the full inventory"). Keep the detailed tables in skills/README.md.

Recommendation: B - The "What You Type" vs. "What Works Automatically" framing is immediately intuitive. It answers the first question any user has: "what can I do?" Nobody's first question is "what's the architectural tier?" Keep skills/README.md as the deeper reference for architecture and step tracking.

A005: B

---

## Q006: Should the README include a "Design Philosophy" or "How I Think About This" section?

Context: The scratchpad plan suggests a philosophy section covering user-controls-commits, ephemeral-vs-permanent, plan-then-execute, etc. This is unusual for a README but could be the most distinctive and valuable part — it explains *why* the skills work the way they do.

Options:
A) Yes, prominent section - Give it a full `##` heading near the top (after quick start, before reference). 5-8 bullet points covering the core principles. This is what makes the project interesting beyond "here are some scripts."
B) Yes, but folded into the intro - Weave the principles into the opening paragraphs rather than giving them their own section. Less structured but more natural.
C) Yes, but at the bottom - Put it after the reference section as "Design Notes" for people who want to understand the thinking. Doesn't compete with the practical content.
D) No - Let the examples speak for themselves. Philosophy emerges from usage.

Recommendation: A - The design principles are the most differentiating content. They explain why someone would adopt these skills over ad-hoc prompting. Putting them near the top (but after the practical quick start) means motivated readers find them quickly while skimmers can jump to the reference.

A006:  Option A sounds good. As part of the 5-8 bullets I want to make sure we call out that I like those skills for the following main reasons:
1. As the author and maintainer of https://github.com/couimet/rangeLink/tree/main/packages/rangelink-vscode-extension I'm definitely biased towards precise references when I interact with you; this is why I want you to produce files (instead of constantly quoting you from the "plan mode")
2. The work files you create and we iterate over are always available after an IDE crash and provide a way to quickly dive back into work with status tracking in the tasks in the scratchpads.
3. The folder-based hierarchical organization of files allows easy lookups/searches (as opposed to files from `~/.claude/plans/`)

---

## Q007: Should we add a visual diagram showing the issue lifecycle flow?

Context: The full workflow (start-issue → tackle blocks → breadcrumbs → side-quests → finish-issue) is the key value story. A visual could make it instantly graspable, but ASCII art or Mermaid diagrams have tradeoffs in a README.

Options:
A) ASCII art flowchart - Works everywhere, renders in any terminal or viewer. Can be compact. Looks intentional in a developer tool README.
B) Mermaid diagram - GitHub renders Mermaid natively in markdown. Clean and professional. But doesn't render in terminal viewers, local markdown editors, or other Git hosts.
C) Both - ASCII for the README, link to a rendered Mermaid version in docs/.
D) Neither - The walkthrough scenario already tells the story sequentially. A diagram would be redundant.

Recommendation: A - ASCII art fits the developer-tool aesthetic, works everywhere, and is easy to maintain. It should be simple — a linear flow with one branch for side-quests — not trying to capture every edge case.

A007: I like Mermaid a lot. Let's try with Mermaid 1st and we'll see what comes out. If it's not great, we'll potentially pivot to ASCII. The ideas pitched in A003 should help us iterate on the Mermaid diagram/full workflow.

---

## Q008: What section ordering gives the best reading experience?

Context: The README needs to serve both "scanning for 30 seconds" and "reading start to finish" use cases. Section order determines the first impression and the narrative flow.

Options:
A) Hook → Install → Quick Start → Full Workflow → Philosophy → Reference → Contributing
B) Hook → Philosophy → Install → Quick Start → Full Workflow → Reference → Contributing
C) Hook → Install → Full Workflow → Quick Start → Philosophy → Reference → Contributing
D) Hook → Install → Quick Start → Reference → Full Workflow → Philosophy → Contributing

Recommendation: A - This follows the standard open-source README pattern: explain what → how to get it → try it → see the full power → understand the thinking → detailed reference. Scanning readers get value from just the first three sections. Deep readers continue through to philosophy and reference.

A008: A

---

## Q009: Should the README link to official Claude Code skills documentation, and how prominently?

Context: The issue explicitly calls out "point to official AGENT skills config for references." This grounds the project in the official ecosystem and helps people who want to understand the underlying mechanism or create their own skills.

Options:
A) Dedicated "Resources" or "Learn More" section at the bottom - Include links to official Claude Code skills docs, SKILL.md format spec, and Claude Code documentation. Clean and conventional.
B) Inline contextual links - Mention the official docs where they're relevant (e.g., in the install section mention how skills work, in the philosophy section link to the skills architecture). No dedicated section.
C) Both - Inline links where relevant plus a collected "Resources" section at the end for people who want to go deeper.

Recommendation: C - Contextual links help readers in the moment ("oh, that's how skills work under the hood"), and a collected section at the end serves as a reference. Neither alone is sufficient.

A009: C; I want to make sure readers do not get the feeling that I pretend I invented all of this -- I'm simply following/leveraging standards.

---

## Q010: Should we create an examples/ directory with sample output files?

Context: Q004 suggests abbreviated inline samples with links to full examples. This question asks whether to actually create that directory as part of this issue, or defer it.

Options:
A) Yes, create examples/ now - Include a sample scratchpad, question file, commit message, and breadcrumbs file. Makes Q004 option B fully workable. Adds ~4 files to the repo.
B) Defer - Keep the README self-contained for now. Create examples/ as a follow-up issue if the inline excerpts feel insufficient.
C) Use real files from .scratchpads/ etc. - Instead of fabricated examples, link to actual working files. Problem: these are git-ignored and won't be in the repo.

Recommendation: A - The examples/ directory directly supports the README's "show don't tell" approach and is small effort. Including sample files also helps people understand the file formats without reading SKILL.md specifications. Four short text files is minimal repo overhead.

A010: Unsure here... See A003 and let me know if you still have questions.

---

## Q011: Should the README address "how to fork/customize these skills for your own workflow"?

Context: Some readers will want to adapt skills rather than use them as-is. A brief section on customization could expand the audience, but it's also scope creep for this issue.

Options:
A) Brief section now - A short "Making These Your Own" paragraph: fork the repo, edit SKILL.md files, re-run install.sh. 5-6 lines. Low effort, high value for the fork-and-customize audience.
B) Defer to a separate doc - Mention it's possible ("these are just markdown files — fork and customize") but don't elaborate. Create a docs/customization.md later if there's interest.
C) Skip entirely - The SKILL.md files are self-documenting. Anyone technical enough to use Claude Code can figure out customization.

Recommendation: A - A brief mention is cheap and signals that this is meant to be adapted, not just consumed. It also reinforces the "no magic" philosophy — these are readable markdown files, not compiled binaries.

A011: A - I 'd love forking to happen; what I'd love even more is for people to submit PRs on this repo.

---

## Q012: Should the opening hook include a "before/after" comparison showing Claude Code without skills vs. with skills?

Context: The strongest way to sell the value might be showing the contrast — what a typical Claude Code session looks like without structured skills (scattered files, no tracking, ad-hoc commits) vs. with them (organized workspace, step tracking, breadcrumb trail). This could be the most compelling element of the intro.

Options:
A) Yes, explicit before/after - Two short side-by-side scenarios or a "Without these skills... / With these skills..." comparison. Immediately communicates value.
B) Implied contrast - Describe what the skills provide and let readers infer the "before" from their own experience. Less dramatic but more concise.
C) Problem statement only - Open with the pain points ("Claude Code is powerful but sessions are unstructured, context is lost between tasks, commit messages are generic...") and then present the skills as the solution. Classic problem-solution framing.

Recommendation: C - A problem statement resonates immediately with anyone who's used Claude Code for real work. They'll recognize the pain points and understand the value proposition without needing an explicit side-by-side. It's also more concise than option A.

A012:  C definitely feels better here -- especially so given how models quickly evolve and any output we capture as made-up example would not age well...

# Demo Approach Follow-ups (from A003)

## Q001: Does the demo/ folder replace the examples/ directory entirely (resolving Q010)?

Context: A003 proposes persisting real artifacts in `demo/real-life/issues-10/`. A004 wants collapsible inline samples. If the demo folder contains real scratchpads, question files, commit messages, and breadcrumbs from this actual issue, that's far more compelling than fabricated examples/ files. The README can inline abbreviated excerpts and link to the demo folder for full context.

Options:
A) Yes, demo/ replaces examples/ - The demo folder IS the examples directory, but better because everything is real. README links point into `demo/real-life/issues-10/` instead of `examples/`.
B) Both - Keep a small examples/ with clean, minimal samples for quick reference. The demo/ folder is the "full story" for people who want depth.

Recommendation: A - Real artifacts are strictly more valuable than fabricated ones. Having both creates maintenance burden and confusing navigation ("which do I look at?"). The demo folder serves both purposes: quick reference (individual files) and full story (the sequence).

A001: A

---

## Q002: What versioning scheme for demo artifacts?

Context: You want sequentially-versioned filenames to capture how files evolve. For example, a scratchpad gets created, then updated when steps complete. We need a naming convention that makes the evolution clear.

Options:
A) Suffix versioning - `0004-readme-enrichment-plan-v1.txt`, `0004-readme-enrichment-plan-v2.txt`, etc. Keeps the original filename recognizable, versions sort naturally.
B) Snapshot directories - `demo/real-life/issues-10/step-01-planning/`, `step-02-first-iteration/`, etc. Each directory is a snapshot of all artifacts at that phase. More context per snapshot but duplicates unchanged files.
C) Flat with timestamps - `2026-02-18T14-30-0004-readme-enrichment-plan.txt`. Self-documenting but long filenames.

Recommendation: A - Suffix versioning is simple, sorts naturally, and doesn't duplicate unchanged files. Readers can diff v1 vs v2 to see exactly what changed. A small `TIMELINE.md` in the demo folder can narrate the sequence.

A002: A -- for the suffix format, instead of `-v1` suffix with single digit, use a `NNNN` format for the numbers (like skills/issue-context/SKILL.md#L79-L89 defines -- yes; shameless plug for a RangeLink here!!!) but for our current custom suffix instead of the beginning of the file). Does that make sense ?

---

## Q003: How should we capture the conversation itself?

Context: You mentioned "the full log from our conversation in the claude-code terminal in a he-said-she-said visual." Claude Code doesn't have a built-in export, and I can't access the terminal rendering. We need a practical approach.

Options:
A) I reconstruct it - I write a narrative log file that summarizes each exchange: what you asked, what I did, what artifacts were produced. Not a verbatim transcript but an accurate retelling with the key prompts and responses.
B) You export manually - You copy-paste the terminal output at key milestones into the demo folder. Most authentic but requires your effort.
C) Annotated artifact trail - Skip the conversation log entirely. Instead, each artifact in the demo folder gets a header comment explaining what prompted its creation and what happened next. The artifacts themselves tell the story.
D) Hybrid - I maintain a TIMELINE.md that narrates the flow with timestamps and links to artifacts. You paste in key terminal snippets when you feel they add value.

Recommendation: D - A TIMELINE.md gives structure and context. Your terminal snippets add authenticity where it matters. I can maintain the timeline continuously; you paste in the bits that are most illustrative.

A003: D - In TIMELINE.md, make sure to add prepared blocks where I can opt-in to add something - or leave blank when I feel nothing was worth adding. I'll rely on you to build most of it. I'll let you capture your recommendation/guidance as a sub-task in the /scratchpad for me to copy from the terminal the start of the conversation before you started building the file. Or, can you use Option A for what has happened so far and you continue on your own with Option D from now on ?

---

## Q004: Should we split this into two issues — README content vs. demo infrastructure?

Context: A003 significantly expands scope. The original issue #10 is "add meat to readme." The demo folder, artifact versioning, conversation capture, and intentional-error-for-CodeRabbit are a substantial parallel effort. Splitting could keep each issue focused, or we could treat the demo as the vehicle for building the README content (they're inseparable).

Options:
A) Keep as one issue - The demo IS the README content. You can't write the "See It In Action" section without having done it. The artifacts are generated as a byproduct of writing the README.
B) Split into two - Issue #10 stays as README content. New issue for "Create demo/ with real artifacts from issue #10 workflow." They reference each other but can be tracked independently.
C) Sub-issues - Keep #10 as parent, create child issues for demo infrastructure, README sections, and the intentional-error experiment.

Recommendation: A - The whole point is that the demo and the README are the same work. Splitting them creates artificial separation and coordination overhead. The demo folder populates naturally as we work through the README issue.

A004: A. About getting CodeRabbit to trip on something: look at all the PRs on https://github.com/couimet/rangeLink; CodeRabbit almost always has something to nitpick about... Use /tackle-pr-comment to retrieve https://github.com/couimet/rangeLink/pull/367#pullrequestreview-3819955487 -- you'llk see CodeRabbit is a stiffler for grammar too. I trust you'll find something..,.

---

## Q005: About the hooks / file-based loop — what's your preferred workflow?

Context: Claude Code doesn't support user-defined hooks that I can install programmatically from within a conversation. The file-based approach you described is workable: I write to files, tell you in terminal, you edit/reply, we loop. But I want to confirm the mechanics.

Options:
A) I copy artifacts to demo/ after each skill invocation - Every time I create or update a scratchpad, question file, commit message, or breadcrumb, I also copy it to `demo/real-life/issues-10/` with the version suffix. I tell you in terminal what changed. You review and reply.
B) Batch copy at milestones - I work normally with ephemeral files, then at key milestones (end of planning, after first implementation block, after PR feedback, etc.) I snapshot everything to the demo folder at once. Less noise, but you lose the incremental story.
C) Demo folder is primary - Instead of creating ephemeral files and copying, I create the working files directly in `demo/real-life/issues-10/`. Skills would need to be invoked with modified paths.

Recommendation: A - Copying after each invocation captures the full incremental story. The ephemeral files still serve their normal workflow purpose; the demo copies are the persistent record. I'll include a short terminal message after each copy: "Updated demo: <filename>".

A005: A should indeed work; combining it with A003 should build something fairly interesting. Clarification from your recommendation: let's use "Added new file: <filename>" to ensure the "Updated" word doesn't confuse us at some point and the process derails and we start updating files instead of creating new ones with suffixes like decided in

Issue #10 — Add Meat to README: Refined Implementation Plan

Resolved decisions from .claude-questions/0001-readme-design-decisions.txt and .claude-questions/0002-demo-approach.txt.

## Summary

Rewrite the landing README as a single comprehensive document with casual first-person voice. The centerpiece is a real "eat your own dog food" demo: we use our actual conversation and issue #10 itself as the walkthrough, persisting all ephemeral artifacts in `demo/real-life/issues-10/` with NNNN-suffixed versioned filenames. A TIMELINE.md narrates the flow. The README links into the demo folder for collapsible full-context examples. We run the full skill lifecycle (start-issue → tackle blocks → breadcrumbs → finish-issue) and let CodeRabbit trigger a /tackle-pr-comment demo naturally.

## Key Decisions (from Q&A)

- **Single comprehensive README** (Q001/A001) — everything in one scrollable document
- **Casual, first-person voice** (Q002/A002) — "I built these because..."
- **Real artifacts from this conversation** (Q003/A003) — no fabrication, full transparency
- **Abbreviated inline + collapsible details** (Q004/A004) — `<details>` blocks for depth, no separate examples/ directory
- **"What You Type" vs. "What Works Automatically"** (Q005/A005) — two-group reference structure
- **Prominent philosophy section** (Q006/A006) — with RangeLink bias, crash recovery, folder-based organization as key bullets
- **Mermaid diagram first** (Q007/A007) — pivot to ASCII if needed
- **Hook → Install → Quick Start → Full Workflow → Philosophy → Reference → Contributing** (Q008/A008)
- **Inline + collected official references** (Q009/A009) — credit standards, don't pretend to have invented anything
- **demo/ replaces examples/** (Q010 resolved by Demo Q001/A001)
- **Brief "Making These Your Own" section** (Q011/A011) — encourage PRs over just forking
- **Problem-statement opening** (Q012/A012) — no fabricated before/after that won't age well
- **NNNN suffix versioning** (Demo Q002/A002) — e.g., `0004-readme-enrichment-plan-0001.txt`
- **TIMELINE.md with prepared user blocks** (Demo Q003/A003) — reconstructed for past, hybrid going forward
- **Single issue scope** (Demo Q004/A004) — demo and README are inseparable
- **Copy after each invocation** (Demo Q005/A005) — "Added new file: <filename>" messaging

## Demo Artifact Conventions

All artifacts persisted in `demo/real-life/issues-10/`.

Naming: `<original-filename>-NNNN.<ext>` where NNNN is a zero-padded sequence scoped per original file.

Examples:
- First version of scratchpad: `0004-readme-enrichment-plan-0001.txt`
- After plan update: `0004-readme-enrichment-plan-0002.txt`
- First question file: `0001-readme-design-decisions-0001.txt`
- After answers filled: `0001-readme-design-decisions-0002.txt`

TIMELINE.md lives at `demo/real-life/issues-10/TIMELINE.md` and is updated (not versioned) since it's the narrative spine.

## README Section Outline

### 1. Opening Hook (problem statement)
Claude Code is powerful but unstructured by default — sessions are ephemeral, context is lost between tasks, commit messages are generic, and there's no trail of decisions made along the way. These skills add lightweight workflow conventions that make Claude a structured development partner.

### 2. Installation
Keep existing content, add brief mention of what Claude Code skills are with inline link to official docs.

### 3. Quick Start — "Your First 5 Minutes"
Three commands to try: `/scratchpad`, `/question`, `/commit-msg`. Show abbreviated output inline with `<details>` blocks expanding to full examples from `demo/real-life/issues-10/`.

### 4. See It In Action — The Full Workflow
The centerpiece. Walk through issue #10's own lifecycle:
1. `/start-issue` — creates branch, scratchpad with implementation plan
2. Review plan, answer questions
3. `/tackle-scratchpad-block` — execute steps iteratively
4. `/breadcrumb` — capture discoveries
5. (Optional) `/start-side-quest` — branch for orthogonal fix
6. `/tackle-pr-comment` — respond to CodeRabbit feedback
7. `/finish-issue` — generate PR description

Each step links to the real versioned artifact in demo/. Mermaid diagram at the top of this section showing the lifecycle flow.

### 5. Why I Built These — Design Philosophy
5-8 bullet points including:
- **Files over chat** — As the author of RangeLink, I'm biased toward precise file references. Skills produce navigable files instead of ephemeral chat output.
- **Crash-proof context** — Work files survive IDE crashes. Status tracking in scratchpads means you can dive back in without reconstructing state.
- **Organized, not scattered** — Folder-based hierarchy (`.scratchpads/issues/42/`) beats flat `~/.claude/plans/` for lookup and search.
- **User controls execution** — Claude plans, user reviews, user commits. No auto-commits, no surprise pushes.
- **Ephemeral vs. permanent** — Working files are git-ignored. Only real code and docs get committed.
- **Plan then execute** — Every composite skill stops after planning. Implementation is a separate, explicit step.
- **No magic** — Skills are just markdown files. Fully readable, forkable, and PR-able.

### 6. Skills Reference
Two groups:

**What You Type** — table of 9 invocable skills with `/command` syntax and one-liner.
**What Works Automatically** — table of 4 non-invocable skills with when they activate.

Link to skills/README.md for architecture details and step tracking format.

### 7. Making These Your Own
Brief paragraph: fork the repo, edit SKILL.md files, re-run install.sh. Encourage PRs for improvements that benefit everyone.

### 8. Resources
Collected links to:
- Official Claude Code skills documentation
- SKILL.md format specification
- Claude Code documentation
- This repo's skills/README.md for architecture details

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Bootstrap demo infrastructure and backfill artifacts",
      "status": "pending",
      "done_when": "demo/real-life/issues-10/ exists with all prior artifacts versioned and TIMELINE.md reconstructed for conversation so far",
      "depends_on": [],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md",
        "demo/real-life/issues-10/0004-readme-enrichment-plan-0001.txt",
        "demo/real-life/issues-10/0004-readme-enrichment-plan-0002.txt",
        "demo/real-life/issues-10/0001-readme-design-decisions-0001.txt",
        "demo/real-life/issues-10/0001-readme-design-decisions-0002.txt",
        "demo/real-life/issues-10/0002-demo-approach-0001.txt",
        "demo/real-life/issues-10/0002-demo-approach-0002.txt"
      ],
      "tasks": [
        "Create demo/real-life/issues-10/ directory",
        "Copy initial scratchpad (before Q&A) as 0004-readme-enrichment-plan-0001.txt",
        "Copy current scratchpad (this file, post-refinement) as 0004-readme-enrichment-plan-0002.txt",
        "Copy question file #1 as created (blank answers) as 0001-readme-design-decisions-0001.txt",
        "Copy question file #1 with answers as 0001-readme-design-decisions-0002.txt",
        "Copy question file #2 as created (blank answers) as 0002-demo-approach-0001.txt",
        "Copy question file #2 with answers as 0002-demo-approach-0002.txt",
        "Write TIMELINE.md reconstructing the conversation from the start (Option A for past events)",
        "Include prepared <!-- YOUR TERMINAL SNIPPET (optional) --> blocks at each exchange point in the timeline"
      ]
    },
    {
      "id": "S002",
      "title": "Create feature branch and formal start-issue flow",
      "status": "pending",
      "done_when": "On issues/10 branch with /start-issue scratchpad created and copied to demo/",
      "depends_on": ["S001"],
      "files": [
        ".scratchpads/issues/10/0001-start-issue-plan.txt"
      ],
      "tasks": [
        "Create issues/10 branch from origin/main",
        "Run /start-issue against https://github.com/couimet/my-claude-skills/issues/10",
        "Copy resulting scratchpad to demo/ with -0001 suffix",
        "Update TIMELINE.md with this step"
      ]
    },
    {
      "id": "S003",
      "title": "Write the README — sections 1-3 (hook, install, quick start)",
      "status": "pending",
      "done_when": "README.md has opening hook, installation, and quick start sections with collapsible detail blocks",
      "depends_on": ["S002"],
      "files": ["README.md"],
      "tasks": [
        "Write problem-statement opening hook",
        "Update installation section with inline link to official Claude Code skills docs",
        "Write Quick Start section with 3 example commands",
        "Add <details> blocks with full output excerpts linking to demo/ artifacts",
        "Use /tackle-scratchpad-block to execute this step",
        "Copy updated README to demo/ as readme-0001.md",
        "Use /commit-msg for this block, copy to demo/",
        "Update TIMELINE.md"
      ]
    },
    {
      "id": "S004",
      "title": "Write the README — section 4 (full workflow with Mermaid diagram)",
      "status": "pending",
      "done_when": "README.md has 'See It In Action' section with Mermaid lifecycle diagram and step-by-step walkthrough linking to demo/ artifacts",
      "depends_on": ["S003"],
      "files": ["README.md"],
      "tasks": [
        "Create Mermaid diagram showing issue lifecycle flow",
        "Write walkthrough narrative using issue #10's own artifacts",
        "Link each step to versioned files in demo/real-life/issues-10/",
        "Add <details> blocks for expanded artifact views",
        "Use /tackle-scratchpad-block, /commit-msg, copy to demo/",
        "Update TIMELINE.md"
      ]
    },
    {
      "id": "S005",
      "title": "Write the README — sections 5-8 (philosophy, reference, contributing, resources)",
      "status": "pending",
      "done_when": "README.md has philosophy bullets, two-group skills reference, making-your-own section, and collected resources with official links",
      "depends_on": ["S004"],
      "files": ["README.md"],
      "tasks": [
        "Write philosophy section with RangeLink, crash-proof, folder-org bullets",
        "Write two-group skills reference (What You Type / What Works Automatically)",
        "Write Making These Your Own paragraph encouraging PRs",
        "Write Resources section with official Claude Code links",
        "Credit standards appropriately throughout (A009)",
        "Use /tackle-scratchpad-block, /commit-msg, copy to demo/",
        "Update TIMELINE.md"
      ]
    },
    {
      "id": "S006",
      "title": "Introduce intentional error for CodeRabbit demo",
      "status": "pending",
      "done_when": "PR created with a subtle but real error that CodeRabbit is likely to catch (grammar, style, or structural issue)",
      "depends_on": ["S005"],
      "files": ["README.md"],
      "tasks": [
        "Introduce a subtle error (grammar, inconsistent formatting, or similar) that CodeRabbit would flag",
        "Push branch and create PR",
        "Wait for CodeRabbit review",
        "Use /tackle-pr-comment on the CodeRabbit feedback",
        "Copy all PR-comment artifacts to demo/",
        "Update TIMELINE.md"
      ]
    },
    {
      "id": "S007",
      "title": "Wrap up with /finish-issue",
      "status": "pending",
      "done_when": "/finish-issue generates PR description, all demo artifacts collected, TIMELINE.md complete",
      "depends_on": ["S006"],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md"
      ],
      "tasks": [
        "Run /finish-issue",
        "Copy generated PR description scratchpad to demo/",
        "Finalize TIMELINE.md with complete narrative",
        "Review all demo/ artifacts for completeness and coherence",
        "Update README section 4 links if any artifact filenames changed during the process"
      ]
    }
  ]
}
```

## Assumptions

- Issue #10 stays bare on GitHub (as stated in A003) — the demo shows the full workflow starting from that minimal issue.
- CodeRabbit is active on this repo and will review PRs automatically. If not, we adapt the /tackle-pr-comment demo (A004 suggests looking at rangeLink PRs for reference).
- The initial scratchpad (0004-readme-enrichment-plan) was created before the issue branch, so it lives at the root .scratchpads/ level. Once we /start-issue, new scratchpads go in .scratchpads/issues/10/.
- TIMELINE.md is the one file we update in place (not versioned) since it's the narrative spine, not a skill artifact.

## Pre-Implementation Task for User

Before S001 begins: consider copying the opening terminal exchange (your initial prompt and my first response) from the Claude Code terminal. This becomes the opening of TIMELINE.md. I'll reconstruct the narrative for the full conversation so far, but authentic terminal snippets at the start would set the tone. I'll leave prepared blocks in TIMELINE.md for you to paste into.

Demo File Naming Convention — Global Sequence + File-Placement Prefix + Version Suffix

Three naming issues to resolve before we start executing implementation steps.

## Issue 1: Missing file-placement category in demo filenames

The flat `demo/real-life/issues-10/` folder needs to be browsable without nested sub-folders. Currently, files like `0004-readme-enrichment-plan-0001.txt` don't tell you at a glance whether it's a scratchpad, question file, commit message, or breadcrumb. The `/file-placement` skill defines categories — we should surface that in the filename.

Categories from file-placement/SKILL.md:
- `scratchpad` — from `.scratchpads/`
- `question` — from `.claude-questions/`
- `commit-msg` — from `.commit-msgs/`
- `breadcrumb` — from `.breadcrumbs/`
- `readme` — special case for README.md snapshots (the actual deliverable)

Delimiter: double-dash (`--`) to visually separate category from filename without colliding with hyphens in slugs.

## Issue 2: Missing `v` prefix on version suffix

Without the `v`, a filename like `0001-readme-design-decisions-0001.txt` has two undifferentiated NNNN blocks. The `v` makes it instantly clear: file #0001, version v0001.

## Issue 3: Missing global chronological sequence

With only category + original-filename + version, the folder sorts by category (all questions together, all scratchpads together). This loses the chronological narrative. A global sequence number prepended to every artifact makes the folder a visual timeline that matches TIMELINE.md 1-for-1.

## Final naming pattern

```
<NNNN>--<category>--<original-filename>-v<NNNN>.<ext>
 ^         ^              ^               ^
 |         |              |               └─ version of this specific file
 |         |              └─ original skill-generated filename
 |         └─ file-placement category
 └─ global chronological sequence (matches TIMELINE.md)
```

TIMELINE.md itself has no prefix — it's the narrative spine, not an artifact snapshot. It is updated in place (never versioned) and every demo artifact maps to an entry in it.

## Chronological mapping of existing artifacts

| Global # | What happened | Demo filename |
|---|---|---|
| 0001 | Claude created initial scratchpad (gap analysis + 8 suggestions) | `0001--scratchpad--0004-readme-enrichment-plan-v0001.txt` |
| 0002 | Claude created 12 design questions (unanswered) | `0002--question--0001-readme-design-decisions-v0001.txt` |
| 0003 | User answered all 12 questions | `0003--question--0001-readme-design-decisions-v0002.txt` |
| 0004 | Claude created 5 demo follow-up questions (unanswered) | `0004--question--0002-demo-approach-v0001.txt` |
| 0005 | User answered demo follow-ups | `0005--question--0002-demo-approach-v0002.txt` |
| 0006 | Claude refined scratchpad with full implementation plan | `0006--scratchpad--0004-readme-enrichment-plan-v0002.txt` |
| 0007 | Claude created this naming convention scratchpad | `0007--scratchpad--0005-demo-file-naming-convention-v0001.txt` |
| 0008 | Claude updated this scratchpad with global sequence | `0008--scratchpad--0005-demo-file-naming-convention-v0002.txt` |

### How it looks when sorted in the folder

```
0001--scratchpad--0004-readme-enrichment-plan-v0001.txt
0002--question--0001-readme-design-decisions-v0001.txt
0003--question--0001-readme-design-decisions-v0002.txt
0004--question--0002-demo-approach-v0001.txt
0005--question--0002-demo-approach-v0002.txt
0006--scratchpad--0004-readme-enrichment-plan-v0002.txt
0007--scratchpad--0005-demo-file-naming-convention-v0001.txt
0008--scratchpad--0005-demo-file-naming-convention-v0002.txt
TIMELINE.md
```

Reading top to bottom tells the full story chronologically. The category segment tells you what kind of artifact it is. The version suffix tells you which iteration of that specific file.

## TIMELINE.md contract

Every file in the demo folder (except TIMELINE.md itself) MUST have a corresponding entry in TIMELINE.md. Every interaction that produces or modifies a demo artifact updates TIMELINE.md. This is a hard rule — the folder listing and TIMELINE.md must always be in sync.

## What needs updating once approved

1. Rename the 6 existing files in `demo/real-life/issues-10/` to new convention
2. Add this scratchpad (v0001 = before global sequence, v0002 = after) as files 0007 and 0008
3. Update TIMELINE.md: fix artifact links, add Exchange 7 (naming convention discussion) and Exchange 8 (global sequence refinement)
4. Update .scratchpads/0004-readme-enrichment-plan.txt Demo Artifact Conventions section and S001 file list

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Rename existing demo files, add new artifacts, and update all references",
      "status": "in_progress",
      "done_when": "All demo files follow new naming convention, TIMELINE.md entries match 1-for-1 with folder contents, main scratchpad conventions updated",
      "depends_on": [],
      "files": [
        "demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt",
        "demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt",
        "demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt",
        "demo/real-life/issues-10/0004--question--0002-demo-approach-v0001.txt",
        "demo/real-life/issues-10/0005--question--0002-demo-approach-v0002.txt",
        "demo/real-life/issues-10/0006--scratchpad--0004-readme-enrichment-plan-v0002.txt",
        "demo/real-life/issues-10/0007--scratchpad--0005-demo-file-naming-convention-v0001.txt",
        "demo/real-life/issues-10/0008--scratchpad--0005-demo-file-naming-convention-v0002.txt",
        "demo/real-life/issues-10/TIMELINE.md",
        ".scratchpads/0004-readme-enrichment-plan.txt"
      ],
      "tasks": [
        "Delete 6 old-named files from demo/real-life/issues-10/",
        "Copy renamed versions of the 6 existing artifacts (global #0001-0006)",
        "Copy scratchpad 0005 v0001 (before global sequence) as global #0007",
        "Copy scratchpad 0005 v0002 (this version) as global #0008",
        "Rewrite TIMELINE.md with updated links and new Exchange 7 + 8 entries",
        "Update main scratchpad (0004) Demo Artifact Conventions section and S001 file list"
      ]
    }
  ]
}
```

# Issue #10: Add Meat to README

Type/Priority/Scope: documentation, enhancement

## Context

The landing README is 25 lines — clone, install, and a pointer to skills/README.md. It communicates nothing about what problem these skills solve, what using them feels like, or why someone would adopt them. The issue asks to "add meat" by pointing to official skills config references and adding a "how I work" section with real usage examples.

Through pre-planning (scratchpads 0004 and 0005, question files 0001 and 0002), the scope expanded into an "eat your own dog food" approach: we use this very issue's workflow as the demo, persisting all ephemeral artifacts in `demo/real-life/issues-10/` so readers can see the full skill lifecycle in action.

Key decisions (resolved in .claude-questions/0001-readme-design-decisions.txt and .claude-questions/0002-demo-approach.txt):
- Single comprehensive README, casual first-person voice, problem-statement opening
- Real artifacts from this conversation as the demo (no fabrication)
- Collapsible `<details>` blocks for inline depth
- Mermaid lifecycle diagram
- "What You Type" / "What Works Automatically" reference structure
- Philosophy section with RangeLink, crash-recovery, folder-org bullets
- demo/ folder with `<NNNN>--<category>--<original-filename>-v<NNNN>.<ext>` naming convention
- TIMELINE.md as narrative spine, 1:1 with demo folder contents

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation with inline link to official Claude Code skills docs, and Quick Start section with 3 example commands and <details> blocks",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Write problem-statement opening hook (pain points of unstructured Claude Code sessions)",
        "Update installation section with inline link to official Claude Code skills docs",
        "Add 'Updating' subsection (keep existing content)",
        "Write Quick Start section: /scratchpad, /question, /commit-msg examples",
        "Add <details> blocks with abbreviated output excerpts linking to demo/ artifacts",
        "Copy updated README to demo/ as next global sequence number"
      ]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "pending",
      "done_when": "README.md has 'See It In Action' section with Mermaid lifecycle diagram and step-by-step walkthrough linking to real demo/ artifacts from issue #10",
      "depends_on": ["S001"],
      "files": ["README.md"],
      "tasks": [
        "Create Mermaid diagram showing issue lifecycle: start-issue → tackle blocks → breadcrumbs → side-quests → finish-issue",
        "Write walkthrough narrative using issue #10's own artifacts",
        "Link each workflow step to versioned files in demo/real-life/issues-10/",
        "Add <details> blocks for expanded artifact views",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S003",
      "title": "Write README sections 5-6: design philosophy and skills reference",
      "status": "pending",
      "done_when": "README.md has philosophy section with 7 bullets and two-group skills reference table",
      "depends_on": ["S002"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Why I Built These' philosophy section with bullets: files over chat (RangeLink bias), crash-proof context, organized not scattered, user controls execution, ephemeral vs permanent, plan then execute, no magic",
        "Write 'What You Type' table (9 invocable skills with /command syntax and one-liner)",
        "Write 'What Works Automatically' table (4 non-invocable skills with when they activate)",
        "Link to skills/README.md for architecture details",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S004",
      "title": "Write README sections 7-8: contributing and resources",
      "status": "pending",
      "done_when": "README.md has 'Making These Your Own' section encouraging PRs and 'Resources' section with official Claude Code links",
      "depends_on": ["S003"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Making These Your Own' paragraph: fork, edit SKILL.md files, re-run install.sh, encourage PRs",
        "Write 'Resources' section with collected links: official Claude Code skills docs, SKILL.md format spec, Claude Code documentation, this repo's skills/README.md",
        "Credit standards appropriately — make clear we're leveraging the official ecosystem, not inventing",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S005",
      "title": "Introduce intentional error for CodeRabbit demo",
      "status": "pending",
      "done_when": "PR created with a subtle but real error that CodeRabbit is likely to catch",
      "depends_on": ["S004"],
      "files": ["README.md"],
      "tasks": [
        "Introduce a subtle error (grammar, inconsistent formatting, broken link, or similar) that CodeRabbit would flag",
        "Push branch and create PR",
        "Wait for CodeRabbit review",
        "Use /tackle-pr-comment on the CodeRabbit feedback",
        "Copy all PR-comment artifacts to demo/"
      ]
    },
    {
      "id": "S006",
      "title": "Wrap up with /finish-issue",
      "status": "pending",
      "done_when": "/finish-issue generates PR description, all demo artifacts collected, TIMELINE.md complete",
      "depends_on": ["S005"],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md"
      ],
      "tasks": [
        "Run /finish-issue to generate PR description",
        "Copy generated PR description scratchpad to demo/",
        "Finalize TIMELINE.md with complete narrative",
        "Review all demo/ artifacts for completeness — folder listing matches TIMELINE.md 1:1",
        "Update README section 4 links if any artifact filenames changed during the process"
      ]
    }
  ]
}
```

## Assumptions Made

- Issue #10 stays bare on GitHub (as stated in design decisions) — the demo shows the full workflow starting from that minimal issue.
- CodeRabbit is active on this repo and will review PRs automatically. If not, we adapt the /tackle-pr-comment demo using a rangeLink PR as reference (per user's suggestion).
- Pre-planning scratchpads (0004, 0005) and question files (0001, 0002) live at root `.scratchpads/` and `.claude-questions/` since they were created before the issue branch. This scratchpad and all future artifacts are scoped to `.scratchpads/issues/10/`.
- TIMELINE.md is updated after every exchange — it's the one file in demo/ that's modified in place rather than versioned.
- The README content references demo artifacts by their final filenames. Since we add artifacts incrementally and filenames include global sequence numbers, the README's "See It In Action" section may need a final pass to update links once all artifacts exist.

## Files to Modify

**S001-S004:** README.md (iterative rewrites)
**S005:** README.md (intentional error), then PR creation
**S006:** demo/real-life/issues-10/TIMELINE.md (finalization)

## Documentation & Discoverability

- [x] README update — this IS the README update
- [ ] CHANGELOG entry — not applicable (no code changes, documentation only)
- [ ] skills/README.md — may need minor updates if root README restructures the reference section
- [ ] install.sh — no changes needed

## Acceptance Criteria

- [ ] README has all 8 sections: hook, install, quick start, full workflow, philosophy, reference, contributing, resources
- [ ] All demo artifacts in demo/real-life/issues-10/ follow the naming convention
- [ ] TIMELINE.md entries match demo folder contents 1:1
- [ ] Mermaid diagram renders correctly on GitHub
- [ ] Official Claude Code skills documentation is linked (inline + resources section)
- [ ] `<details>` blocks expand correctly on GitHub
- [ ] At least one /tackle-pr-comment cycle captured in demo/

# my-claude-skills

Claude Code is powerful, but out of the box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. Pre-planning: explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. Side-quests and breadcrumbs

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Skills

See [skills/README.md](skills/README.md) for the full inventory and architecture.

# Issue #10: Add Meat to README

Type/Priority/Scope: documentation, enhancement

## Context

The landing README is 25 lines — clone, install, and a pointer to skills/README.md. It communicates nothing about what problem these skills solve, what using them feels like, or why someone would adopt them. The issue asks to "add meat" by pointing to official skills config references and adding a "how I work" section with real usage examples.

Through pre-planning (scratchpads 0004 and 0005, question files 0001 and 0002), the scope expanded into an "eat your own dog food" approach: we use this very issue's workflow as the demo, persisting all ephemeral artifacts in `demo/real-life/issues-10/` so readers can see the full skill lifecycle in action.

Key decisions (resolved in .claude-questions/0001-readme-design-decisions.txt and .claude-questions/0002-demo-approach.txt):
- Single comprehensive README, casual first-person voice, problem-statement opening
- Real artifacts from this conversation as the demo (no fabrication)
- Collapsible `<details>` blocks for inline depth
- Mermaid lifecycle diagram
- "What You Type" / "What Works Automatically" reference structure
- Philosophy section with RangeLink, crash-recovery, folder-org bullets
- demo/ folder with `<NNNN>--<category>--<original-filename>-v<NNNN>.<ext>` naming convention
- TIMELINE.md as narrative spine, 1:1 with demo folder contents

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation with inline link to official Claude Code skills docs, and Quick Start section with 3 example commands and <details> blocks",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Write problem-statement opening hook (pain points of unstructured Claude Code sessions)",
        "Update installation section with inline link to official Claude Code skills docs",
        "Add 'Updating' subsection (keep existing content)",
        "Write Quick Start section: /scratchpad, /question, /commit-msg examples",
        "Add <details> blocks with abbreviated output excerpts linking to demo/ artifacts",
        "Copy updated README to demo/ as next global sequence number"
      ]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "done",
      "done_when": "README.md has 'See It In Action' section with Mermaid lifecycle diagram and step-by-step walkthrough linking to real demo/ artifacts from issue #10",
      "depends_on": ["S001"],
      "files": ["README.md"],
      "tasks": [
        "Create Mermaid diagram showing issue lifecycle: start-issue → tackle blocks → breadcrumbs → side-quests → finish-issue",
        "Write walkthrough narrative using issue #10's own artifacts",
        "Link each workflow step to versioned files in demo/real-life/issues-10/",
        "Add <details> blocks for expanded artifact views",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S003",
      "title": "Write README sections 5-6: design philosophy and skills reference",
      "status": "pending",
      "done_when": "README.md has philosophy section with 7 bullets and two-group skills reference table",
      "depends_on": ["S002"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Why I Built These' philosophy section with bullets: files over chat (RangeLink bias), crash-proof context, organized not scattered, user controls execution, ephemeral vs permanent, plan then execute, no magic",
        "Write 'What You Type' table (9 invocable skills with /command syntax and one-liner)",
        "Write 'What Works Automatically' table (4 non-invocable skills with when they activate)",
        "Link to skills/README.md for architecture details",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S004",
      "title": "Write README sections 7-8: contributing and resources",
      "status": "pending",
      "done_when": "README.md has 'Making These Your Own' section encouraging PRs and 'Resources' section with official Claude Code links",
      "depends_on": ["S003"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Making These Your Own' paragraph: fork, edit SKILL.md files, re-run install.sh, encourage PRs",
        "Write 'Resources' section with collected links: official Claude Code skills docs, SKILL.md format spec, Claude Code documentation, this repo's skills/README.md",
        "Credit standards appropriately — make clear we're leveraging the official ecosystem, not inventing",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S005",
      "title": "Introduce intentional error for CodeRabbit demo",
      "status": "pending",
      "done_when": "PR created with a subtle but real error that CodeRabbit is likely to catch",
      "depends_on": ["S004"],
      "files": ["README.md"],
      "tasks": [
        "Introduce a subtle error (grammar, inconsistent formatting, broken link, or similar) that CodeRabbit would flag",
        "Push branch and create PR",
        "Wait for CodeRabbit review",
        "Use /tackle-pr-comment on the CodeRabbit feedback",
        "Copy all PR-comment artifacts to demo/"
      ]
    },
    {
      "id": "S006",
      "title": "Wrap up with /finish-issue",
      "status": "pending",
      "done_when": "/finish-issue generates PR description, all demo artifacts collected, TIMELINE.md complete",
      "depends_on": ["S005"],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md"
      ],
      "tasks": [
        "Run /finish-issue to generate PR description",
        "Copy generated PR description scratchpad to demo/",
        "Finalize TIMELINE.md with complete narrative",
        "Review all demo/ artifacts for completeness — folder listing matches TIMELINE.md 1:1",
        "Update README section 4 links if any artifact filenames changed during the process"
      ]
    }
  ]
}
```

## Assumptions Made

- Issue #10 stays bare on GitHub (as stated in design decisions) — the demo shows the full workflow starting from that minimal issue.
- CodeRabbit is active on this repo and will review PRs automatically. If not, we adapt the /tackle-pr-comment demo using a rangeLink PR as reference (per user's suggestion).
- Pre-planning scratchpads (0004, 0005) and question files (0001, 0002) live at root `.scratchpads/` and `.claude-questions/` since they were created before the issue branch. This scratchpad and all future artifacts are scoped to `.scratchpads/issues/10/`.
- TIMELINE.md is updated after every exchange — it's the one file in demo/ that's modified in place rather than versioned.
- The README content references demo artifacts by their final filenames. Since we add artifacts incrementally and filenames include global sequence numbers, the README's "See It In Action" section may need a final pass to update links once all artifacts exist.

## Files to Modify

**S001-S004:** README.md (iterative rewrites)
**S005:** README.md (intentional error), then PR creation
**S006:** demo/real-life/issues-10/TIMELINE.md (finalization)

## Documentation & Discoverability

- [x] README update — this IS the README update
- [ ] CHANGELOG entry — not applicable (no code changes, documentation only)
- [ ] skills/README.md — may need minor updates if root README restructures the reference section
- [ ] install.sh — no changes needed

## Acceptance Criteria

- [ ] README has all 8 sections: hook, install, quick start, full workflow, philosophy, reference, contributing, resources
- [ ] All demo artifacts in demo/real-life/issues-10/ follow the naming convention
- [ ] TIMELINE.md entries match demo folder contents 1:1
- [ ] Mermaid diagram renders correctly on GitHub
- [ ] Official Claude Code skills documentation is linked (inline + resources section)
- [ ] `<details>` blocks expand correctly on GitHub
- [ ] At least one /tackle-pr-comment cycle captured in demo/

# my-claude-skills

Claude Code is powerful, but out of the box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. Pre-planning: explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. Side-quests and breadcrumbs

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Why I Built These

I've used Claude Code on dozens of real issues and kept running into the same friction points. These skills encode the patterns that worked:

- **Files over chat.** Every decision, plan, and question lives in a file — not buried in terminal scroll. If you use [RangeLink](https://github.com/couimet/rangeLink) or similar tools, the file references become clickable navigation.
- **Crash-proof context.** Claude Code sessions can compact, disconnect, or run out of context. Because everything is written to disk as it happens, you can resume from any scratchpad in a fresh session without losing anything.
- **Organized, not scattered.** Working files go in predictable locations (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) with auto-numbering and issue-scoped subdirectories. No manual file management.
- **You control execution.** Claude proposes plans and drafts commit messages. You review, edit, and execute. No auto-commits, no surprise pushes, no "let me just fix that for you."
- **Ephemeral vs. permanent.** Working files are git-ignored — they're your private workspace. Only real code and documentation get committed. This distinction is enforced by convention, not tooling.
- **Plan, then execute.** `/start-issue` creates the plan. `/tackle-scratchpad-block` executes one step at a time. The plan is always visible, always editable, always the source of truth for what's left to do.
- **No magic.** These are plain markdown files that Claude reads as instructions. There's no framework, no runtime, no dependencies. Fork the repo, edit a `SKILL.md`, re-run `install.sh`.

## Skills Reference

### What You Type

| Command | What It Does |
| --- | --- |
| `/scratchpad <desc>` | Create a working document — plans, analysis, PR drafts, anything temporary |
| `/question <topic>` | Surface design decisions as a structured Q&A file you edit in-place |
| `/commit-msg <desc>` | Draft a commit message focused on WHY, not WHAT |
| `/breadcrumb <note>` | Drop a timestamped note collected by `/finish-issue` for the PR description |
| `/start-issue <url>` | Analyze a GitHub issue, create a branch, and produce an implementation plan |
| `/tackle-scratchpad-block <path#lines>` | Execute a specific step from a plan — the core implementation loop |
| `/start-side-quest <desc>` | Branch off for an orthogonal improvement without polluting the current issue |
| `/tackle-pr-comment <url>` | Analyze PR feedback and create a plan to address it |
| `/finish-issue` | Verify work, collect breadcrumbs, check docs, and generate a PR description |

### What Works Automatically

These skills aren't invoked directly — Claude consults them when the context matches.

| Skill | When It Activates |
| --- | --- |
| `code-ref` | When generating file/line references — formats them as clickable permalinks |
| `file-placement` | When deciding where to put a new file — routes to the right directory |
| `issue-context` | When on an `issues/<N>` branch — scopes working files to issue subdirectories |
| `prose-style` | When writing prose to working files — applies consistent formatting conventions |

For architecture details, the two-tier design, and step tracking schema, see [skills/README.md](skills/README.md).

# Issue #10: Add Meat to README

Type/Priority/Scope: documentation, enhancement

## Context

The landing README is 25 lines — clone, install, and a pointer to skills/README.md. It communicates nothing about what problem these skills solve, what using them feels like, or why someone would adopt them. The issue asks to "add meat" by pointing to official skills config references and adding a "how I work" section with real usage examples.

Through pre-planning (scratchpads 0004 and 0005, question files 0001 and 0002), the scope expanded into an "eat your own dog food" approach: we use this very issue's workflow as the demo, persisting all ephemeral artifacts in `demo/real-life/issues-10/` so readers can see the full skill lifecycle in action.

Key decisions (resolved in .claude-questions/0001-readme-design-decisions.txt and .claude-questions/0002-demo-approach.txt):
- Single comprehensive README, casual first-person voice, problem-statement opening
- Real artifacts from this conversation as the demo (no fabrication)
- Collapsible `<details>` blocks for inline depth
- Mermaid lifecycle diagram
- "What You Type" / "What Works Automatically" reference structure
- Philosophy section with RangeLink, crash-recovery, folder-org bullets
- demo/ folder with `<NNNN>--<category>--<original-filename>-v<NNNN>.<ext>` naming convention
- TIMELINE.md as narrative spine, 1:1 with demo folder contents

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation with inline link to official Claude Code skills docs, and Quick Start section with 3 example commands and <details> blocks",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Write problem-statement opening hook (pain points of unstructured Claude Code sessions)",
        "Update installation section with inline link to official Claude Code skills docs",
        "Add 'Updating' subsection (keep existing content)",
        "Write Quick Start section: /scratchpad, /question, /commit-msg examples",
        "Add <details> blocks with abbreviated output excerpts linking to demo/ artifacts",
        "Copy updated README to demo/ as next global sequence number"
      ]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "done",
      "done_when": "README.md has 'See It In Action' section with Mermaid lifecycle diagram and step-by-step walkthrough linking to real demo/ artifacts from issue #10",
      "depends_on": ["S001"],
      "files": ["README.md"],
      "tasks": [
        "Create Mermaid diagram showing issue lifecycle: start-issue → tackle blocks → breadcrumbs → side-quests → finish-issue",
        "Write walkthrough narrative using issue #10's own artifacts",
        "Link each workflow step to versioned files in demo/real-life/issues-10/",
        "Add <details> blocks for expanded artifact views",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S003",
      "title": "Write README sections 5-6: design philosophy and skills reference",
      "status": "done",
      "done_when": "README.md has philosophy section with 7 bullets and two-group skills reference table",
      "depends_on": ["S002"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Why I Built These' philosophy section with bullets: files over chat (RangeLink bias), crash-proof context, organized not scattered, user controls execution, ephemeral vs permanent, plan then execute, no magic",
        "Write 'What You Type' table (9 invocable skills with /command syntax and one-liner)",
        "Write 'What Works Automatically' table (4 non-invocable skills with when they activate)",
        "Link to skills/README.md for architecture details",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S004",
      "title": "Write README sections 7-8: contributing and resources",
      "status": "pending",
      "done_when": "README.md has 'Making These Your Own' section encouraging PRs and 'Resources' section with official Claude Code links",
      "depends_on": ["S003"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Making These Your Own' paragraph: fork, edit SKILL.md files, re-run install.sh, encourage PRs",
        "Write 'Resources' section with collected links: official Claude Code skills docs, SKILL.md format spec, Claude Code documentation, this repo's skills/README.md",
        "Credit standards appropriately — make clear we're leveraging the official ecosystem, not inventing",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S005",
      "title": "Introduce intentional error for CodeRabbit demo",
      "status": "pending",
      "done_when": "PR created with a subtle but real error that CodeRabbit is likely to catch",
      "depends_on": ["S004"],
      "files": ["README.md"],
      "tasks": [
        "Introduce a subtle error (grammar, inconsistent formatting, broken link, or similar) that CodeRabbit would flag",
        "Push branch and create PR",
        "Wait for CodeRabbit review",
        "Use /tackle-pr-comment on the CodeRabbit feedback",
        "Copy all PR-comment artifacts to demo/"
      ]
    },
    {
      "id": "S006",
      "title": "Wrap up with /finish-issue",
      "status": "pending",
      "done_when": "/finish-issue generates PR description, all demo artifacts collected, TIMELINE.md complete",
      "depends_on": ["S005"],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md"
      ],
      "tasks": [
        "Run /finish-issue to generate PR description",
        "Copy generated PR description scratchpad to demo/",
        "Finalize TIMELINE.md with complete narrative",
        "Review all demo/ artifacts for completeness — folder listing matches TIMELINE.md 1:1",
        "Update README section 4 links if any artifact filenames changed during the process"
      ]
    }
  ]
}
```

## Assumptions Made

- Issue #10 stays bare on GitHub (as stated in design decisions) — the demo shows the full workflow starting from that minimal issue.
- CodeRabbit is active on this repo and will review PRs automatically. If not, we adapt the /tackle-pr-comment demo using a rangeLink PR as reference (per user's suggestion).
- Pre-planning scratchpads (0004, 0005) and question files (0001, 0002) live at root `.scratchpads/` and `.claude-questions/` since they were created before the issue branch. This scratchpad and all future artifacts are scoped to `.scratchpads/issues/10/`.
- TIMELINE.md is updated after every exchange — it's the one file in demo/ that's modified in place rather than versioned.
- The README content references demo artifacts by their final filenames. Since we add artifacts incrementally and filenames include global sequence numbers, the README's "See It In Action" section may need a final pass to update links once all artifacts exist.

## Files to Modify

**S001-S004:** README.md (iterative rewrites)
**S005:** README.md (intentional error), then PR creation
**S006:** demo/real-life/issues-10/TIMELINE.md (finalization)

## Documentation & Discoverability

- [x] README update — this IS the README update
- [ ] CHANGELOG entry — not applicable (no code changes, documentation only)
- [ ] skills/README.md — may need minor updates if root README restructures the reference section
- [ ] install.sh — no changes needed

## Acceptance Criteria

- [ ] README has all 8 sections: hook, install, quick start, full workflow, philosophy, reference, contributing, resources
- [ ] All demo artifacts in demo/real-life/issues-10/ follow the naming convention
- [ ] TIMELINE.md entries match demo folder contents 1:1
- [ ] Mermaid diagram renders correctly on GitHub
- [ ] Official Claude Code skills documentation is linked (inline + resources section)
- [ ] `<details>` blocks expand correctly on GitHub
- [ ] At least one /tackle-pr-comment cycle captured in demo/

# my-claude-skills

Claude Code is powerful, but out of the box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. Pre-planning: explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. Side-quests and breadcrumbs

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Why I Built These

I've used Claude Code on dozens of real issues and kept running into the same friction points. These skills encode the patterns that worked:

- **Files over chat.** Every decision, plan, and question lives in a file — not buried in terminal scroll. If you use [RangeLink](https://github.com/couimet/rangeLink) or similar tools, the file references become clickable navigation.
- **Crash-proof context.** Claude Code sessions can compact, disconnect, or run out of context. Because everything is written to disk as it happens, you can resume from any scratchpad in a fresh session without losing anything.
- **Organized, not scattered.** Working files go in predictable locations (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) with auto-numbering and issue-scoped subdirectories. No manual file management.
- **You control execution.** Claude proposes plans and drafts commit messages. You review, edit, and execute. No auto-commits, no surprise pushes, no "let me just fix that for you."
- **Ephemeral vs. permanent.** Working files are git-ignored — they're your private workspace. Only real code and documentation get committed. This distinction is enforced by convention, not tooling.
- **Plan, then execute.** `/start-issue` creates the plan. `/tackle-scratchpad-block` executes one step at a time. The plan is always visible, always editable, always the source of truth for what's left to do.
- **No magic.** These are plain markdown files that Claude reads as instructions. There's no framework, no runtime, no dependencies. Fork the repo, edit a `SKILL.md`, and changes take effect immediately — symlinks mean edits are picked up without re-running anything. You only run `install.sh` again when adding or removing skills.

## Skills Reference

### What You Type

| Command | What It Does |
| --- | --- |
| `/scratchpad <desc>` | Create a working document — plans, analysis, PR drafts, anything temporary |
| `/question <topic>` | Surface design decisions as a structured Q&A file you edit in-place |
| `/commit-msg <desc>` | Draft a commit message focused on WHY, not WHAT |
| `/breadcrumb <note>` | Drop a timestamped note collected by `/finish-issue` for the PR description |
| `/start-issue <url>` | Analyze a GitHub issue, create a branch, and produce an implementation plan |
| `/tackle-scratchpad-block <path#lines>` | Execute a specific step from a plan — the core implementation loop |
| `/start-side-quest <desc>` | Branch off for an orthogonal improvement without polluting the current issue |
| `/tackle-pr-comment <url>` | Analyze PR feedback and create a plan to address it |
| `/finish-issue` | Verify work, collect breadcrumbs, check docs, and generate a PR description |

### What Works Automatically

These skills aren't invoked directly — Claude consults them when the context matches.

| Skill | When It Activates |
| --- | --- |
| `code-ref` | When generating file/line references — formats them as GitHub-style permalinks, clickable in editors with [RangeLink](https://github.com/couimet/rangeLink) installed (VS Code/Cursor don't recognize the suffix natively) |
| `file-placement` | When deciding where to put a new file — routes to the right directory |
| `issue-context` | When on an `issues/<N>` branch — scopes working files to issue subdirectories |
| `prose-style` | When writing prose to working files — applies consistent formatting conventions |

For architecture details, the two-tier design, and step tracking schema, see [skills/README.md](skills/README.md).

# my-claude-skills

Claude Code is powerful, but out of the box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. Pre-planning: explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. Side-quests and breadcrumbs

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Why I Built These

I've used Claude Code on dozens of real issues and kept running into the same friction points. These skills encode the patterns that worked:

- **Files over chat.** Every decision, plan, and question lives in a file — not buried in terminal scroll. If you use [RangeLink](https://github.com/couimet/rangeLink) or similar tools, the file references become clickable navigation.
- **Crash-proof context.** Claude Code sessions can compact, disconnect, or run out of context. Because everything is written to disk as it happens, you can resume from any scratchpad in a fresh session without losing anything.
- **Organized, not scattered.** Working files go in predictable locations (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) with auto-numbering and issue-scoped subdirectories. No manual file management.
- **You control execution.** Claude proposes plans and drafts commit messages. You review, edit, and execute. No auto-commits, no surprise pushes, no "let me just fix that for you."
- **Ephemeral vs. permanent.** Working files are git-ignored — they're your private workspace. Only real code and documentation get committed. This distinction is enforced by convention, not tooling.
- **Plan, then execute.** `/start-issue` creates the plan. `/tackle-scratchpad-block` executes one step at a time. The plan is always visible, always editable, always the source of truth for what's left to do.
- **No magic.** These are plain markdown files that Claude reads as instructions. There's no framework, no runtime, no dependencies. Fork the repo, edit a `SKILL.md`, and changes take effect immediately — symlinks mean edits are picked up without re-running anything. You only run `install.sh` again when adding or removing skills.

## Skills Reference

### What You Type

| Command | What It Does |
| --- | --- |
| `/scratchpad <desc>` | Create a working document — plans, analysis, PR drafts, anything temporary |
| `/question <topic>` | Surface design decisions as a structured Q&A file you edit in-place |
| `/commit-msg <desc>` | Draft a commit message focused on WHY, not WHAT |
| `/breadcrumb <note>` | Drop a timestamped note collected by `/finish-issue` for the PR description |
| `/start-issue <url>` | Analyze a GitHub issue, create a branch, and produce an implementation plan |
| `/tackle-scratchpad-block <path#lines>` | Execute a specific step from a plan — the core implementation loop |
| `/start-side-quest <desc>` | Branch off for an orthogonal improvement without polluting the current issue |
| `/tackle-pr-comment <url>` | Analyze PR feedback and create a plan to address it |
| `/finish-issue` | Verify work, collect breadcrumbs, check docs, and generate a PR description |

### What Works Automatically

These skills aren't invoked directly — Claude consults them when the context matches.

| Skill | When It Activates |
| --- | --- |
| `code-ref` | When generating file/line references — formats them as GitHub-style permalinks, clickable in editors with [RangeLink](https://github.com/couimet/rangeLink) installed (VS Code/Cursor don't recognize the suffix natively) |
| `file-placement` | When deciding where to put a new file — routes to the right directory |
| `issue-context` | When on an `issues/<N>` branch — scopes working files to issue subdirectories |
| `prose-style` | When writing prose to working files — applies consistent formatting conventions |

For architecture details, the two-tier design, and step tracking schema, see [skills/README.md](skills/README.md).

## Making These Your Own

These skills are designed to be forked and adapted. Each skill is a standalone `SKILL.md` file — plain markdown with instructions Claude follows. There's no coupling between them beyond naming conventions.

To customize:

1. **Fork this repo** and clone it locally
2. **Edit any `SKILL.md`** in `skills/` — changes take effect immediately through symlinks
3. **Add new skills** by creating a new directory under `skills/` with a `SKILL.md`, then re-run `install.sh`
4. **Remove skills** by deleting the directory and re-running `install.sh`

If you build something useful, PRs are welcome. These skills evolved from my own workflow friction — yours will be different, and that's the point.

## Resources

- [Claude Code skills documentation](https://code.claude.com/docs/en/skills) — the official guide to how skills work, including the `SKILL.md` format spec
- [Claude Code documentation](https://code.claude.com/docs/en/) — full Claude Code reference
- [skills/README.md](skills/README.md) — this repo's skill inventory, architecture notes, and step tracking schema
- [RangeLink](https://github.com/couimet/rangeLink) — VS Code/Cursor extension that makes `file#line` references clickable (used throughout these skills via the `code-ref` convention)

Everything here builds on Claude Code's official skills system — we're not inventing a framework, just adding conventions on top of what Anthropic already provides.

# Issue #10: Add Meat to README

Type/Priority/Scope: documentation, enhancement

## Context

The landing README is 25 lines — clone, install, and a pointer to skills/README.md. It communicates nothing about what problem these skills solve, what using them feels like, or why someone would adopt them. The issue asks to "add meat" by pointing to official skills config references and adding a "how I work" section with real usage examples.

Through pre-planning (scratchpads 0004 and 0005, question files 0001 and 0002), the scope expanded into an "eat your own dog food" approach: we use this very issue's workflow as the demo, persisting all ephemeral artifacts in `demo/real-life/issues-10/` so readers can see the full skill lifecycle in action.

Key decisions (resolved in .claude-questions/0001-readme-design-decisions.txt and .claude-questions/0002-demo-approach.txt):
- Single comprehensive README, casual first-person voice, problem-statement opening
- Real artifacts from this conversation as the demo (no fabrication)
- Collapsible `<details>` blocks for inline depth
- Mermaid lifecycle diagram
- "What You Type" / "What Works Automatically" reference structure
- Philosophy section with RangeLink, crash-recovery, folder-org bullets
- demo/ folder with `<NNNN>--<category>--<original-filename>-v<NNNN>.<ext>` naming convention
- TIMELINE.md as narrative spine, 1:1 with demo folder contents

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation with inline link to official Claude Code skills docs, and Quick Start section with 3 example commands and <details> blocks",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Write problem-statement opening hook (pain points of unstructured Claude Code sessions)",
        "Update installation section with inline link to official Claude Code skills docs",
        "Add 'Updating' subsection (keep existing content)",
        "Write Quick Start section: /scratchpad, /question, /commit-msg examples",
        "Add <details> blocks with abbreviated output excerpts linking to demo/ artifacts",
        "Copy updated README to demo/ as next global sequence number"
      ]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "done",
      "done_when": "README.md has 'See It In Action' section with Mermaid lifecycle diagram and step-by-step walkthrough linking to real demo/ artifacts from issue #10",
      "depends_on": ["S001"],
      "files": ["README.md"],
      "tasks": [
        "Create Mermaid diagram showing issue lifecycle: start-issue → tackle blocks → breadcrumbs → side-quests → finish-issue",
        "Write walkthrough narrative using issue #10's own artifacts",
        "Link each workflow step to versioned files in demo/real-life/issues-10/",
        "Add <details> blocks for expanded artifact views",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S003",
      "title": "Write README sections 5-6: design philosophy and skills reference",
      "status": "done",
      "done_when": "README.md has philosophy section with 7 bullets and two-group skills reference table",
      "depends_on": ["S002"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Why I Built These' philosophy section with bullets: files over chat (RangeLink bias), crash-proof context, organized not scattered, user controls execution, ephemeral vs permanent, plan then execute, no magic",
        "Write 'What You Type' table (9 invocable skills with /command syntax and one-liner)",
        "Write 'What Works Automatically' table (4 non-invocable skills with when they activate)",
        "Link to skills/README.md for architecture details",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S004",
      "title": "Write README sections 7-8: contributing and resources",
      "status": "done",
      "done_when": "README.md has 'Making These Your Own' section encouraging PRs and 'Resources' section with official Claude Code links",
      "depends_on": ["S003"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Making These Your Own' paragraph: fork, edit SKILL.md files, re-run install.sh, encourage PRs",
        "Write 'Resources' section with collected links: official Claude Code skills docs, SKILL.md format spec, Claude Code documentation, this repo's skills/README.md",
        "Credit standards appropriately — make clear we're leveraging the official ecosystem, not inventing",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S005",
      "title": "Introduce intentional error for CodeRabbit demo",
      "status": "pending",
      "done_when": "PR created with a subtle but real error that CodeRabbit is likely to catch",
      "depends_on": ["S004"],
      "files": ["README.md"],
      "tasks": [
        "Introduce a subtle error (grammar, inconsistent formatting, broken link, or similar) that CodeRabbit would flag",
        "Push branch and create PR",
        "Wait for CodeRabbit review",
        "Use /tackle-pr-comment on the CodeRabbit feedback",
        "Copy all PR-comment artifacts to demo/"
      ]
    },
    {
      "id": "S006",
      "title": "Wrap up with /finish-issue",
      "status": "pending",
      "done_when": "/finish-issue generates PR description, all demo artifacts collected, TIMELINE.md complete",
      "depends_on": ["S005"],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md"
      ],
      "tasks": [
        "Run /finish-issue to generate PR description",
        "Copy generated PR description scratchpad to demo/",
        "Finalize TIMELINE.md with complete narrative",
        "Review all demo/ artifacts for completeness — folder listing matches TIMELINE.md 1:1",
        "Update README section 4 links if any artifact filenames changed during the process"
      ]
    }
  ]
}
```

## Assumptions Made

- Issue #10 stays bare on GitHub (as stated in design decisions) — the demo shows the full workflow starting from that minimal issue.
- CodeRabbit is active on this repo and will review PRs automatically. If not, we adapt the /tackle-pr-comment demo using a rangeLink PR as reference (per user's suggestion).
- Pre-planning scratchpads (0004, 0005) and question files (0001, 0002) live at root `.scratchpads/` and `.claude-questions/` since they were created before the issue branch. This scratchpad and all future artifacts are scoped to `.scratchpads/issues/10/`.
- TIMELINE.md is updated after every exchange — it's the one file in demo/ that's modified in place rather than versioned.
- The README content references demo artifacts by their final filenames. Since we add artifacts incrementally and filenames include global sequence numbers, the README's "See It In Action" section may need a final pass to update links once all artifacts exist.

## Files to Modify

**S001-S004:** README.md (iterative rewrites)
**S005:** README.md (intentional error), then PR creation
**S006:** demo/real-life/issues-10/TIMELINE.md (finalization)

## Documentation & Discoverability

- [x] README update — this IS the README update
- [ ] CHANGELOG entry — not applicable (no code changes, documentation only)
- [ ] skills/README.md — may need minor updates if root README restructures the reference section
- [ ] install.sh — no changes needed

## Acceptance Criteria

- [ ] README has all 8 sections: hook, install, quick start, full workflow, philosophy, reference, contributing, resources
- [ ] All demo artifacts in demo/real-life/issues-10/ follow the naming convention
- [ ] TIMELINE.md entries match demo folder contents 1:1
- [ ] Mermaid diagram renders correctly on GitHub
- [ ] Official Claude Code skills documentation is linked (inline + resources section)
- [ ] `<details>` blocks expand correctly on GitHub
- [ ] At least one /tackle-pr-comment cycle captured in demo/

# my-claude-skills

Claude Code is powerful, but out of the box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. Pre-planning: explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. Side-quests and breadcrumbs

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Why I Built These

I've used Claude Code on dozens of real issues and kept running into the same friction points. These skills encode the patterns that worked:

- **Files over chat.** Every decision, plan, and question lives in a file — not buried in terminal scroll. If you use [RangeLink](https://github.com/couimet/rangeLink) or similar tools, the file references become clickable navigation.
- **Crash-proof context.** Claude Code sessions can compact, disconnect, or run out of context. Because everything is written to disk as it happens, you can resume from any scratchpad in a fresh session without losing anything.
- **Organized, not scattered.** Working files go in predictable locations (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) with auto-numbering and issue-scoped subdirectories. No manual file management.
- **You control execution.** Claude proposes plans and drafts commit messages. You review, edit, and execute. No auto-commits, no surprise pushes, no "let me just fix that for you."
- **Ephemeral vs. permanent.** Working files are git-ignored — they're your private workspace. Only real code and documentation get committed. This distinction is enforced by convention, not tooling.
- **Plan, then execute.** `/start-issue` creates the plan. `/tackle-scratchpad-block` executes one step at a time. The plan is always visible, always editable, always the source of truth for what's left to do.
- **No magic.** These are plain markdown files that Claude reads as instructions. There's no framework, no runtime, no dependencies. Fork the repo, edit a `SKILL.md`, and changes take effect immediately — symlinks mean edits are picked up without re-running anything. You only run `install.sh` again when adding or removing skills.

## Skills Reference

### What You Type

| Command | What It Does |
| --- | --- |
| `/scratchpad <desc>` | Create a working document — plans, analysis, PR drafts, anything temporary |
| `/question <topic>` | Surface design decisions as a structured Q&A file you edit in-place |
| `/commit-msg <desc>` | Draft a commit message focused on WHY, not WHAT |
| `/breadcrumb <note>` | Drop a timestamped note collected by `/finish-issue` for the PR description |
| `/start-issue <url>` | Analyze a GitHub issue, create a branch, and produce an implementation plan |
| `/tackle-scratchpad-block <path#lines>` | Execute a specific step from a plan — the core implementation loop |
| `/start-side-quest <desc>` | Branch off for an orthogonal improvement without polluting the current issue |
| `/tackle-pr-comment <url>` | Analyze PR feedback and create a plan to address it |
| `/finish-issue` | Verify work, collect breadcrumbs, check docs, and generate a PR description |

### What Works Automatically

These skills aren't invoked directly — Claude consults them when the context matches.

| Skill | When It Activates |
| --- | --- |
| `code-ref` | When generating file/line references — formats them as GitHub-style permalinks, clickable in editors with [RangeLink](https://github.com/couimet/rangeLink) installed (VS Code/Cursor don't recognize the suffix natively) |
| `file-placement` | When deciding where to put a new file — routes to the right directory |
| `issue-context` | When on an `issues/<N>` branch — scopes working files to issue subdirectories |
| `prose-style` | When writing prose to working files — applies consistent formatting conventions |

For architecture details, the two-tier design, and step tracking schema, see [skills/README.md](skills/README.md).

## Making These Your Own

These skills are designed to be forked and adapted. Each skill is a standalone `SKILL.md` file — plain markdown with instructions Claude follows. There's no coupling between them beyond naming conventions.

To customize:

1. **Fork this repo** and clone it locally
2. **Edit any `SKILL.md`** in `skills/` — changes take effect immediately through symlinks
3. **Add new skills** by creating a new directory under `skills/` with a `SKILL.md`, then re-run `install.sh`
4. **Remove skills** by deleting the directory and re-running `install.sh`

If you build something useful, PRs are welcome. These skills evolved from my own workflow friction — yours will be different, and that's the point.

## Resources

- [Claude Code skills documentation](https://code.claude.com/docs/en/skills) — the official guide to how skills work, including the `SKILL.md` format spec
- [Claude Code documentation](https://code.claude.com/docs/en/) — full Claude Code reference
- [skills/README.md](skill/README.md) — this repo's skill inventory, architecture notes, and step tracking schema
- [RangeLink](https://github.com/couimet/rangeLink) — VS Code/Cursor extension that makes `file#line` references clickable (used throughout these skills via the `code-ref` convention)

Everything here builds on Claude Code's official skills system — we're not inventing a framework, just adding conventions on top of what Anthropic already provides.

# Issue #10: Add Meat to README

Type/Priority/Scope: documentation, enhancement

## Context

The landing README is 25 lines — clone, install, and a pointer to skills/README.md. It communicates nothing about what problem these skills solve, what using them feels like, or why someone would adopt them. The issue asks to "add meat" by pointing to official skills config references and adding a "how I work" section with real usage examples.

Through pre-planning (scratchpads 0004 and 0005, question files 0001 and 0002), the scope expanded into an "eat your own dog food" approach: we use this very issue's workflow as the demo, persisting all ephemeral artifacts in `demo/real-life/issues-10/` so readers can see the full skill lifecycle in action.

Key decisions (resolved in .claude-questions/0001-readme-design-decisions.txt and .claude-questions/0002-demo-approach.txt):
- Single comprehensive README, casual first-person voice, problem-statement opening
- Real artifacts from this conversation as the demo (no fabrication)
- Collapsible `<details>` blocks for inline depth
- Mermaid lifecycle diagram
- "What You Type" / "What Works Automatically" reference structure
- Philosophy section with RangeLink, crash-recovery, folder-org bullets
- demo/ folder with `<NNNN>--<category>--<original-filename>-v<NNNN>.<ext>` naming convention
- TIMELINE.md as narrative spine, 1:1 with demo folder contents

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation with inline link to official Claude Code skills docs, and Quick Start section with 3 example commands and <details> blocks",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Write problem-statement opening hook (pain points of unstructured Claude Code sessions)",
        "Update installation section with inline link to official Claude Code skills docs",
        "Add 'Updating' subsection (keep existing content)",
        "Write Quick Start section: /scratchpad, /question, /commit-msg examples",
        "Add <details> blocks with abbreviated output excerpts linking to demo/ artifacts",
        "Copy updated README to demo/ as next global sequence number"
      ]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "done",
      "done_when": "README.md has 'See It In Action' section with Mermaid lifecycle diagram and step-by-step walkthrough linking to real demo/ artifacts from issue #10",
      "depends_on": ["S001"],
      "files": ["README.md"],
      "tasks": [
        "Create Mermaid diagram showing issue lifecycle: start-issue → tackle blocks → breadcrumbs → side-quests → finish-issue",
        "Write walkthrough narrative using issue #10's own artifacts",
        "Link each workflow step to versioned files in demo/real-life/issues-10/",
        "Add <details> blocks for expanded artifact views",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S003",
      "title": "Write README sections 5-6: design philosophy and skills reference",
      "status": "done",
      "done_when": "README.md has philosophy section with 7 bullets and two-group skills reference table",
      "depends_on": ["S002"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Why I Built These' philosophy section with bullets: files over chat (RangeLink bias), crash-proof context, organized not scattered, user controls execution, ephemeral vs permanent, plan then execute, no magic",
        "Write 'What You Type' table (9 invocable skills with /command syntax and one-liner)",
        "Write 'What Works Automatically' table (4 non-invocable skills with when they activate)",
        "Link to skills/README.md for architecture details",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S004",
      "title": "Write README sections 7-8: contributing and resources",
      "status": "done",
      "done_when": "README.md has 'Making These Your Own' section encouraging PRs and 'Resources' section with official Claude Code links",
      "depends_on": ["S003"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Making These Your Own' paragraph: fork, edit SKILL.md files, re-run install.sh, encourage PRs",
        "Write 'Resources' section with collected links: official Claude Code skills docs, SKILL.md format spec, Claude Code documentation, this repo's skills/README.md",
        "Credit standards appropriately — make clear we're leveraging the official ecosystem, not inventing",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S005",
      "title": "Introduce intentional error for CodeRabbit demo",
      "status": "done",
      "done_when": "PR created with a subtle but real error that CodeRabbit is likely to catch",
      "depends_on": ["S004"],
      "files": ["README.md"],
      "tasks": [
        "Introduce a subtle error (grammar, inconsistent formatting, broken link, or similar) that CodeRabbit would flag",
        "Push branch and create PR",
        "Wait for CodeRabbit review",
        "Use /tackle-pr-comment on the CodeRabbit feedback",
        "Copy all PR-comment artifacts to demo/"
      ]
    },
    {
      "id": "S006",
      "title": "Wrap up with /finish-issue",
      "status": "pending",
      "done_when": "/finish-issue generates PR description, all demo artifacts collected, TIMELINE.md complete",
      "depends_on": ["S005"],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md"
      ],
      "tasks": [
        "Run /finish-issue to generate PR description",
        "Copy generated PR description scratchpad to demo/",
        "Finalize TIMELINE.md with complete narrative",
        "Review all demo/ artifacts for completeness — folder listing matches TIMELINE.md 1:1",
        "Update README section 4 links if any artifact filenames changed during the process"
      ]
    }
  ]
}
```

## Assumptions Made

- Issue #10 stays bare on GitHub (as stated in design decisions) — the demo shows the full workflow starting from that minimal issue.
- CodeRabbit is active on this repo and will review PRs automatically. If not, we adapt the /tackle-pr-comment demo using a rangeLink PR as reference (per user's suggestion).
- Pre-planning scratchpads (0004, 0005) and question files (0001, 0002) live at root `.scratchpads/` and `.claude-questions/` since they were created before the issue branch. This scratchpad and all future artifacts are scoped to `.scratchpads/issues/10/`.
- TIMELINE.md is updated after every exchange — it's the one file in demo/ that's modified in place rather than versioned.
- The README content references demo artifacts by their final filenames. Since we add artifacts incrementally and filenames include global sequence numbers, the README's "See It In Action" section may need a final pass to update links once all artifacts exist.

## Files to Modify

**S001-S004:** README.md (iterative rewrites)
**S005:** README.md (intentional error), then PR creation
**S006:** demo/real-life/issues-10/TIMELINE.md (finalization)

## Documentation & Discoverability

- [x] README update — this IS the README update
- [ ] CHANGELOG entry — not applicable (no code changes, documentation only)
- [ ] skills/README.md — may need minor updates if root README restructures the reference section
- [ ] install.sh — no changes needed

## Acceptance Criteria

- [ ] README has all 8 sections: hook, install, quick start, full workflow, philosophy, reference, contributing, resources
- [ ] All demo artifacts in demo/real-life/issues-10/ follow the naming convention
- [ ] TIMELINE.md entries match demo folder contents 1:1
- [ ] Mermaid diagram renders correctly on GitHub
- [ ] Official Claude Code skills documentation is linked (inline + resources section)
- [ ] `<details>` blocks expand correctly on GitHub
- [ ] At least one /tackle-pr-comment cycle captured in demo/

# Issue #10: Add Meat to README

Type/Priority/Scope: documentation, enhancement

## Context

The landing README is 25 lines — clone, install, and a pointer to skills/README.md. It communicates nothing about what problem these skills solve, what using them feels like, or why someone would adopt them. The issue asks to "add meat" by pointing to official skills config references and adding a "how I work" section with real usage examples.

Through pre-planning (scratchpads 0004 and 0005, question files 0001 and 0002), the scope expanded into an "eat your own dog food" approach: we use this very issue's workflow as the demo, persisting all ephemeral artifacts in `demo/real-life/issues-10/` so readers can see the full skill lifecycle in action.

Key decisions (resolved in .claude-questions/0001-readme-design-decisions.txt and .claude-questions/0002-demo-approach.txt):
- Single comprehensive README, casual first-person voice, problem-statement opening
- Real artifacts from this conversation as the demo (no fabrication)
- Collapsible `<details>` blocks for inline depth
- Mermaid lifecycle diagram
- "What You Type" / "What Works Automatically" reference structure
- Philosophy section with RangeLink, crash-recovery, folder-org bullets
- demo/ folder with `<NNNN>--<category>--<original-filename>-v<NNNN>.<ext>` naming convention
- TIMELINE.md as narrative spine, 1:1 with demo folder contents

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation with inline link to official Claude Code skills docs, and Quick Start section with 3 example commands and <details> blocks",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Write problem-statement opening hook (pain points of unstructured Claude Code sessions)",
        "Update installation section with inline link to official Claude Code skills docs",
        "Add 'Updating' subsection (keep existing content)",
        "Write Quick Start section: /scratchpad, /question, /commit-msg examples",
        "Add <details> blocks with abbreviated output excerpts linking to demo/ artifacts",
        "Copy updated README to demo/ as next global sequence number"
      ]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "done",
      "done_when": "README.md has 'See It In Action' section with Mermaid lifecycle diagram and step-by-step walkthrough linking to real demo/ artifacts from issue #10",
      "depends_on": ["S001"],
      "files": ["README.md"],
      "tasks": [
        "Create Mermaid diagram showing issue lifecycle: start-issue → tackle blocks → breadcrumbs → side-quests → finish-issue",
        "Write walkthrough narrative using issue #10's own artifacts",
        "Link each workflow step to versioned files in demo/real-life/issues-10/",
        "Add <details> blocks for expanded artifact views",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S003",
      "title": "Write README sections 5-6: design philosophy and skills reference",
      "status": "done",
      "done_when": "README.md has philosophy section with 7 bullets and two-group skills reference table",
      "depends_on": ["S002"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Why I Built These' philosophy section with bullets: files over chat (RangeLink bias), crash-proof context, organized not scattered, user controls execution, ephemeral vs permanent, plan then execute, no magic",
        "Write 'What You Type' table (9 invocable skills with /command syntax and one-liner)",
        "Write 'What Works Automatically' table (4 non-invocable skills with when they activate)",
        "Link to skills/README.md for architecture details",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S004",
      "title": "Write README sections 7-8: contributing and resources",
      "status": "done",
      "done_when": "README.md has 'Making These Your Own' section encouraging PRs and 'Resources' section with official Claude Code links",
      "depends_on": ["S003"],
      "files": ["README.md"],
      "tasks": [
        "Write 'Making These Your Own' paragraph: fork, edit SKILL.md files, re-run install.sh, encourage PRs",
        "Write 'Resources' section with collected links: official Claude Code skills docs, SKILL.md format spec, Claude Code documentation, this repo's skills/README.md",
        "Credit standards appropriately — make clear we're leveraging the official ecosystem, not inventing",
        "Copy updated README to demo/"
      ]
    },
    {
      "id": "S005",
      "title": "Introduce intentional error for CodeRabbit demo",
      "status": "done",
      "done_when": "PR created with a subtle but real error that CodeRabbit is likely to catch",
      "depends_on": ["S004"],
      "files": ["README.md"],
      "tasks": [
        "Introduce a subtle error (grammar, inconsistent formatting, broken link, or similar) that CodeRabbit would flag",
        "Push branch and create PR",
        "Wait for CodeRabbit review",
        "Use /tackle-pr-comment on the CodeRabbit feedback",
        "Copy all PR-comment artifacts to demo/"
      ]
    },
    {
      "id": "S006",
      "title": "Wrap up with /finish-issue",
      "status": "done",
      "done_when": "/finish-issue generates PR description, all demo artifacts collected, TIMELINE.md complete",
      "depends_on": ["S005"],
      "files": [
        "demo/real-life/issues-10/TIMELINE.md"
      ],
      "tasks": [
        "Run /finish-issue to generate PR description",
        "Copy generated PR description scratchpad to demo/",
        "Finalize TIMELINE.md with complete narrative",
        "Review all demo/ artifacts for completeness — folder listing matches TIMELINE.md 1:1",
        "Update README section 4 links if any artifact filenames changed during the process"
      ]
    }
  ]
}
```

## Assumptions Made

- Issue #10 stays bare on GitHub (as stated in design decisions) — the demo shows the full workflow starting from that minimal issue.
- CodeRabbit is active on this repo and will review PRs automatically. If not, we adapt the /tackle-pr-comment demo using a rangeLink PR as reference (per user's suggestion).
- Pre-planning scratchpads (0004, 0005) and question files (0001, 0002) live at root `.scratchpads/` and `.claude-questions/` since they were created before the issue branch. This scratchpad and all future artifacts are scoped to `.scratchpads/issues/10/`.
- TIMELINE.md is updated after every exchange — it's the one file in demo/ that's modified in place rather than versioned.
- The README content references demo artifacts by their final filenames. Since we add artifacts incrementally and filenames include global sequence numbers, the README's "See It In Action" section may need a final pass to update links once all artifacts exist.

## Files to Modify

**S001-S004:** README.md (iterative rewrites)
**S005:** README.md (intentional error), then PR creation
**S006:** demo/real-life/issues-10/TIMELINE.md (finalization)

## Documentation & Discoverability

- [x] README update — this IS the README update
- [ ] CHANGELOG entry — not applicable (no code changes, documentation only)
- [ ] skills/README.md — may need minor updates if root README restructures the reference section
- [ ] install.sh — no changes needed

## Acceptance Criteria

- [ ] README has all 8 sections: hook, install, quick start, full workflow, philosophy, reference, contributing, resources
- [ ] All demo artifacts in demo/real-life/issues-10/ follow the naming convention
- [ ] TIMELINE.md entries match demo folder contents 1:1
- [ ] Mermaid diagram renders correctly on GitHub
- [ ] Official Claude Code skills documentation is linked (inline + resources section)
- [ ] `<details>` blocks expand correctly on GitHub
- [ ] At least one /tackle-pr-comment cycle captured in demo/

# my-claude-skills

Claude Code is powerful, but out of the box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. `/scratchpad` + `/question` — explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. `/breadcrumb` + `/start-side-quest` — handle detours without derailing

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Why I Built These

I've used Claude Code on dozens of real issues and kept running into the same friction points. These skills encode the patterns that worked:

- **Files over chat.** Every decision, plan, and question lives in a file — not buried in terminal scroll. If you use [RangeLink](https://github.com/couimet/rangeLink) or similar tools, the file references become clickable navigation.
- **Crash-proof context.** Claude Code sessions can compact, disconnect, or run out of context. Because everything is written to disk as it happens, you can resume from any scratchpad in a fresh session without losing anything.
- **Organized, not scattered.** Working files go in predictable locations (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) with auto-numbering and issue-scoped subdirectories. No manual file management.
- **You control execution.** Claude proposes plans and drafts commit messages. You review, edit, and execute. No auto-commits, no surprise pushes, no "let me just fix that for you."
- **Ephemeral vs. permanent.** Working files are git-ignored — they're your private workspace. Only real code and documentation get committed. This distinction is enforced by convention, not tooling.
- **Plan, then execute.** `/start-issue` creates the plan. `/tackle-scratchpad-block` executes one step at a time. The plan is always visible, always editable, always the source of truth for what's left to do.
- **No magic.** These are plain markdown files that Claude reads as instructions. There's no framework, no runtime, no dependencies. Fork the repo, edit a `SKILL.md`, and changes take effect immediately — symlinks mean edits are picked up without re-running anything. You only run `install.sh` again when adding or removing skills.

## Skills Reference

### What You Type

| Command | What It Does |
| --- | --- |
| `/scratchpad <desc>` | Create a working document — plans, analysis, PR drafts, anything temporary |
| `/question <topic>` | Surface design decisions as a structured Q&A file you edit in-place |
| `/commit-msg <desc>` | Draft a commit message focused on WHY, not WHAT |
| `/breadcrumb <note>` | Drop a timestamped note collected by `/finish-issue` for the PR description |
| `/start-issue <url>` | Analyze a GitHub issue, create a branch, and produce an implementation plan |
| `/tackle-scratchpad-block <path#lines>` | Execute a specific step from a plan — the core implementation loop |
| `/start-side-quest <desc>` | Branch off for an orthogonal improvement without polluting the current issue |
| `/tackle-pr-comment <url>` | Analyze PR feedback and create a plan to address it |
| `/finish-issue` | Verify work, collect breadcrumbs, check docs, and generate a PR description |

### What Works Automatically

These skills aren't invoked directly — Claude consults them when the context matches.

| Skill | When It Activates |
| --- | --- |
| `code-ref` | When generating file/line references — formats them as GitHub-style permalinks, clickable in editors with [RangeLink](https://github.com/couimet/rangeLink) installed (VS Code/Cursor don't recognize the suffix natively) |
| `file-placement` | When deciding where to put a new file — routes to the right directory |
| `issue-context` | When on an `issues/<N>` branch — scopes working files to issue subdirectories |
| `prose-style` | When writing prose to working files — applies consistent formatting conventions |

For architecture details, the two-tier design, and step tracking schema, see [skills/README.md](skills/README.md).

## Making These Your Own

These skills are designed to be forked and adapted. Each skill is a standalone `SKILL.md` file — plain markdown with instructions Claude follows. There's no coupling between them beyond naming conventions.

To customize:

1. **Fork this repo** and clone it locally
2. **Edit any `SKILL.md`** in `skills/` — changes take effect immediately through symlinks
3. **Add new skills** by creating a new directory under `skills/` with a `SKILL.md`, then re-run `install.sh`
4. **Remove skills** by deleting the directory and re-running `install.sh`

If you build something useful, PRs are welcome. These skills evolved from my own workflow friction — yours will be different, and that's the point.

## Resources

- [Claude Code skills documentation](https://code.claude.com/docs/en/skills) — the official guide to how skills work, including the `SKILL.md` format spec
- [Claude Code documentation](https://code.claude.com/docs/en/) — full Claude Code reference
- [skills/README.md](skill/README.md) — this repo's skill inventory, architecture notes, and step tracking schema
- [RangeLink](https://github.com/couimet/rangeLink) — VS Code/Cursor extension that makes `file#line` references clickable (used throughout these skills via the `code-ref` convention)

Everything here builds on Claude Code's official skills system — we're not inventing a framework, just adding conventions on top of what Anthropic already provides.

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3826186415

## Reviewer Feedback Summary

CodeRabbit's automated review flagged 11 items across README.md and demo snapshot files: a broken link (our intentional bait), two hyphenation fixes, missing language identifiers on 9 fenced code blocks, and duplicate suggestions for 6 historical README snapshots in the demo folder.

## Analysis

### Feedback A: Broken link `skill/README.md` in Resources section

README.md#L315 links to `skill/README.md` instead of `skills/README.md`. This was our intentional bait for CodeRabbit (planted in Exchange 17 / S005), and it successfully caught it.

Decision: ACCEPT
Reason: The bait served its purpose -- CodeRabbit found it. Time to fix the broken link so the README actually works.

### Feedback B: Hyphenate "out of the box" as compound modifier

README.md#L3 uses "out of the box sessions" where "out-of-the-box" is a compound adjective modifying "sessions." Standard English grammar requires hyphenation.

Decision: ACCEPT
Reason: CodeRabbit is correct -- compound adjectives before a noun take hyphens.

### Feedback C: Hyphenate "step tracking" as compound modifier

README.md#L296 uses "step tracking schema" where "step-tracking" modifies "schema." Same grammar rule as Feedback B.

Decision: ACCEPT
Reason: Consistent with accepting B -- both are compound modifiers.

### Feedback D: MD040 -- Missing language identifiers on fenced code blocks

9 fenced code blocks in README.md use bare ``` instead of ```json, ```text, or ```bash. Markdownlint rule MD040 requires language identifiers for accessibility and syntax highlighting.

Decision: ACCEPT
Reason: Language identifiers improve readability on GitHub (syntax highlighting) and are a low-effort improvement.

### Feedback E: Same issues flagged in demo snapshot files

CodeRabbit flagged the same broken link, hyphenation, and MD040 issues in 6 historical README snapshots: 0011, 0015, 0018, 0021, 0023, 0027. These are frozen-in-time artifacts that document the README's evolution.

Decision: IGNORE
Reason: Demo snapshots are historical records -- they capture the README as it existed at each point in time. Retroactively "fixing" them would destroy the chronological record and undermine the entire demo's purpose. The final README (committed at the end) contains the fixes; the snapshots show the journey.

### Feedback F: Truncated A005 in question file 0005

`demo/real-life/issues-10/0005--question--0002-demo-approach-v0002.txt` has A005 ending mid-sentence: "...decided in" with no completion. This is the user's raw answer captured verbatim.

Decision: IGNORE
Reason: The question file captures the user's actual response as-is. The truncation is authentic -- the user trailed off or was interrupted. Editing it would falsify the historical record.

### Feedback G: Stale artifact count "29" in finish-issue scratchpad

`demo/real-life/issues-10/0030--scratchpad--0002-finish-issue-10-v0001.txt` references "29 chronologically numbered artifacts" but the folder now has 34+.

Decision: IGNORE
Reason: The PR description scratchpad was generated when there were 29 artifacts. It's a snapshot of that moment. The count will be updated in the actual PR description if needed, not in the historical artifact.

### Feedback H: Stray backtick in commit message 0034

`demo/real-life/issues-10/0034--commit-msg--0010-consistent-walkthrough-headings-v0001.txt` line 3 has an unmatched backtick: "the pattern `/skill-name` — description`" -- the trailing backtick after "description" is orphaned.

Decision: IGNORE
Reason: The actual git commit contains the same stray backtick. The demo artifact is an accurate copy of the committed message -- modifying it would falsify the historical record, same logic as the README snapshots.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix broken link and hyphenation in README.md",
      "status": "pending",
      "done_when": "README.md line 315 links to skills/README.md, line 3 uses out-of-the-box, line 296 uses step-tracking",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Fix README.md#L315: change (skill/README.md) to (skills/README.md)",
        "Fix README.md#L3: change 'out of the box sessions' to 'out-of-the-box sessions'",
        "Fix README.md#L296: change 'step tracking schema' to 'step-tracking schema'"
      ],
      "addresses": ["A", "B", "C"]
    },
    {
      "id": "S002",
      "title": "Add language identifiers to all fenced code blocks in README.md",
      "status": "pending",
      "done_when": "All 9 bare fenced code blocks have language identifiers (text, json, or bash as appropriate)",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Audit all fenced code blocks in README.md",
        "Add appropriate language identifier to each: text for plain scratchpad content, json for JSON blocks, bash for shell commands"
      ],
      "addresses": ["D"]
    },
  ]
}
```

## Recommendations

All three steps are independent and straightforward. S001 and S002 both touch README.md but different parts, so they can be combined into a single commit. S003 is a standalone fix to a demo artifact.

S001 and S002 both touch README.md but different parts. Recommend a single commit addressing all README.md fixes.

## Files to Modify

- `README.md` -- fix broken link, hyphenation, and add language identifiers (S001, S002)

# my-claude-skills

Claude Code is powerful, but out-of-the-box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. `/scratchpad` + `/question` — explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. `/breadcrumb` + `/start-side-quest` — handle detours without derailing

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Why I Built These

I've used Claude Code on dozens of real issues and kept running into the same friction points. These skills encode the patterns that worked:

- **Files over chat.** Every decision, plan, and question lives in a file — not buried in terminal scroll. If you use [RangeLink](https://github.com/couimet/rangeLink) or similar tools, the file references become clickable navigation.
- **Crash-proof context.** Claude Code sessions can compact, disconnect, or run out of context. Because everything is written to disk as it happens, you can resume from any scratchpad in a fresh session without losing anything.
- **Organized, not scattered.** Working files go in predictable locations (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) with auto-numbering and issue-scoped subdirectories. No manual file management.
- **You control execution.** Claude proposes plans and drafts commit messages. You review, edit, and execute. No auto-commits, no surprise pushes, no "let me just fix that for you."
- **Ephemeral vs. permanent.** Working files are git-ignored — they're your private workspace. Only real code and documentation get committed. This distinction is enforced by convention, not tooling.
- **Plan, then execute.** `/start-issue` creates the plan. `/tackle-scratchpad-block` executes one step at a time. The plan is always visible, always editable, always the source of truth for what's left to do.
- **No magic.** These are plain markdown files that Claude reads as instructions. There's no framework, no runtime, no dependencies. Fork the repo, edit a `SKILL.md`, and changes take effect immediately — symlinks mean edits are picked up without re-running anything. You only run `install.sh` again when adding or removing skills.

## Skills Reference

### What You Type

| Command | What It Does |
| --- | --- |
| `/scratchpad <desc>` | Create a working document — plans, analysis, PR drafts, anything temporary |
| `/question <topic>` | Surface design decisions as a structured Q&A file you edit in-place |
| `/commit-msg <desc>` | Draft a commit message focused on WHY, not WHAT |
| `/breadcrumb <note>` | Drop a timestamped note collected by `/finish-issue` for the PR description |
| `/start-issue <url>` | Analyze a GitHub issue, create a branch, and produce an implementation plan |
| `/tackle-scratchpad-block <path#lines>` | Execute a specific step from a plan — the core implementation loop |
| `/start-side-quest <desc>` | Branch off for an orthogonal improvement without polluting the current issue |
| `/tackle-pr-comment <url>` | Analyze PR feedback and create a plan to address it |
| `/finish-issue` | Verify work, collect breadcrumbs, check docs, and generate a PR description |

### What Works Automatically

These skills aren't invoked directly — Claude consults them when the context matches.

| Skill | When It Activates |
| --- | --- |
| `code-ref` | When generating file/line references — formats them as GitHub-style permalinks, clickable in editors with [RangeLink](https://github.com/couimet/rangeLink) installed (VS Code/Cursor don't recognize the suffix natively) |
| `file-placement` | When deciding where to put a new file — routes to the right directory |
| `issue-context` | When on an `issues/<N>` branch — scopes working files to issue subdirectories |
| `prose-style` | When writing prose to working files — applies consistent formatting conventions |

For architecture details, the two-tier design, and step-tracking schema, see [skills/README.md](skills/README.md).

## Making These Your Own

These skills are designed to be forked and adapted. Each skill is a standalone `SKILL.md` file — plain markdown with instructions Claude follows. There's no coupling between them beyond naming conventions.

To customize:

1. **Fork this repo** and clone it locally
2. **Edit any `SKILL.md`** in `skills/` — changes take effect immediately through symlinks
3. **Add new skills** by creating a new directory under `skills/` with a `SKILL.md`, then re-run `install.sh`
4. **Remove skills** by deleting the directory and re-running `install.sh`

If you build something useful, PRs are welcome. These skills evolved from my own workflow friction — yours will be different, and that's the point.

## Resources

- [Claude Code skills documentation](https://code.claude.com/docs/en/skills) — the official guide to how skills work, including the `SKILL.md` format spec
- [Claude Code documentation](https://code.claude.com/docs/en/) — full Claude Code reference
- [skills/README.md](skills/README.md) — this repo's skill inventory, architecture notes, and step tracking schema
- [RangeLink](https://github.com/couimet/rangeLink) — VS Code/Cursor extension that makes `file#line` references clickable (used throughout these skills via the `code-ref` convention)

Everything here builds on Claude Code's official skills system — we're not inventing a framework, just adding conventions on top of what Anthropic already provides.

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3826186415

## Reviewer Feedback Summary

CodeRabbit's automated review flagged 11 items across README.md and demo snapshot files: a broken link (our intentional bait), two hyphenation fixes, missing language identifiers on 9 fenced code blocks, and duplicate suggestions for 6 historical README snapshots in the demo folder.

## Analysis

### Feedback A: Broken link `skill/README.md` in Resources section

README.md#L315 links to `skill/README.md` instead of `skills/README.md`. This was our intentional bait for CodeRabbit (planted in Exchange 17 / S005), and it successfully caught it.

Decision: ACCEPT
Reason: The bait served its purpose -- CodeRabbit found it. Time to fix the broken link so the README actually works.

### Feedback B: Hyphenate "out of the box" as compound modifier

README.md#L3 uses "out of the box sessions" where "out-of-the-box" is a compound adjective modifying "sessions." Standard English grammar requires hyphenation.

Decision: ACCEPT
Reason: CodeRabbit is correct -- compound adjectives before a noun take hyphens.

### Feedback C: Hyphenate "step tracking" as compound modifier

README.md#L296 uses "step tracking schema" where "step-tracking" modifies "schema." Same grammar rule as Feedback B.

Decision: ACCEPT
Reason: Consistent with accepting B -- both are compound modifiers.

### Feedback D: MD040 -- Missing language identifiers on fenced code blocks

9 fenced code blocks in README.md use bare ``` instead of ```json, ```text, or ```bash. Markdownlint rule MD040 requires language identifiers for accessibility and syntax highlighting.

Decision: ACCEPT
Reason: Language identifiers improve readability on GitHub (syntax highlighting) and are a low-effort improvement.

### Feedback E: Same issues flagged in demo snapshot files

CodeRabbit flagged the same broken link, hyphenation, and MD040 issues in 6 historical README snapshots: 0011, 0015, 0018, 0021, 0023, 0027. These are frozen-in-time artifacts that document the README's evolution.

Decision: IGNORE
Reason: Demo snapshots are historical records -- they capture the README as it existed at each point in time. Retroactively "fixing" them would destroy the chronological record and undermine the entire demo's purpose. The final README (committed at the end) contains the fixes; the snapshots show the journey.

### Feedback F: Truncated A005 in question file 0005

`demo/real-life/issues-10/0005--question--0002-demo-approach-v0002.txt` has A005 ending mid-sentence: "...decided in" with no completion. This is the user's raw answer captured verbatim.

Decision: IGNORE
Reason: The question file captures the user's actual response as-is. The truncation is authentic -- the user trailed off or was interrupted. Editing it would falsify the historical record.

### Feedback G: Stale artifact count "29" in finish-issue scratchpad

`demo/real-life/issues-10/0030--scratchpad--0002-finish-issue-10-v0001.txt` references "29 chronologically numbered artifacts" but the folder now has 34+.

Decision: IGNORE
Reason: The PR description scratchpad was generated when there were 29 artifacts. It's a snapshot of that moment. The count will be updated in the actual PR description if needed, not in the historical artifact.

### Feedback H: Stray backtick in commit message 0034

`demo/real-life/issues-10/0034--commit-msg--0010-consistent-walkthrough-headings-v0001.txt` line 3 has an unmatched backtick: "the pattern `/skill-name` — description`" -- the trailing backtick after "description" is orphaned.

Decision: IGNORE
Reason: The actual git commit contains the same stray backtick. The demo artifact is an accurate copy of the committed message -- modifying it would falsify the historical record, same logic as the README snapshots.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix broken link and hyphenation in README.md",
      "status": "done",
      "done_when": "README.md line 315 links to skills/README.md, line 3 uses out-of-the-box, line 296 uses step-tracking",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Fix README.md#L315: change (skill/README.md) to (skills/README.md)",
        "Fix README.md#L3: change 'out of the box sessions' to 'out-of-the-box sessions'",
        "Fix README.md#L296: change 'step tracking schema' to 'step-tracking schema'"
      ],
      "addresses": ["A", "B", "C"]
    },
    {
      "id": "S002",
      "title": "Add language identifiers to all fenced code blocks in README.md",
      "status": "pending",
      "done_when": "All 9 bare fenced code blocks have language identifiers (text, json, or bash as appropriate)",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Audit all fenced code blocks in README.md",
        "Add appropriate language identifier to each: text for plain scratchpad content, json for JSON blocks, bash for shell commands"
      ],
      "addresses": ["D"]
    },
  ]
}
```

## Recommendations

All three steps are independent and straightforward. S001 and S002 both touch README.md but different parts, so they can be combined into a single commit. S003 is a standalone fix to a demo artifact.

S001 and S002 both touch README.md but different parts. Recommend a single commit addressing all README.md fixes.

## Files to Modify

- `README.md` -- fix broken link, hyphenation, and add language identifiers (S001, S002)

# my-claude-skills

Claude Code is powerful, but out-of-the-box sessions are ephemeral — context evaporates between tasks, there's no trail of decisions made along the way, and commit messages end up as whatever the AI felt like writing. I built these skills because I wanted Claude to be a structured development partner, not just a code generator.

This is a collection of portable [Claude Code skills](https://code.claude.com/docs/en/skills) that add lightweight workflow conventions to every project I work on. They've been iterated over many real issues, PR reviews, and side-quests. Nothing here is theoretical — I use every one of these daily.

## Installation

```bash
git clone git@github.com:couimet/my-claude-skills.git ~/src/my-claude-skills
~/src/my-claude-skills/install.sh
```

This creates symlinks from `~/.claude/skills/` to the repo, making all skills globally available in every Claude Code project. Skills are the [standard Claude Code extension mechanism](https://code.claude.com/docs/en/skills) — each one is a markdown file with instructions that Claude follows when you invoke it.

### Updating

```bash
cd ~/src/my-claude-skills && git pull && ./install.sh
```

The install script is idempotent — safe to run on every pull. It only creates/updates symlinks; it never deletes non-symlink directories.

## Quick Start

Once installed, try these in any project:

### `/scratchpad` — Create a working document

```text
/scratchpad plan the authentication refactor
```

Creates a `.scratchpads/0001-plan-the-authentication-refactor.txt` file with structured step tracking. The file is git-ignored — it's your private workspace.

<details>
<summary>See a real scratchpad from this repo</summary>

```text
Issue #10 — Add Meat to README: Enrichment Plan

This scratchpad analyzes the current README state and suggests ways
to enrich issue #10 before implementation.

## Gap Analysis

### What's Missing for Beginners
- No explanation of what Claude Code skills even are
- No "what problem does this solve?" framing
- No gentle walkthrough of a first use

### What's Missing for Advanced Users
- No real-world workflow scenarios showing skills composing together
- No illustration of the full issue lifecycle
...
```

Full file: [demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt](demo/real-life/issues-10/0001--scratchpad--0004-readme-enrichment-plan-v0001.txt)

</details>

### `/question` — Gather design decisions

```text
/question authentication strategy choices
```

Creates a `.claude-questions/0001-authentication-strategy-choices.txt` with structured Q&A. Claude pre-fills recommendations; you edit answers in-file as the single source of truth.

<details>
<summary>See a real question file from this repo</summary>

```text
## Q001: Should the root README be the single comprehensive document,
         or should it stay lean and link to deeper pages?

Context: The current README is 25 lines pointing to skills/README.md.

Options:
A) Single comprehensive README - Everything in one scrollable document.
B) Hub-and-spoke - Root README covers intro, link out for details.
C) Progressive disclosure - Heavy use of GitHub's <details> blocks.

Recommendation: A - A single comprehensive README is the most welcoming.

A001: [RECOMMENDED] A
```

Full file: [demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt)

</details>

### `/commit-msg` — Draft a commit message

```text
/commit-msg add authentication middleware
```

Creates a `.commit-msgs/0001-add-authentication-middleware.txt` focused on WHY, not WHAT — the diff already shows what changed. You review and commit manually; Claude never auto-commits.

<details>
<summary>See a real commit message from this repo</summary>

```text
[docs] Bootstrap demo infrastructure and start-issue plan for README overhaul

Establishes the "eat your own dog food" approach: issue #10's own workflow
becomes the README's walkthrough demo. All ephemeral skill artifacts are
persisted in demo/real-life/issues-10/ with a naming convention that makes
the folder a visual timeline.

Benefits:
- Real artifacts replace fabricated examples
- Chronological folder listing tells the story without opening any file
- TIMELINE.md provides narrative context for the full follow-along
```

Full file: [demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt](demo/real-life/issues-10/0010--commit-msg--0001-bootstrap-demo-and-start-issue-v0001.txt)

</details>

All working files (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) are git-ignored automatically. They're your private workspace — only real code and docs get committed.

## See It In Action

These skills aren't meant to be used in isolation — they compose into a full issue lifecycle. Here's the flow:

```mermaid
graph LR
    A["/start-issue"] --> B["/tackle-scratchpad-block"]
    B --> C{More steps?}
    C -- yes --> B
    C -- no --> D["/finish-issue"]
    B -.-> E["/breadcrumb"]
    B -.-> F["/start-side-quest"]
    B -.-> G["/question"]
    F --> B
```

Every artifact linked below is real — generated while building the README you're reading right now ([issue #10](https://github.com/couimet/my-claude-skills/issues/10)). The full unredacted history lives in [`demo/real-life/issues-10/`](demo/real-life/issues-10/).

### 1. `/scratchpad` + `/question` — explore before committing to a plan

Before any branch existed, I used `/scratchpad` to analyze the bare issue and `/question` to surface 12 design decisions. The questions file captures things like: should the README be one page or hub-and-spoke? Real examples or fabricated ones? What tone?

The user answered all 12 questions by editing the file directly — that's the contract. Claude pre-fills `[RECOMMENDED]` answers; the user removes that marker to acknowledge or changes the answer entirely.

<details>
<summary>See how a question evolves from asked to answered</summary>

**Before (Claude's question):**
```text
## Q003: Should inline examples use real artifacts from this repo
         or fabricated/generic snippets?

Options:
A) Real artifacts - Actual files from this repo's own workflow.
B) Fabricated - Carefully crafted examples for maximum clarity.
C) Mix - Real artifacts for advanced, fabricated for beginner.

Recommendation: A - Real artifacts are more compelling.

A003: [RECOMMENDED] A
```

**After (user's answer — a game-changer):**
```text
A003: A; I'd like to take it further — use the current conversation
as the demo. "Eat your own dog food." Leave issue #10 bare as-is
and build the full-cycle demo from it...
```

Full files: [before](demo/real-life/issues-10/0002--question--0001-readme-design-decisions-v0001.txt) → [after](demo/real-life/issues-10/0003--question--0001-readme-design-decisions-v0002.txt)

</details>

### 2. `/start-issue` — branch + implementation plan

Once design decisions were resolved, `/start-issue` created the `issues/10` branch and produced a formal implementation plan with 6 JSON-tracked steps. Each step has a status (`pending` → `in_progress` → `done`), concrete completion criteria, dependencies, and file lists.

<details>
<summary>See the implementation plan structure</summary>

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Write README sections 1-3: opening hook, installation, quick start",
      "status": "done",
      "done_when": "README.md has problem-statement hook, updated installation...",
      "depends_on": [],
      "files": ["README.md"]
    },
    {
      "id": "S002",
      "title": "Write README section 4: full workflow walkthrough with Mermaid diagram",
      "status": "in_progress",
      "depends_on": ["S001"]
    }
  ]
}
```

Full file: [demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt)

</details>

### 3. `/tackle-scratchpad-block` — execute one step at a time

This is the core loop. You point Claude at a specific step using a code reference — a file path with line numbers:

```text
/tackle-scratchpad-block .scratchpads/issues/10/0001-start-issue-plan.txt#L26-L41
```

Claude reads the step, checks its status and dependencies, marks it `in_progress`, executes the work, runs tests, marks it `done`, and drafts a commit message. You review everything and commit manually.

The precision matters: you choose which step to work on, and Claude reads the surrounding plan for context. No ambiguity about what's being requested.

<details>
<summary>See a step transition from pending to done</summary>

**Before executing S001:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "pending",
```

**After execution:**
```json
"id": "S001",
"title": "Write README sections 1-3: opening hook, installation, quick start",
"status": "done",
```

Compare: [before](demo/real-life/issues-10/0009--scratchpad--0001-start-issue-plan-v0001.txt) → [after](demo/real-life/issues-10/0013--scratchpad--0001-start-issue-plan-v0002.txt)

</details>

### 4. `/breadcrumb` + `/start-side-quest` — handle detours without derailing

Mid-issue, you'll often notice orthogonal improvements — a helper function that deserves its own PR, a naming inconsistency worth fixing. Instead of polluting the current branch:

- **`/breadcrumb`** drops a timestamped note that `/finish-issue` collects later
- **`/start-side-quest`** creates a separate branch, tracks the detour, and returns you to the main issue when done

### 5. `/finish-issue` — wrap up with a PR description

When all steps are done, `/finish-issue` verifies the work, collects breadcrumbs, checks documentation needs, and generates a PR description. The description links back to the plan and summarizes what was done and why.

### Following along

The [`demo/real-life/issues-10/`](demo/real-life/issues-10/) folder contains every artifact from this issue's lifecycle — scratchpads, questions, commit messages, and README snapshots — numbered chronologically. [`TIMELINE.md`](demo/real-life/issues-10/TIMELINE.md) provides the narrative context for each one.

## Why I Built These

I've used Claude Code on dozens of real issues and kept running into the same friction points. These skills encode the patterns that worked:

- **Files over chat.** Every decision, plan, and question lives in a file — not buried in terminal scroll. If you use [RangeLink](https://github.com/couimet/rangeLink) or similar tools, the file references become clickable navigation.
- **Crash-proof context.** Claude Code sessions can compact, disconnect, or run out of context. Because everything is written to disk as it happens, you can resume from any scratchpad in a fresh session without losing anything.
- **Organized, not scattered.** Working files go in predictable locations (`.scratchpads/`, `.claude-questions/`, `.commit-msgs/`, `.breadcrumbs/`) with auto-numbering and issue-scoped subdirectories. No manual file management.
- **You control execution.** Claude proposes plans and drafts commit messages. You review, edit, and execute. No auto-commits, no surprise pushes, no "let me just fix that for you."
- **Ephemeral vs. permanent.** Working files are git-ignored — they're your private workspace. Only real code and documentation get committed. This distinction is enforced by convention, not tooling.
- **Plan, then execute.** `/start-issue` creates the plan. `/tackle-scratchpad-block` executes one step at a time. The plan is always visible, always editable, always the source of truth for what's left to do.
- **No magic.** These are plain markdown files that Claude reads as instructions. There's no framework, no runtime, no dependencies. Fork the repo, edit a `SKILL.md`, and changes take effect immediately — symlinks mean edits are picked up without re-running anything. You only run `install.sh` again when adding or removing skills.

## Skills Reference

### What You Type

| Command | What It Does |
| --- | --- |
| `/scratchpad <desc>` | Create a working document — plans, analysis, PR drafts, anything temporary |
| `/question <topic>` | Surface design decisions as a structured Q&A file you edit in-place |
| `/commit-msg <desc>` | Draft a commit message focused on WHY, not WHAT |
| `/breadcrumb <note>` | Drop a timestamped note collected by `/finish-issue` for the PR description |
| `/start-issue <url>` | Analyze a GitHub issue, create a branch, and produce an implementation plan |
| `/tackle-scratchpad-block <path#lines>` | Execute a specific step from a plan — the core implementation loop |
| `/start-side-quest <desc>` | Branch off for an orthogonal improvement without polluting the current issue |
| `/tackle-pr-comment <url>` | Analyze PR feedback and create a plan to address it |
| `/finish-issue` | Verify work, collect breadcrumbs, check docs, and generate a PR description |

### What Works Automatically

These skills aren't invoked directly — Claude consults them when the context matches.

| Skill | When It Activates |
| --- | --- |
| `code-ref` | When generating file/line references — formats them as GitHub-style permalinks, clickable in editors with [RangeLink](https://github.com/couimet/rangeLink) installed (VS Code/Cursor don't recognize the suffix natively) |
| `file-placement` | When deciding where to put a new file — routes to the right directory |
| `issue-context` | When on an `issues/<N>` branch — scopes working files to issue subdirectories |
| `prose-style` | When writing prose to working files — applies consistent formatting conventions |

For architecture details, the two-tier design, and step-tracking schema, see [skills/README.md](skills/README.md).

## Making These Your Own

These skills are designed to be forked and adapted. Each skill is a standalone `SKILL.md` file — plain markdown with instructions Claude follows. There's no coupling between them beyond naming conventions.

To customize:

1. **Fork this repo** and clone it locally
2. **Edit any `SKILL.md`** in `skills/` — changes take effect immediately through symlinks
3. **Add new skills** by creating a new directory under `skills/` with a `SKILL.md`, then re-run `install.sh`
4. **Remove skills** by deleting the directory and re-running `install.sh`

If you build something useful, PRs are welcome. These skills evolved from my own workflow friction — yours will be different, and that's the point.

## Resources

- [Claude Code skills documentation](https://code.claude.com/docs/en/skills) — the official guide to how skills work, including the `SKILL.md` format spec
- [Claude Code documentation](https://code.claude.com/docs/en/) — full Claude Code reference
- [skills/README.md](skills/README.md) — this repo's skill inventory, architecture notes, and step tracking schema
- [RangeLink](https://github.com/couimet/rangeLink) — VS Code/Cursor extension that makes `file#line` references clickable (used throughout these skills via the `code-ref` convention)

Everything here builds on Claude Code's official skills system — we're not inventing a framework, just adding conventions on top of what Anthropic already provides.

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3826186415

## Reviewer Feedback Summary

CodeRabbit's automated review flagged 11 items across README.md and demo snapshot files: a broken link (our intentional bait), two hyphenation fixes, missing language identifiers on 9 fenced code blocks, and duplicate suggestions for 6 historical README snapshots in the demo folder.

## Analysis

### Feedback A: Broken link `skill/README.md` in Resources section

README.md#L315 links to `skill/README.md` instead of `skills/README.md`. This was our intentional bait for CodeRabbit (planted in Exchange 17 / S005), and it successfully caught it.

Decision: ACCEPT
Reason: The bait served its purpose -- CodeRabbit found it. Time to fix the broken link so the README actually works.

### Feedback B: Hyphenate "out of the box" as compound modifier

README.md#L3 uses "out of the box sessions" where "out-of-the-box" is a compound adjective modifying "sessions." Standard English grammar requires hyphenation.

Decision: ACCEPT
Reason: CodeRabbit is correct -- compound adjectives before a noun take hyphens.

### Feedback C: Hyphenate "step tracking" as compound modifier

README.md#L296 uses "step tracking schema" where "step-tracking" modifies "schema." Same grammar rule as Feedback B.

Decision: ACCEPT
Reason: Consistent with accepting B -- both are compound modifiers.

### Feedback D: MD040 -- Missing language identifiers on fenced code blocks

9 fenced code blocks in README.md use bare ``` instead of ```json, ```text, or ```bash. Markdownlint rule MD040 requires language identifiers for accessibility and syntax highlighting.

Decision: ACCEPT
Reason: Language identifiers improve readability on GitHub (syntax highlighting) and are a low-effort improvement.

### Feedback E: Same issues flagged in demo snapshot files

CodeRabbit flagged the same broken link, hyphenation, and MD040 issues in 6 historical README snapshots: 0011, 0015, 0018, 0021, 0023, 0027. These are frozen-in-time artifacts that document the README's evolution.

Decision: IGNORE
Reason: Demo snapshots are historical records -- they capture the README as it existed at each point in time. Retroactively "fixing" them would destroy the chronological record and undermine the entire demo's purpose. The final README (committed at the end) contains the fixes; the snapshots show the journey.

### Feedback F: Truncated A005 in question file 0005

`demo/real-life/issues-10/0005--question--0002-demo-approach-v0002.txt` has A005 ending mid-sentence: "...decided in" with no completion. This is the user's raw answer captured verbatim.

Decision: IGNORE
Reason: The question file captures the user's actual response as-is. The truncation is authentic -- the user trailed off or was interrupted. Editing it would falsify the historical record.

### Feedback G: Stale artifact count "29" in finish-issue scratchpad

`demo/real-life/issues-10/0030--scratchpad--0002-finish-issue-10-v0001.txt` references "29 chronologically numbered artifacts" but the folder now has 34+.

Decision: IGNORE
Reason: The PR description scratchpad was generated when there were 29 artifacts. It's a snapshot of that moment. The count will be updated in the actual PR description if needed, not in the historical artifact.

### Feedback H: Stray backtick in commit message 0034

`demo/real-life/issues-10/0034--commit-msg--0010-consistent-walkthrough-headings-v0001.txt` line 3 has an unmatched backtick: "the pattern `/skill-name` — description`" -- the trailing backtick after "description" is orphaned.

Decision: IGNORE
Reason: The actual git commit contains the same stray backtick. The demo artifact is an accurate copy of the committed message -- modifying it would falsify the historical record, same logic as the README snapshots.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix broken link and hyphenation in README.md",
      "status": "done",
      "done_when": "README.md line 315 links to skills/README.md, line 3 uses out-of-the-box, line 296 uses step-tracking",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Fix README.md#L315: change (skill/README.md) to (skills/README.md)",
        "Fix README.md#L3: change 'out of the box sessions' to 'out-of-the-box sessions'",
        "Fix README.md#L296: change 'step tracking schema' to 'step-tracking schema'"
      ],
      "addresses": ["A", "B", "C"]
    },
    {
      "id": "S002",
      "title": "Add language identifiers to all fenced code blocks in README.md",
      "status": "done",
      "done_when": "All 9 bare fenced code blocks have language identifiers (text, json, or bash as appropriate)",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Audit all fenced code blocks in README.md",
        "Add appropriate language identifier to each: text for plain scratchpad content, json for JSON blocks, bash for shell commands"
      ],
      "addresses": ["D"]
    },
  ]
}
```

## Recommendations

All three steps are independent and straightforward. S001 and S002 both touch README.md but different parts, so they can be combined into a single commit. S003 is a standalone fix to a demo artifact.

S001 and S002 both touch README.md but different parts. Recommend a single commit addressing all README.md fixes.

## Files to Modify

- `README.md` -- fix broken link, hyphenation, and add language identifiers (S001, S002)

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3826186415

## Reviewer Feedback Summary

CodeRabbit's automated review flagged 11 items across README.md and demo snapshot files: a broken link (our intentional bait), two hyphenation fixes, missing language identifiers on 9 fenced code blocks, and duplicate suggestions for 6 historical README snapshots in the demo folder.

## Analysis

### Feedback A: Broken link `skill/README.md` in Resources section

README.md#L315 links to `skill/README.md` instead of `skills/README.md`. This was our intentional bait for CodeRabbit (planted in Exchange 17 / S005), and it successfully caught it.

Decision: ACCEPT
Reason: The bait served its purpose -- CodeRabbit found it. Time to fix the broken link so the README actually works.

### Feedback B: Hyphenate "out of the box" as compound modifier

README.md#L3 uses "out of the box sessions" where "out-of-the-box" is a compound adjective modifying "sessions." Standard English grammar requires hyphenation.

Decision: ACCEPT
Reason: CodeRabbit is correct -- compound adjectives before a noun take hyphens.

### Feedback C: Hyphenate "step tracking" as compound modifier

README.md#L296 uses "step tracking schema" where "step-tracking" modifies "schema." Same grammar rule as Feedback B.

Decision: ACCEPT
Reason: Consistent with accepting B -- both are compound modifiers.

### Feedback D: MD040 -- Missing language identifiers on fenced code blocks

9 fenced code blocks in README.md use bare ``` instead of ```json, ```text, or ```bash. Markdownlint rule MD040 requires language identifiers for accessibility and syntax highlighting.

Decision: ACCEPT
Reason: Language identifiers improve readability on GitHub (syntax highlighting) and are a low-effort improvement.

### Feedback E: Same issues flagged in demo snapshot files

CodeRabbit flagged the same broken link, hyphenation, and MD040 issues in 6 historical README snapshots: 0011, 0015, 0018, 0021, 0023, 0027. These are frozen-in-time artifacts that document the README's evolution.

Decision: IGNORE
Reason: Demo snapshots are historical records -- they capture the README as it existed at each point in time. Retroactively "fixing" them would destroy the chronological record and undermine the entire demo's purpose. The final README (committed at the end) contains the fixes; the snapshots show the journey.

### Feedback F: Truncated A005 in question file 0005

`demo/real-life/issues-10/0005--question--0002-demo-approach-v0002.txt` has A005 ending mid-sentence: "...decided in" with no completion. This is the user's raw answer captured verbatim.

Decision: IGNORE
Reason: The question file captures the user's actual response as-is. The truncation is authentic -- the user trailed off or was interrupted. Editing it would falsify the historical record.

### Feedback G: Stale artifact count "29" in finish-issue scratchpad

`demo/real-life/issues-10/0030--scratchpad--0002-finish-issue-10-v0001.txt` references "29 chronologically numbered artifacts" but the folder now has 34+.

Decision: IGNORE
Reason: The PR description scratchpad was generated when there were 29 artifacts. It's a snapshot of that moment. The count will be updated in the actual PR description if needed, not in the historical artifact.

### Feedback H: Stray backtick in commit message 0034

`demo/real-life/issues-10/0034--commit-msg--0010-consistent-walkthrough-headings-v0001.txt` line 3 has an unmatched backtick: "the pattern `/skill-name` — description`" -- the trailing backtick after "description" is orphaned.

Decision: IGNORE
Reason: The actual git commit contains the same stray backtick. The demo artifact is an accurate copy of the committed message -- modifying it would falsify the historical record, same logic as the README snapshots.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix broken link and hyphenation in README.md",
      "status": "done",
      "done_when": "README.md line 315 links to skills/README.md, line 3 uses out-of-the-box, line 296 uses step-tracking",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Fix README.md#L315: change (skill/README.md) to (skills/README.md)",
        "Fix README.md#L3: change 'out of the box sessions' to 'out-of-the-box sessions'",
        "Fix README.md#L296: change 'step tracking schema' to 'step-tracking schema'"
      ],
      "addresses": ["A", "B", "C"]
    },
    {
      "id": "S002",
      "title": "Add language identifiers to all fenced code blocks in README.md",
      "status": "done",
      "done_when": "All 9 bare fenced code blocks have language identifiers (text, json, or bash as appropriate)",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Audit all fenced code blocks in README.md",
        "Add appropriate language identifier to each: text for plain scratchpad content, json for JSON blocks, bash for shell commands"
      ],
      "addresses": ["D"]
    },
  ]
}
```

## Recommendations

S001 and S002 both touch README.md but different parts. Recommend a single commit addressing all README.md fixes.

## Files to Modify

- `README.md` -- fix broken link, hyphenation, and add language identifiers (S001, S002)

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3829645589

## Reviewer Feedback Summary

CodeRabbit's second review pass caught a stale Recommendations paragraph in the PR feedback scratchpad: the text still references "all three steps" and S003, even though S003 was removed when Feedback H was flipped from ACCEPT to IGNORE. The same stale text appears in 3 demo snapshot versions (0036, 0038, 0041) because it was present in the working scratchpad when each snapshot was taken.

## Analysis

### Feedback A: Stale S003 reference in Recommendations section of scratchpad 0036 (v0002)

The Recommendations section in 0036 has two paragraphs: the first says "All three steps are independent and straightforward... S003 is a standalone fix" while the second (updated in Exchange 23) correctly says only S001 and S002 remain. The first paragraph was missed during the S003 removal.

This is a genuine oversight in the working scratchpad that then propagated to demo copies.

Decision: ACCEPT
Reason: The working scratchpad still has the stale text and should be corrected. However, the fix only applies to the working file and the next demo copy forward -- not to historical snapshots.

### Feedback B: Same stale text in demo snapshots 0038 (v0003) and 0041 (v0004)

CodeRabbit flags the same stale paragraph in two later demo snapshots. These inherited the issue from the working scratchpad.

Decision: IGNORE
Reason: Demo snapshots are frozen-in-time records. They accurately capture the state of the working scratchpad at the moment they were taken -- including the oversight. Retroactively fixing them would falsify the historical record. The correction will appear in the next version (v0005).

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix stale Recommendations paragraph in working scratchpad",
      "status": "done",
      "done_when": "Recommendations section no longer references S003 or 'three steps'",
      "depends_on": [],
      "files": [".scratchpads/issues/10/0004-pr-11-review-3826186415.txt"],
      "tasks": [
        "Remove the stale first paragraph ('All three steps are independent...S003 is a standalone fix to a demo artifact.')",
        "The second paragraph already correctly describes the two-step plan"
      ],
      "addresses": ["A"]
    }
  ]
}
```

## Recommendations

Single-line fix: delete the stale paragraph. The second paragraph already captures the correct state.

## Files to Modify

- `.scratchpads/issues/10/0004-pr-11-review-3826186415.txt` -- remove stale Recommendations paragraph referencing S003

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3826186415

## Reviewer Feedback Summary

CodeRabbit's automated review flagged 11 items across README.md and demo snapshot files: a broken link (our intentional bait), two hyphenation fixes, missing language identifiers on 9 fenced code blocks, and duplicate suggestions for 6 historical README snapshots in the demo folder.

## Analysis

### Feedback A: Broken link `skill/README.md` in Resources section

README.md#L315 links to `skill/README.md` instead of `skills/README.md`. This was our intentional bait for CodeRabbit (planted in Exchange 17 / S005), and it successfully caught it.

Decision: ACCEPT
Reason: The bait served its purpose -- CodeRabbit found it. Time to fix the broken link so the README actually works.

### Feedback B: Hyphenate "out of the box" as compound modifier

README.md#L3 uses "out of the box sessions" where "out-of-the-box" is a compound adjective modifying "sessions." Standard English grammar requires hyphenation.

Decision: ACCEPT
Reason: CodeRabbit is correct -- compound adjectives before a noun take hyphens.

### Feedback C: Hyphenate "step tracking" as compound modifier

README.md#L296 uses "step tracking schema" where "step-tracking" modifies "schema." Same grammar rule as Feedback B.

Decision: ACCEPT
Reason: Consistent with accepting B -- both are compound modifiers.

### Feedback D: MD040 -- Missing language identifiers on fenced code blocks

9 fenced code blocks in README.md use bare ``` instead of ```json, ```text, or ```bash. Markdownlint rule MD040 requires language identifiers for accessibility and syntax highlighting.

Decision: ACCEPT
Reason: Language identifiers improve readability on GitHub (syntax highlighting) and are a low-effort improvement.

### Feedback E: Same issues flagged in demo snapshot files

CodeRabbit flagged the same broken link, hyphenation, and MD040 issues in 6 historical README snapshots: 0011, 0015, 0018, 0021, 0023, 0027. These are frozen-in-time artifacts that document the README's evolution.

Decision: IGNORE
Reason: Demo snapshots are historical records -- they capture the README as it existed at each point in time. Retroactively "fixing" them would destroy the chronological record and undermine the entire demo's purpose. The final README (committed at the end) contains the fixes; the snapshots show the journey.

### Feedback F: Truncated A005 in question file 0005

`demo/real-life/issues-10/0005--question--0002-demo-approach-v0002.txt` has A005 ending mid-sentence: "...decided in" with no completion. This is the user's raw answer captured verbatim.

Decision: IGNORE
Reason: The question file captures the user's actual response as-is. The truncation is authentic -- the user trailed off or was interrupted. Editing it would falsify the historical record.

### Feedback G: Stale artifact count "29" in finish-issue scratchpad

`demo/real-life/issues-10/0030--scratchpad--0002-finish-issue-10-v0001.txt` references "29 chronologically numbered artifacts" but the folder now has 34+.

Decision: IGNORE
Reason: The PR description scratchpad was generated when there were 29 artifacts. It's a snapshot of that moment. The count will be updated in the actual PR description if needed, not in the historical artifact.

### Feedback H: Stray backtick in commit message 0034

`demo/real-life/issues-10/0034--commit-msg--0010-consistent-walkthrough-headings-v0001.txt` line 3 has an unmatched backtick: "the pattern `/skill-name` — description`" -- the trailing backtick after "description" is orphaned.

Decision: IGNORE
Reason: The actual git commit contains the same stray backtick. The demo artifact is an accurate copy of the committed message -- modifying it would falsify the historical record, same logic as the README snapshots.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix broken link and hyphenation in README.md",
      "status": "done",
      "done_when": "README.md line 315 links to skills/README.md, line 3 uses out-of-the-box, line 296 uses step-tracking",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Fix README.md#L315: change (skill/README.md) to (skills/README.md)",
        "Fix README.md#L3: change 'out of the box sessions' to 'out-of-the-box sessions'",
        "Fix README.md#L296: change 'step tracking schema' to 'step-tracking schema'"
      ],
      "addresses": ["A", "B", "C"]
    },
    {
      "id": "S002",
      "title": "Add language identifiers to all fenced code blocks in README.md",
      "status": "done",
      "done_when": "All 9 bare fenced code blocks have language identifiers (text, json, or bash as appropriate)",
      "depends_on": [],
      "files": ["README.md"],
      "tasks": [
        "Audit all fenced code blocks in README.md",
        "Add appropriate language identifier to each: text for plain scratchpad content, json for JSON blocks, bash for shell commands"
      ],
      "addresses": ["D"]
    }
  ]
}
```

## Recommendations

S001 and S002 both touch README.md but different parts. Recommend a single commit addressing all README.md fixes.

## Files to Modify

- `README.md` -- fix broken link, hyphenation, and add language identifiers (S001, S002)

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3829680372

## Reviewer Feedback Summary

CodeRabbit's third review pass found 4 items: a trailing comma in the JSON block of the PR feedback scratchpad (invalid JSON), broken code spans in TIMELINE.md where inner backticks break rendering, and two prose wordiness nitpicks in demo scratchpad files.

## Analysis

### Feedback A: Trailing comma after last step in JSON block (scratchpad 0044)

The `"steps"` array in the working scratchpad's JSON block has a trailing comma after S002's closing brace (`},` followed by `]`). This makes the JSON technically invalid per RFC 8259. The same issue exists in the working scratchpad.

Decision: ACCEPT
Reason: Invalid JSON should be fixed in the working scratchpad. The demo copy 0044 is a snapshot and stays as-is.

### Feedback B: Broken code spans in TIMELINE.md lines 387, 409, 411-412

TIMELINE.md uses single backticks for heading patterns like `` `### N. `/skill-name` — brief description` `` but the inner backticks for `/skill-name` break the code span. CodeRabbit suggests double backticks to wrap the entire fragment.

Decision: ACCEPT
Reason: TIMELINE.md is a living document, not a frozen snapshot. Fixing the code spans improves readability.

### Feedback C: "at each point in time" wordiness in scratchpad 0044

LanguageTool flags "at each point in time" as redundant, suggesting "at each point" instead. CodeRabbit flagged the demo snapshot copy (0044), not the working scratchpad.

Decision: IGNORE
Reason: CodeRabbit reviewed the committed demo snapshot file, not the ephemeral working scratchpad. Working scratchpads are git-ignored and never committed -- polishing their prose based on feedback aimed at snapshot copies is busywork. The demo protocol creates new versioned copies going forward; it does not retroactively edit snapshots or their source files.

### Feedback D: "at the moment they were taken" wordiness in scratchpad 0045

LanguageTool flags "at the moment they were taken" as wordy, suggesting "when they were taken" instead. Same situation as Feedback C.

Decision: IGNORE
Reason: Same as C -- CodeRabbit flagged a demo snapshot, not the ephemeral working file. Prose polish on git-ignored scratchpads adds no value.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix trailing comma in working scratchpad 0004",
      "status": "done",
      "done_when": "JSON block has no trailing comma",
      "depends_on": [],
      "files": [".scratchpads/issues/10/0004-pr-11-review-3826186415.txt"],
      "tasks": [
        "Remove trailing comma after S002's closing brace (line 100: change `},` to `}`)"
      ],
      "addresses": ["A"]
    },
    {
      "id": "S002",
      "title": "Fix broken code spans in TIMELINE.md",
      "status": "pending",
      "done_when": "Lines 387, 409, 411, 412 use double backticks for heading patterns containing inner backticks",
      "depends_on": [],
      "files": ["demo/real-life/issues-10/TIMELINE.md"],
      "tasks": [
        "Replace single-backtick code spans with double-backtick spans where inner backticks appear",
        "Affects lines 387, 409, 411, 412 -- heading patterns like ### N. `/skill` — description"
      ],
      "addresses": ["B"]
    }
  ]
}
```

## Recommendations

S001 is done (trailing comma removed). S002 fixes rendering in TIMELINE.md. Prose nitpicks (C, D) ignored since they target ephemeral working files via their demo snapshot copies.

## Files to Modify

- `.scratchpads/issues/10/0004-pr-11-review-3826186415.txt` -- trailing comma fix (S001, done)
- `demo/real-life/issues-10/TIMELINE.md` -- double-backtick code spans (S002)

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3829680372

## Reviewer Feedback Summary

CodeRabbit's third review pass found 4 items: a trailing comma in the JSON block of the PR feedback scratchpad (invalid JSON), broken code spans in TIMELINE.md where inner backticks break rendering, and two prose wordiness nitpicks in demo scratchpad files.

## Analysis

### Feedback A: Trailing comma after last step in JSON block (scratchpad 0044)

The `"steps"` array in the working scratchpad's JSON block has a trailing comma after S002's closing brace (`},` followed by `]`). This makes the JSON technically invalid per RFC 8259. The same issue exists in the working scratchpad.

Decision: ACCEPT
Reason: Invalid JSON should be fixed in the working scratchpad. The demo copy 0044 is a snapshot and stays as-is.

### Feedback B: Broken code spans in TIMELINE.md lines 387, 409, 411-412

TIMELINE.md uses single backticks for heading patterns like `` `### N. `/skill-name` — brief description` `` but the inner backticks for `/skill-name` break the code span. CodeRabbit suggests double backticks to wrap the entire fragment.

Decision: ACCEPT
Reason: TIMELINE.md is a living document, not a frozen snapshot. Fixing the code spans improves readability.

### Feedback C: "at each point in time" wordiness in scratchpad 0044

LanguageTool flags "at each point in time" as redundant, suggesting "at each point" instead. CodeRabbit flagged the demo snapshot copy (0044), not the working scratchpad.

Decision: IGNORE
Reason: CodeRabbit reviewed the committed demo snapshot file, not the ephemeral working scratchpad. Working scratchpads are git-ignored and never committed -- polishing their prose based on feedback aimed at snapshot copies is busywork. The demo protocol creates new versioned copies going forward; it does not retroactively edit snapshots or their source files.

### Feedback D: "at the moment they were taken" wordiness in scratchpad 0045

LanguageTool flags "at the moment they were taken" as wordy, suggesting "when they were taken" instead. Same situation as Feedback C.

Decision: IGNORE
Reason: Same as C -- CodeRabbit flagged a demo snapshot, not the ephemeral working file. Prose polish on git-ignored scratchpads adds no value.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix trailing comma in working scratchpad 0004",
      "status": "done",
      "done_when": "JSON block has no trailing comma",
      "depends_on": [],
      "files": [".scratchpads/issues/10/0004-pr-11-review-3826186415.txt"],
      "tasks": [
        "Remove trailing comma after S002's closing brace (line 100: change `},` to `}`)"
      ],
      "addresses": ["A"]
    },
    {
      "id": "S002",
      "title": "Fix broken code spans in TIMELINE.md",
      "status": "done",
      "done_when": "Lines 387, 409, 411, 412 use double backticks for heading patterns containing inner backticks",
      "depends_on": [],
      "files": ["demo/real-life/issues-10/TIMELINE.md"],
      "tasks": [
        "Replace single-backtick code spans with double-backtick spans where inner backticks appear",
        "Affects lines 387, 409, 411, 412 -- heading patterns like ### N. `/skill` — description"
      ],
      "addresses": ["B"]
    }
  ]
}
```

## Recommendations

S001 is done (trailing comma removed). S002 fixes rendering in TIMELINE.md. Prose nitpicks (C, D) ignored since they target ephemeral working files via their demo snapshot copies.

## Files to Modify

- `.scratchpads/issues/10/0004-pr-11-review-3826186415.txt` -- trailing comma fix (S001, done)
- `demo/real-life/issues-10/TIMELINE.md` -- double-backtick code spans (S002)

# PR #11 Comment Response

Source: https://github.com/couimet/my-claude-skills/pull/11#pullrequestreview-3829795386

## Reviewer Feedback Summary

CodeRabbit's fourth review pass found 4 items: a stale "pending" status in demo artifact 0047, an "11 items" vs "12 items" count discrepancy in demo artifact 0048, a stale Exchange 28 narrative in TIMELINE.md that still describes the pre-correction plan, and a repeated prose wordiness nitpick on a demo snapshot.

## Analysis

### Feedback A: Stale "pending" status in 0047 scratchpad v0001 (line 49)

CodeRabbit flags that S001's status is "pending" in 0047 but the Recommendations section says S001 is done. It suggests changing the status to "done."

Decision: IGNORE
Reason: 0047 is the v0001 copy -- the "before" state. It intentionally shows S001 as `pending` so the diff to v0002 (0049) reveals only the status transition to `done`. CodeRabbit sees v0001 in isolation and misreads the stale-looking status. The versioning convention is working as designed.

### Feedback B: "11 items" count discrepancy in 0048 (line 7)

CodeRabbit flags that the summary says "11 items" but the breakdown (1 broken link + 2 hyphenation + 9 code fences) sums to 12. It suggests fixing the count.

Decision: IGNORE
Reason: 0048 is a frozen demo snapshot of working scratchpad 0004. Frozen snapshots are historical records that capture the file as it existed at a point in time. Retroactively fixing them would falsify the chronological record.

### Feedback C: Stale Exchange 28 narrative in TIMELINE.md (~lines 535-537)

Exchange 28 still reads: "All 4 items accepted. [...] Three steps: S001 fixes trailing comma + prose in scratchpad 0004, S002 fixes prose in scratchpad 0005, S003 fixes code spans in TIMELINE.md." This describes the pre-correction plan. The corrected plan has only 2 items accepted (A and B), 2 ignored (C and D), and 2 steps (S001 trailing comma, S002 code spans). We updated artifacts 0047-0050 when altering the past but missed the TIMELINE narrative and artifact description.

Decision: ACCEPT
Reason: TIMELINE.md is a living document. Exchange 28's narrative must match the corrected artifacts it references. This is a genuine oversight from our "altering the past" work.

### Feedback D: "at each point in time" wordiness in 0048 (line 44)

Same prose nitpick as the previous review (Feedback C in scratchpad 0006). LanguageTool flags "at each point in time" as redundant.

Decision: IGNORE
Reason: Same as before -- 0048 is a frozen demo snapshot. Prose polish on historical records adds no value.

Note: ACCEPT items flow to Implementation Plan steps. IGNORE items flow to the commit message's "Ignored Feedback" section.

## Implementation Plan

```json
{
  "steps": [
    {
      "id": "S001",
      "title": "Fix stale Exchange 28 narrative in TIMELINE.md",
      "status": "done",
      "done_when": "Exchange 28 reflects the corrected plan: 2 items accepted (A, B), 2 ignored (C, D), 2 steps (S001 trailing comma, S002 code spans), and artifact description no longer says 'all 4 items accepted'",
      "depends_on": [],
      "files": ["demo/real-life/issues-10/TIMELINE.md"],
      "tasks": [
        "Rewrite TIMELINE.md lines 535-537: replace 'All 4 items accepted' with accurate summary (A and B accepted, C and D ignored)",
        "Replace 'Three steps: S001...S003' with 'Two steps: S001 fixes trailing comma in scratchpad 0004, S002 fixes code spans in TIMELINE.md'",
        "Update artifact description on line 541: remove 'all 4 items accepted'"
      ],
      "addresses": ["C"]
    }
  ]
}
```

## Recommendations

S001 is a straightforward text correction in TIMELINE.md. The other three items (A, B, D) are all correctly ignored: A misunderstands the versioning convention, B and D target frozen demo snapshots.

## Files to Modify

- `demo/real-life/issues-10/TIMELINE.md` -- fix Exchange 28 narrative and artifact description (S001)