git:20260517.94b54a3 to git:20260704.75075f1

10 added, 26 removed. Audit A to A.

# AGENTS.md — mssql-performance-skills

## What this is

- A library of 16 Markdown skills for SQL Server performance tuning — 15 specialised review skills plus one agentic orchestrator (`mssql-performance-review`). No build system, no tests, no dependencies. The only executable is `bash scripts/verify-docs.sh`.

+ A library of Markdown skills for SQL Server performance tuning. No build system, no tests, no dependencies.

+ All skill details, check counts, prefix map, contributor workflows, and conventions — see `CLAUDE.md`.

## Verify before commit

```

bash scripts/verify-docs.sh

```

- Runs 31 documentation consistency checks. Fails block commit; warnings are advisory.

+ Runs documentation consistency checks. Fails block commit; warnings are advisory.

A `.claude/settings.json` PostToolUse hook auto-runs this after every Write/Edit — check output after file edits.

## Critical gotchas

- **Dollar signs in SKILL.md break at runtime.** The Claude skill loader does shell variable expansion on SKILL.md content. Never write `$0.012` or `$[expr]` — use `USD 0.012`. verify-docs.sh check 5 catches this.

+ **Dollar signs in SKILL.md break at runtime.** The Claude skill loader does shell variable expansion on SKILL.md content. Never write `$0.012` or `$[expr]` — use `USD 0.012`. verify-docs.sh catches this.

**references/check-explanations.md is NOT loaded at runtime by default.** Only SKILL.md is read automatically by the skill loader. All thresholds and triggers must live in SKILL.md. The reference file is on-demand context — Claude may load it when a user asks "explain check X" or for deeper fix-option detail.

- **Dispatchers are exempt from check-count matching** (verify-docs.sh check 11). Skills with no own checks — `sqlplan-batch`, `sqlplan-index-advisor`, `mssql-performance-review` — have references/check-explanations.md files that describe methodology, not per-check entries.

- ## Adding a check → update 6 locations

- `skills/<skill>/SKILL.md` (check + section header + frontmatter count + Purpose count),

- `skills/<skill>/references/check-explanations.md` (explanation + header + Quick Reference table),

- `PERFORMANCE_TUNING_GUIDE.md` (Check ID Reference total),

- `LLM_COST_ESTIMATION.md` (total checks line).

- ## Adding a skill → 9 steps

- See `CLAUDE.md` "Adding a New Skill" section for the full checklist (files, tables, references, examples).

- ## Check prefix map

- ```

- T = tsql-review I/W = sqlstats-review X = sqltrace-review

- V = sqlwait-review (40) S/N = sqlplan-review C = sqlplan-compare

- D = sqlplan-index-advisor P = sqlplan-deadlock Q = query-store-review

- R = procstats-review H = hadr-health-review L = clusterlog-review

- E = errorlog-review K = spn-review

- ```

- Dispatchers (no own prefix): `sqlplan-batch` (aggregates S/N), `mssql-performance-review` (delegates to all 15).

- Available prefixes: A, B, F, G, J, M, O, U, Y, Z

+ **Dispatcher-style skills are exempt from check-count matching.** Skills with no own checks have references/check-explanations.md files that describe methodology, not per-check entries.

## Full contributor guide

- `CLAUDE.md` — file map, conventions, all 16 skills listed, install instructions, development constraints, and step-by-step workflows for adding checks and skills.

+ `CLAUDE.md` — file map, conventions, all skills listed, install instructions, development constraints, and step-by-step workflows for adding checks and skills.

+ ## Autonomous agent workflow

+ This repo also runs [AgentWorks](https://github.com/vanterx/agentworks): agents can claim `status: available` GitHub issues and work through `scripts/start_work.sh`. If you were invoked by that loop (or `review_work.sh`), see `AGENT_CONTRACT.md` for the claim/work/review/merge contract — it's separate from this file, which covers the skills-library conventions above.