# common-skills

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

## Skills

| Skill | Description |
|---|---|
| [commit-message](skills/commit-message/README.md) | Generate Conventional Commits messages from staged changes |
| [deep-dive](skills/deep-dive/README.md) | Produce structured technical reports from code, docs, or URLs |
| [docs-rag](skills/docs-rag/README.md) | RAG over local 3GPP Release 19 specification documents |
| [meta-creator](skills/meta-creator/README.md) | Create and iterate on agent skills and custom agents |
| [ppt-maker](skills/ppt-maker/README.md) | Convert Markdown to professional PPTX with auto-charts |
| [sdlc](skills/sdlc/README.md) | Guide a full software development lifecycle end-to-end |

## Repository Structure

```
skills/
├── commit-message/
│   ├── SKILL.md
│   ├── README.md
│   ├── assets/          ← architecture.svg, workflow.svg + .puml sources
│   ├── evals/evals.json
│   └── references/
├── deep-dive/
├── docs-rag/
├── meta-creator/
├── ppt-maker/
└── sdlc/
scripts/
├── run_evals.py         ← eval runner with regression protection
├── puml2svg.sh          ← convert .puml diagrams to SVG
├── sync.sh              ← sync skills into a project
├── install-agents.sh    ← install agent configs into a project
└── orchestrate.py       ← multi-skill orchestration
.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 commit-message ppt-maker
```

## 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. Add architecture and workflow diagrams:
   ```bash
   # Create skills/<name>/assets/architecture.puml and workflow.puml, then:
   bash scripts/puml2svg.sh <name>
   ```
4. Run evals locally and update baseline:
   ```bash
   python scripts/run_evals.py <name> --update-baseline
   ```
5. Push — the pre-push hook will verify no regressions on changed skills

## Updating Diagrams

Each skill stores PlantUML source files in `assets/` alongside the rendered SVGs.

```bash
# Regenerate all SVGs
bash scripts/puml2svg.sh

# Regenerate a single skill
bash scripts/puml2svg.sh deep-dive
```

Requires Java and Graphviz (`apt install graphviz`). The PlantUML jar is resolved automatically from the VS Code extension path; override with `PLANTUML_JAR=/path/to/plantuml.jar`.

## Running Evals

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

# Run single skill
python scripts/run_evals.py commit-message

# 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 commit-message --update-baseline
```

## Install pre-push Hook

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