Initial project setup with reflect skill

Reusable Claude Code skills shared across projects via symlinks
into ~/.claude/skills/. Includes the /reflect skill for structured
milestone reflections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,34 @@
+# Custom Claude Skills
+
+Reusable Claude Code skills shared across all projects via symlinks into `~/.claude/skills/`.
+
+## Repository Structure
+
+```
+custom-claude-skills/
+├── CLAUDE.md              # This file
+├── MEMORY.md              # Learnings about skill development
+├── FUTURE.md              # Future skill ideas
+├── README.md              # Setup instructions and skill catalogue
+├── scripts/
+│   └── install.sh         # Symlinks all skills into ~/.claude/skills/
+└── skills/
+    └── reflect/
+        └── SKILL.md       # Milestone reflection skill
+```
+
+## Conventions
+
+- Each skill lives in `skills/<skill-name>/SKILL.md`
+- Skills should be project-agnostic where possible — use dynamic context injection (`!`command``) to adapt to the current project
+- The `scripts/install.sh` script creates symlinks from `~/.claude/skills/<name>` → this repo's `skills/<name>/`
+- After adding a new skill, run `./scripts/install.sh` to register it
+- Skills that are only useful for one project should live in that project's `.claude/skills/` instead
+
+## Skill Development Guidelines
+
+- **Inline by default** — only use `context: fork` if the skill genuinely doesn't need conversation history
+- **Pre-fetch context** with `!`command`` injection to reduce tool calls during execution
+- **Restrict tools** with `allowed-tools` to the minimum needed — this reduces permission prompts
+- **Use $ARGUMENTS** for user input, `$0`, `$1` etc. for positional args
+- Dynamic commands in `!`command`` run at skill load time, not during Claude's execution

FUTURE.md

@@ -0,0 +1,13 @@
+# Custom Claude Skills — Future Ideas
+
+## F1: Pre-commit validation skill
+- **Problem:** The "validate locally, deploy once" pattern is frequently violated — errors caught in prod that could be caught locally
+- **Idea:** A `/validate` skill that detects the project type and runs appropriate local validation (helm template, kustomize build, docker compose config, etc.)
+- **Open questions:** How to detect project type reliably? Should it be one skill or per-type?
+- **Depends on:** More experience with which validations are commonly missed
+
+## F2: Milestone setup skill
+- **Problem:** Starting a new milestone has boilerplate (create verify script skeleton, update README table, etc.)
+- **Idea:** A `/new-milestone M9 "Velero backup"` skill that scaffolds the milestone
+- **Open questions:** How much should be templated vs. left to Claude?
+- **Depends on:** Stable milestone conventions across projects

MEMORY.md

@@ -0,0 +1,8 @@
+# Custom Claude Skills — Memory
+
+## Skill Development Learnings
+
+- Skills in `~/.claude/skills/` are available across all projects (personal scope)
+- `!`command`` injection runs at skill load time — great for pre-fetching git logs, file contents, etc.
+- Inline skills (no `context: fork`) retain full conversation history — essential for reflection-type skills
+- `allowed-tools` reduces permission prompts by declaring what the skill needs upfront

README.md

