# common-skills

Shared Kiro agent skills for the team. All skills are evaluated before merge.

## Structure

```
skills/
├── codereview/
│   ├── SKILL.md
│   └── evals/evals.json
├── docs-rag/
│   ├── SKILL.md
│   ├── data/index.json
│   └── evals/evals.json
├── python/
├── testing/
└── typescript/
scripts/
├── run_evals.py   ← eval runner with regression protection
└── sync.sh        ← sync skills into a project
.githooks/
└── pre-push       ← blocks push if changed skills regress
baselines.json     ← recorded pass rates (committed to repo)
```

## Using Skills in Your Project

```bash
# Sync all skills
COMMON_SKILLS_DIR=~/common-skills bash scripts/sync.sh

# Sync specific skills only
COMMON_SKILLS_DIR=~/common-skills bash scripts/sync.sh codereview python
```

## Contributing a New Skill

1. Create `skills/<name>/SKILL.md` with YAML frontmatter (`name`, `description`)
2. Add `skills/<name>/evals/evals.json` with at least 3 eval cases
3. Run evals locally and update baseline:
   ```bash
   python scripts/run_evals.py <name> --update-baseline
   ```
4. Push — the pre-push hook will verify no regressions on changed skills

## Running Evals

```bash
# Run all skills
python scripts/run_evals.py

# Run single skill
python scripts/run_evals.py codereview

# Check for regressions against baselines.json
python scripts/run_evals.py --check-regression

# After improving a skill, record new baseline
python scripts/run_evals.py codereview --update-baseline
```

## Install pre-push Hook

```bash
cp .githooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
```