Compound

Compound Learnings

Save new patterns and learnings from the current session into global skills, guidelines, or learnings under ~/.claude/.

Usage

• /learnings:compound — Capture learnings from current session

Providers

Read ~/.claude/learnings-providers.json to discover available learning destinations. Each entry has:

• localPath — where files are written
• writeScope — which learning scope routes here (global or private)
• writable — whether this skill may write here
• defaultWriteTarget — the canonical Global destination

Scope routing:

• Global → provider with defaultWriteTarget: true (plus any other writeScope: "global", writable: true — multi-provider write)
• Private → provider with writeScope: "private" (e.g., ~/.claude/learnings-private)
• Project-local → projectLocal.path in the current project (resolved relative to project root)

Adding a new provider is just an edit to ~/.claude/learnings-providers.json. The ~/.claude/learnings*/** permission pattern covers any provider following the learnings-<name>/ naming convention.

Prerequisites

For prompt-free execution, add these allow patterns to user-level ~/.claude/settings.local.json:

"Read(~/.claude/commands/**)",
"Read(~/.claude/learnings-providers.json)",
"Read(~/.claude/learnings*/**)",
"Read(~/.claude/guidelines/**)",
"Write(~/.claude/learnings*/**)",
"Write(~/.claude/commands/**)",
"Write(~/.claude/guidelines/**)",
"Edit(~/.claude/learnings*/**)",
"Edit(~/.claude/commands/**)",
"Edit(~/.claude/guidelines/**)"

Reference Files (conditional — load only when needed)

• ~/.claude/learnings/claude-authoring/routing-table.md — categorization ambiguous
• skill-template.md + ~/.claude/learnings/claude-authoring-skills.md — authoring a new Skill
• iterative-loop-design.md — learning involves iterative/loop patterns
• public-release-review.md — learning will be shared publicly or across repos

Type Reference

Categorize each candidate against this table — it's the source of truth for routing, target paths, and write behavior.

Ambiguous type? Prefer Learning > Guideline > Skill (least to most structured).

Utility ratings (apply to Skill / Guideline / Learning — not Skill fix):

• High — Novel pattern OR proven pattern worth reinforcing/expanding → auto-write
• Medium — Useful reminder; could rediscover if needed → auto-write
• Low — Standard knowledge or already documented → shown for transparency, not written

Instructions

1. Identify candidates

• Review the conversation for new patterns, decisions that worked well, validated existing learnings, and every implemented change (edits, fixes, file writes). For each fix, ask "what did I need to know to make this change?"
• Categorize each candidate per the Type Reference. Assess scope for Learnings.
• Prefer extending an existing target file over creating a new one — bias toward consolidation when the topic overlaps existing keywords.
• Sniff each target file (Read(file, limit=80) or grep keywords) before finalizing utility. If an existing section already covers the pattern → downgrade utility (Medium → Low) or drop. Catches redundancy before the table is built. Skip when the target file doesn't exist yet.

2. Display and select

ALWAYS use a markdown table — never section breaks, horizontal rules, or prose paragraphs.

Identified learnings from this session:

| # | Description | Type | Scope | Target | Utility |
|---|-------------|------|-------|--------|---------|
| 1 | LGTM verification process | Skill | Global | ~/.claude/commands/address-pr-review/SKILL.md | High |
| 2 | Co-authorship in PR replies | Guideline | Global | ~/.claude/guidelines/git-workflow.md | Low |
| 3 | SessionEnd hook configuration | Learning | Global | ~/.claude/learnings/ci-cd.md | High |
| 4 | Step 10b skip when no workflows | Skill fix | -- | ~/.claude/commands/sweep/address-prs/addresser-prompt.md:~84 | -- |

After the table, announce:

Auto-writing N High/Medium learning(s). Skipping K Low. M Skill fix(es) require confirmation.

If nothing qualifies (no High/Medium AND no Skill fixes) → state so and exit. Otherwise proceed.

3. Write

Read each target before writing.

Skill fix path (per-fix, never batched, never auto-applied): 1. Read the target skill file to confirm current state at the cited line. 2. Draft the Edit (old_string / new_string) per the Conciseness gate below. 3. Present the proposed diff via AskUserQuestion with options Apply / Skip / Defer. 4. On Apply → Edit. On Skip → log "skill fix declined" with a one-line reason. On Defer → list in step 4 summary as "pending apply."

Auto-write path (Skill / Guideline / Learning):