@@ -0,0 +1,40 @@
+# Custom Claude Skills
+
+Reusable [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skills shared across all projects.
+
+## Setup
+
+```bash
+# Clone and install
+cd ~/dev/claude/custom-claude-skills
+./scripts/install.sh
+```
+
+The install script creates symlinks from `~/.claude/skills/` to this repo, making all skills available in every project.
+
+## Available Skills
+
+| Skill | Invocation | Description |
+|-------|-----------|-------------|
+| reflect | `/reflect M8` | Milestone reflection — reviews conversation history, git log, and project docs to produce structured reflection artifacts across MEMORY.md, FUTURE.md, README.md, and CLAUDE.md |
+
+## Adding a New Skill
+
+1. Create `skills/<skill-name>/SKILL.md` with YAML frontmatter and instructions
+2. Run `./scripts/install.sh` to create the symlink
+3. Update this README's skill table
+
+## How Skills Work
+
+Skills are Claude Code's extensibility mechanism. Each skill is a markdown file with:
+- **YAML frontmatter** — metadata, tool restrictions, execution mode
+- **Dynamic context injection** — `!`command`` blocks run at load time to pre-fetch data
+- **Structured instructions** — what Claude should do when the skill is invoked
+
+Skills in `~/.claude/skills/` are available across all projects (personal scope).
+
+## Scripts
+
+| Script | Purpose | When to run |
+|--------|---------|-------------|
+| `scripts/install.sh` | Symlinks all skills into `~/.claude/skills/` | After cloning or adding new skills |

scripts/install.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Symlink all skills from this repo into ~/.claude/skills/ (personal scope)
+# so they're available across all Claude Code projects.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(dirname "$SCRIPT_DIR")"
+SKILLS_SRC="$REPO_DIR/skills"
+SKILLS_DST="$HOME/.claude/skills"
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+mkdir -p "$SKILLS_DST"
+
+installed=0
+skipped=0
+
+for skill_dir in "$SKILLS_SRC"/*/; do
+    [ -d "$skill_dir" ] || continue
+    skill_name="$(basename "$skill_dir")"
+    target="$SKILLS_DST/$skill_name"
+
+    if [ -L "$target" ]; then
+        existing="$(readlink -f "$target")"
+        expected="$(readlink -f "$skill_dir")"
+        if [ "$existing" = "$expected" ]; then
+            echo -e "${YELLOW}SKIP${NC} $skill_name (already linked)"
+            skipped=$((skipped + 1))
+            continue
+        else
+            echo -e "${YELLOW}UPDATE${NC} $skill_name (repointing symlink)"
+            rm "$target"
+        fi
+    elif [ -e "$target" ]; then
+        echo -e "${YELLOW}SKIP${NC} $skill_name (non-symlink exists at $target — remove manually to update)"
+        skipped=$((skipped + 1))
+        continue
+    fi
+
+    ln -s "$skill_dir" "$target"
+    echo -e "${GREEN}INSTALLED${NC} $skill_name → $target"
+    installed=$((installed + 1))
+done
+
+echo ""
+echo "Done. Installed: $installed, Skipped: $skipped"
+echo "Skills are now available as slash commands in Claude Code (e.g. /reflect M8)"

skills/reflect/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: reflect
+description: >
+  Run a milestone reflection after completing a milestone. Reviews the full conversation history,
+  git log, and current project docs to produce structured reflection artifacts. Use when a milestone
+  is complete and verified. Invoke with the milestone number, e.g. /reflect M8
+allowed-tools: Read, Edit, Write, Grep, Glob, Bash(git *)
+---
+
+# Milestone Reflection Skill
+
+You are performing a milestone reflection for milestone **$ARGUMENTS**.
+
+## Context
+
+You have access to the full conversation history in your context window. Your job is to
+review **everything** that happened during this milestone — every commit, every debugging
+detour, every wrong assumption, every backtrack — and distill it into structured artifacts.
+
+## Pre-gathered context
+
+### Git log for this milestone
+!`git log --oneline --since="$(git log --all --oneline --grep="[Mm]$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1-1}').*[Vv]erif\|[Mm]$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1-1}').*[Rr]eflect\|[Mm]$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1-1}').*[Cc]omplete" --format='%aI' | head -1 || echo '3 months ago')" 2>/dev/null || git log --oneline -30`
+
+### Current MEMORY.md
+!`cat MEMORY.md 2>/dev/null || echo "No MEMORY.md found"`
+
+### Current FUTURE.md
+!`cat FUTURE.md 2>/dev/null || echo "No FUTURE.md found"`
+
+### Current README.md (scripts section)
+!`sed -n '/## Scripts/,/^## /p' README.md 2>/dev/null | head -60 || echo "No Scripts section found"`
+
+### Available scripts
+!`ls -1 scripts/ 2>/dev/null || echo "No scripts directory"`
+
+### Verify script for this milestone
+!`cat scripts/verify-m$(echo '$ARGUMENTS' | tr -d 'Mm' | awk '{print $1}').sh 2>/dev/null || echo "No verify script found for this milestone"`
+
+## Instructions
+
+Review the **entire conversation** from the start of this milestone. Do NOT just look at the
+final state — examine the journey: wrong turns, debugging sessions, repeated commands, surprises.
+
+### Step 1: Draft the reflection
+
+Before editing any files, write out your reflection analysis covering these four areas:
+
+1. **Process improvements:** What slowed us down? Wrong assumptions? Circles or backtracks?
+   What could be automated? What would make this faster if redone from scratch?
+
+2. **Key knowledge for reproduction:** Critical facts, gotchas, version quirks, network
+   constraints, configuration details that caused debugging detours. Things a future session
+   needs to know.
+
+3. **Scripts and automation:** Commands run repeatedly that should be scripts. Existing scripts
+   that proved valuable. Multi-step manual processes to condense.
+
+4. **Future improvements:** Ideas that surfaced but don't belong in current scope. These go
+   in FUTURE.md with Problem/Idea/Open questions/Depends on format.
+
+### Step 2: Count the commits
+
+Analyze the git log to quantify:
+- Total commits for this milestone
+- How many were fixes vs. forward progress
+- Number of pushes / syncs if identifiable
+- Longest debugging detour
+
+### Step 3: Update files
+
+Update these files in order:
+
+1. **MEMORY.md** — Add a `## $ARGUMENTS Reflection — <title>` section with the reflection
+   bullets. Also update any existing sections (Gotchas, Process Lessons, Key Patterns) with
+   new learnings from this milestone.
+
+2. **FUTURE.md** — Add any new future improvement ideas in the standard format.
+
+3. **README.md** — Update the milestone table status and the Scripts section with any new scripts.
+
+4. **CLAUDE.md** — Update the repo structure if it changed, and add any new conventions or
+   patterns discovered.
+
+### Step 4: Summary
+
+After all edits, provide a brief summary:
+- Number of new gotchas added
+- Number of new FUTURE items
+- Key theme of the milestone (1 sentence)
+- Biggest process lesson (1 sentence)
+
+## Quality checks
+
+- Every bullet in the reflection should be **actionable or informative** — no filler
+- Gotchas should include the **symptom AND the fix**, not just "X was tricky"
+- Process lessons should be phrased as **rules** ("Always X before Y", "Never assume Z")
+- Future items need all four fields (Problem/Idea/Open questions/Depends on)
+- Use the same formatting style as existing reflections in MEMORY.md