Contributing¶

Add or update a skill¶

Follow authoring guidance on AGENTS.md.
Depending on whether it's a pipeline or a guidance skill, start with the appropriate template in templates/.
Put the skill at skills/<skill-name>/SKILL.md.
Folder name must match frontmatter name. Set category and summary (the public table blurb). Check format with test_skill_quality.py
Run python docs/hooks/skill_catalog.py to refresh the skill table in README.md and docs/index.html. Do not edit tests/test_skill_catalog.py — it discovers skills/*/SKILL.md itself.
Open a PR and request a second-party review.

Test¶

Several levels of testing is advised.

1. Repo-level tests: formatting¶

./tests/test_skill_quality.py tests skill's formatting
./tests/test_sync_bundle.py tests that unnecessary skill folders are not synced to Unity Catalog/Gateway

Both these tests can be invoked on all skills with

uv run --isolated --with pytest --with pyyaml python -m pytest -q tests

2.Skill-level unit tests¶

Store your skill's unit tests here ./skills/<your_skill>/tests

uv run --isolated --with pytest --with-requirements skills/<name>/tests/requirements.txt \
    python -m pytest -q skills/<name>/tests

Automated CI¶

Both overall formatting and unit tests can be automated with CI (.github/workflows/ci.yml) which runs on every non-draft PR. The repo tests also check that README.md and docs/index.html match the skills; if they lag, the job fails and prints the regenerate command. - Put a skill's test-only dependencies in skills/<name>/tests/requirements.txt, pinned to versions you ran. CI finds every skills/*/tests/ folder automatically. - A skill's eval/ or tests/ folder is never published by sync_skills_git2unity.py; tests/test_sync_bundle.py fails if that filter is removed. - CI also scans the full git history for secrets with gitleaks.

3. Evaluate with and without skill¶

See Evaluation.

Docs site¶

Most of the docs site is generated from SKILL.md files, README.md, and this file. Edit those, not the pages in docs/.

Warning

Some headings in README.md and this file are copied to the site by name. Read DOCS.md before renaming or re-leveling a heading, and for how to preview and publish the site.