• Existing file → Edit to append a new section (anchor on a unique trailing string).
• New file (Read returns error) → Write with full content.
• Multi-provider (Learnings only): if multiple providers have writeScope: "global" and writable: true, write to each. For new files in additional providers, add an index entry to that provider's CLAUDE.md (` - filename.md — one-line description ). Cross-refs in the copy use paths relative to that provider's localPath`. Single-provider setup → skip silently.

Conciseness gate (mandatory):

• One to two sentences per insight. A second sentence is fine for the "why" or a key caveat — if three are needed, split the insight.
• Lead with the rule, not the story. Drop "I discovered that…" framing.
• Use code or terse structure ( → , bullet fragments, tables) over prose when meaning is preserved.
• No hedging ("might", "could potentially"). State the pattern.
• Strip provenance — no "discovered while building X" / "learned during Y" notes. The pattern itself is what matters.
• Code examples are high-value, not verbosity. A 3-line working command beats a paragraph explaining the same thing.

4. Verify and report

Read back each written file to confirm. Output:

Updated files:
- <path> — <what was added> (Utility: <High/Medium>)
- <provider path> — multi-provider write (if applicable)
- <skill-file>:<line> — applied / declined / deferred (Skill fix)

Wrote N learnings. Applied K skill fixes (D declined, E deferred). Wrote M to additional providers.

Important Notes

• Keep learnings atomic — one concept per section.

Iterative Loop Design

Patterns for creating skills that use iterative AI loops (Ralph loops, research loops, etc.).

The Problem with Fixed Task Lists

A static list of 4 tasks with "ONE TASK PER ITERATION" means 4 iterations = done. The loop terminates before deeper investigation.

Design for extended autonomous operation rather than quick completion.

Expansion/Contraction Pattern

Design loops to follow a natural cycle:

1. Expansion Phase: Initial tasks generate "areas for deeper investigation" → agents add follow-up tasks → task list grows 2. Contraction Phase: Follow-up tasks complete → questions accumulate → task list shrinks 3. Termination: Only when genuinely blocked on operator input

Key Template Elements

1. Dynamic Task Generation Instructions

## Dynamic Task Generation

After completing research tasks, review findings for gaps.

**Add new tasks to Pending Tasks** when you identify:
- Topics in "Areas for Deeper Investigation" sections
- Assumptions needing validation
- Questions answerable with more research

Format:
- [ ] Deep Research: <topic> - <description>

2. Required "Questions for Operator" Section

## Questions Requiring Operator Input
<!--
REQUIRED before completion. Add genuine blocking questions:
- What decisions require operator judgment?
- What information only the operator can provide?

If empty, you haven't gone deep enough. Add more research tasks.
-->

3. Stricter Completion Criteria

## Completion

**Do NOT add completion signal until ALL true:**

1. All tasks complete (including dynamically added ones)
2. "Questions Requiring Operator Input" has genuine blocking questions
3. You cannot proceed further without operator input

**If no blocking questions**: Review research, add more deep research tasks, continue.

Why This Matters

Without these patterns, loops complete in predictable iterations (typically 4) regardless of research depth. With them, loops maximize autonomous progress before requiring operator intervention.

Reference Implementation

See .claude/commands/ralph/init/ for templates implementing this pattern.

Testing Long-Running Scripts

Add Timeout Parameters

For scripts that run continuously (monitors, watchers, polling loops), add an optional timeout parameter that auto-exits after a specified duration. This enables automated testing without requiring external process management.

# Example: Optional timeout in minutes (0 = run indefinitely)
TIMEOUT_MINUTES="${4:-0}"
START_TIME=$(date +%s)

while true; do
    if [ "$TIMEOUT_MINUTES" -gt 0 ]; then
        ELAPSED=$(( $(date +%s) - START_TIME ))
        if [ "$ELAPSED" -ge $(( TIMEOUT_MINUTES * 60 )) ]; then
            echo "Stopped after $TIMEOUT_MINUTES minute(s)"
            exit 0
        fi
    fi
    # ... rest of loop
done

Cross-Refs

• skill-template.md - Template and file organization for skills
• ~/.claude/learnings/claude-authoring-skills.md - Skill writing conventions and design patterns

Public Release Review

Pre-Publish Sanitization Checklist

Before making skills, commands, or documentation public, review all files for unintentional domain-specific leaks. These often hide in examples rather than instructions.

What to check

• Service/module names in example paths (e.g., my-internal-service/src/... should be backend/src/...)
• Domain-specific business terms in parenthetical examples (e.g., specific workflow names should be generic like "order lifecycle, approval flow")
• Internal URLs, hostnames, or API endpoints in examples or comments
• Team/org names or internal project identifiers
• Business logic references that reveal what the original codebase does

Where leaks hide

• Inline examples in instructions (e.g., e.g., ... parentheticals)
• Path format examples in agent prompts
• Sample output blocks
• ASCII diagrams with labeled components
• Comments explaining "why" with domain context

Fix approach

Replace with generic equivalents that preserve the teaching value without revealing the source domain.

Skill Template & File Organization

Reference for creating new skills and organizing skill files.

Skill Structure Template

---
description: One-line description of what the skill does
---

# Skill Name

One-line description of what the skill does.

## Usage

- `/skill-name` - Default behavior
- `/skill-name <arg>` - With argument
- `/skill-name --flag` - With option

## Reference Files (conditional — read only when needed)

- reference-file.md - Description of what it contains

## Instructions

1. **Step name**:
   - Explanation

command

2. **Next step**:
   ...

## Example Output (optional)

Example session showing typical usage

## Important Notes

- Caveats, warnings, edge cases

Skill File Organization

Standalone vs Directory Structure

Skills can be organized two ways:

Migrating to Directory Structure

When a skill grows to need reference files (templates, scripts, etc.):

1. Create directory: mkdir .claude/commands/skill-name/ 2. Move skill: mv .claude/commands/skill-name.md .claude/commands/skill-name/SKILL.md 3. Extract large content blocks into reference files (e.g., pr-body-template.md, init-script.sh) 4. Add ## Reference Files section with references to supporting files

Before:

.claude/commands/
└── git-create-pr.md        # 80+ lines with embedded template

After:

.claude/commands/
└── git-create-pr/
    ├── SKILL.md            # Main instructions, references template
    └── pr-body-template.md # Extracted template

When to Extract Reference Files

Extract content into separate files when:

• Templates are 10+ lines
• Shell scripts are reusable or complex
• Content would benefit from syntax highlighting in its own file
• Multiple skills might share the same reference

See ~/.claude/learnings/claude-authoring-skills.md for conventions when writing skill content.

Cross-Refs

• ~/.claude/learnings/claude-authoring/routing-table.md - Deciding if something should be a skill, guideline, or learning
• ~/.claude/learnings/claude-authoring-skills.md - Conventions for writing effective skills
• iterative-loop-design.md - Patterns for Ralph-style research loops