git:20260805.2bc00ea to git:20260805.c75a5fb

# CLAUDE.md

Guidance for Claude Code working in this repository.

## What this is

Personal Claude skills, one per directory under `skills/`. The repo is also a

Claude Code plugin marketplace (`.claude-plugin/marketplace.json` +

`plugin.json`), so others can `/plugin marketplace add matt-w-horn/skills`; I

load them myself by symlinking each into `~/.claude/skills/`. A skill is a

directory with a `SKILL.md` (frontmatter: `name` matching the directory,

`description`) plus optional `references/`, `scripts/`, and `tests/`. The

simulation scripts (`skills/life-paths/scripts/fi_model.py`,

`skills/financial-planning/scripts/simcore.py`) are pure standard library;

keep them that way, since CI installs nothing.

## Commands

```bash

python3 tools/validate_skills.py # structure + path-reference validation

tools/run_tests.sh # every tests/ suite (skills and tools)

sh tools/install-hooks.sh # git pre-commit hook: both checks + gitleaks

```

Both checks run on commit (hook) and on push/PR (CI). Keep them green.

Evals (see `tools/eval/README.md`; only the first is gated by CI, via

`tools/eval/tests/`):

```bash

python3 tools/eval/lint_evals.py # corpus quality gate, stdlib only

python3 tools/eval/grade.py --calibrate # judge must separate good.md from bad.md

python3 tools/eval/run_trigger.py --split graded # ~144 `claude -p` runs

python3 tools/eval/run_exec.py --runs 2 # 32 long runs; hours

```

## Conventions & gotchas

- **Adding a skill**: create `skills/<skill>/` with a `SKILL.md`, then activate

it from the repo root with `ln -s "$PWD/skills/<skill>" ~/.claude/skills/<skill>`.

Nothing else to wire up: the marketplace auto-discovers everything under

`skills/` (no manifest edit), and the validator finds skills at any depth by

their `SKILL.md`.

- **Path references are validated.** Any `dir/file` token in a skill's

Markdown whose first segment is a real subdirectory of that skill must

resolve, fenced commands included; runtime artifacts (dirs that don't exist

in the repo, like `finances/config.json`) are ignored. Files under

`references/` or `scripts/` that no Markdown mentions draw a warning.

- **Scripts must ship with tests** (`tests/test_*.py`, `unittest`, run from

the skill directory). Degenerate inputs should raise `ValueError` with a

clear message, never crash deep in the math — see the guards in `simcore.py`

and `fi_model.py` for the pattern.

- **Eval corpora live in `skills/<skill>/evals/`** and are authored blind: a

trigger query or rubric assertion must not paraphrase the SKILL.md body, and

`lint_evals.py` rule 5 fails the corpus if one shares a five-word phrase with

the body that is absent from the description. When editing evals, work from

the description and domain knowledge, not the skill's own instructions.

Trigger queries must also be self-contained: runs happen in an empty

directory, so a query naming a file misfires for a fixture reason that reads

like a description failure.

- **Never put a `SKILL.md` under `evals/`.** `validate_skills.py` treats any

`SKILL.md` at any depth as a skill and would try to validate the fixture.

Same trap for `scripts/`-, `references/`-, `tests/`- or `evals/`-prefixed

path tokens in eval prose: the validator resolves them against the real

directories. Both are linted.

- **This repo is public, so it may not depend on anything outside itself.** A

skill here must stand alone: no references to system-wide skills, to

`~/.claude`, or to a project that isn't public. Skills needing any of those

live as real directories under `~/.claude/skills/` instead, which is where

`apps-script-deploy` went on 2026-07-26. The `~/.claude/skills/`

paths below are install instructions for a reader, not a dependency.

- No secrets belong here, ever; gitleaks runs in the hook and CI as a backstop.