From 5ff98763cd6885e25364d2be5605b3092871f676 Mon Sep 17 00:00:00 2001 From: Paul O'Reilly Date: Wed, 11 Mar 2026 15:33:46 +1300 Subject: [PATCH] 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 --- CLAUDE.md | 34 ++++++++++++++ FUTURE.md | 13 ++++++ MEMORY.md | 8 ++++ README.md | 40 +++++++++++++++++ scripts/install.sh | 50 +++++++++++++++++++++ skills/reflect/SKILL.md | 99 +++++++++++++++++++++++++++++++++++++++++ 6 files changed, 244 insertions(+) create mode 100644 CLAUDE.md create mode 100644 FUTURE.md create mode 100644 MEMORY.md create mode 100644 README.md create mode 100755 scripts/install.sh create mode 100644 skills/reflect/SKILL.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f5d2e24 --- /dev/null +++ b/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.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/` → this repo's `skills//` +- 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 diff --git a/FUTURE.md b/FUTURE.md new file mode 100644 index 0000000..189f6b8 --- /dev/null +++ b/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 diff --git a/MEMORY.md b/MEMORY.md new file mode 100644 index 0000000..05bf3d8 --- /dev/null +++ b/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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..8c16ead --- /dev/null +++ b/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.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 | diff --git a/scripts/install.sh b/scripts/install.sh new file mode 100755 index 0000000..048828a --- /dev/null +++ b/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)" diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md new file mode 100644 index 0000000..af3a9fe --- /dev/null +++ b/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 — ` 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