AGENTS.md git:20261020.21af20cA

Immutable. This exact content never changes and is served at /api/v1/blob/c3b40508c8fa9a23.

# Working in this repo

A collection of Agent Skills (the open `SKILL.md` format). Read this before adding or changing a skill.

## Layout

```
skills/<name>/          one folder per skill; this is exactly what gets installed
  SKILL.md              frontmatter (name, description, ...) + instructions
  references/           docs the skill tells the agent to read when needed
  scripts/              helper scripts the skill runs
evals/<name>/           test prompts; kept outside the skill so installs stay lean
  evals.json            task prompts + assertions for with/without-skill runs
  trigger-eval-set.json should/shouldn't-trigger queries for tuning the description
tools/validate.py       checks every SKILL.md (run before committing)
tools/package.py        builds dist/<name>.skill for claude.ai / desktop upload
.claude-plugin/         Claude Code plugin marketplace manifest
```

## Rules for a skill

- **Folder name = `name`**: kebab-case, at most 64 characters.
- **Description** (at most 1024 chars, no `<` or `>`) is the only thing an agent sees before deciding to load the skill. It says what the skill does *and* when to use it, including phrasings that don't name the skill, and ends with when *not* to use it.
  - If the description contains `: ` (colon-space), wrap it in double quotes. Unquoted, it breaks the YAML and the skill silently fails to load.
- **Allowed frontmatter keys:** `name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility` (at most 500 chars: runtime needs such as Python or browser tools). Claude Code reads extra keys (`when_to_use`, `argument-hint`, ...), but a claude.ai upload rejects them, so keep skills to the standard keys.
- **Keep `SKILL.md` under about 500 lines.** Push detail into `references/` and point to it from `SKILL.md`, saying when to read it.
- **Explain why, not just what.** Agents follow reasoning better than all-caps rules.
- **Scripts:**
  - Portable (Windows, macOS, Linux), standard library only where possible.
  - Runnable as `python scripts/x.py` and under `python -I`.
  - They print where their outputs went.
- **No secrets, personal paths or machine-specific values** anywhere in `skills/`.

## Before committing

```bash
python tools/validate.py
claude plugin validate .  # checks .claude-plugin/marketplace.json
python tools/package.py   # optional, output is gitignored
```

When a skill changes, **bump its `version` in `.claude-plugin/marketplace.json`**. Claude Code users only receive an update when that version changes. The marketplace name `hrih-skills` is what users type in install commands, so don't rename it casually. Names like `agent-skills` and `anthropic-*` are reserved.

For claude.ai users, attach the `dist/*.skill` files to a GitHub Release.

## Testing a skill

1. Run each prompt in `evals/<name>/evals.json` twice: once with the skill and once without, as fresh agents.
2. Grade the outputs against the assertions and look at them yourself. Design and writing quality need human eyes.
3. Keep runs in a `<name>-workspace/` folder outside `skills/`; it's gitignored.
4. For the description, use `trigger-eval-set.json` with skill-creator's `run_loop`, choosing by held-out score, not train score.
   - On Windows, its `run_eval.py` needs a non-`select()` pipe reader.
   - Its parallel workers can pick each other's temporary command, so count any copy of the skill as a trigger.

## Adding a skill

1. Create `skills/<name>/SKILL.md` (copy an existing skill's structure).
2. Add `evals/<name>/evals.json` with 2–3 realistic prompts.
3. Add the skill to `.claude-plugin/marketplace.json` and to the table in `README.md`.
4. Run `tools/validate.py`.