common-skills/README.md

common-skills

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

Skills

Skill	Description
commit-message	Generate Conventional Commits messages from staged changes
deep-dive	Produce structured technical reports from code, docs, or URLs
docs-rag	RAG over local 3GPP Release 19 specification documents
meta-creator	Create and iterate on agent skills and custom agents
ppt-maker	Convert Markdown to professional PPTX with auto-charts
sdlc	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

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

   # Create skills/<name>/assets/architecture.puml and workflow.puml, then:
   bash scripts/puml2svg.sh <name>
   

4. Run evals locally and update baseline:

   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.

# 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

# 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

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