# 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.

## 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.
- **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
  `writing` and `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.