Repository Guidelines

Project Structure & Module Organization

This repository is organized as a set of AI skills plus validation tooling.

Add new skills as <skill-name>/SKILL.md at the repository root. Keep each skill self-contained in its own directory.

All skills must align with the specification available here: https://agentskills.io/specification.md

Build, Test, and Development Commands

• make validate: checks each */SKILL.md for YAML frontmatter, a name that matches its directory, a non-TODO description, and at least one top-level # heading. This is the canonical structural check.
• make validate-changelog: validates CHANGELOG.md format.
• make validate-links: runs the lychee link checker (config in lychee.toml).
• make install-dev: bootstraps the dev environment via scripts/install.sh.

Coding Style & Naming Conventions

• Shell scripts use Bash with strict mode (set -euo pipefail); keep new scripts consistent.
• Use 2-space indentation in shell blocks to match existing files.
• Skill directories should use lowercase kebab-case (example: my-new-skill/).
• SKILL.md must include YAML frontmatter with:
  • name: must exactly match the directory name.
  • description: non-empty, not TODO.
• Every SKILL.md must include a top-level Markdown heading (# ...).

Python in skill assets must support Python 3.9+

Scripts under */assets/ ship to customers and run against whatever python3 is on their machine (often macOS system Python 3.9). Keep them compatible with Python 3.9.

• Add from __future__ import annotations at the top so PEP 604 unions (X | None, list[int] | None) and other annotation-only syntax don't evaluate at import time.
• Do not use Python 3.10+ runtime features: match/case, tomllib, typing.Self, ExceptionGroup / except*, parenthesized with groups.
• Stick to the standard library — asset scripts must not require pip install on a customer's machine.

Tooling under .ci-scripts/ and scripts/ is not subject to this floor — those run under the project's uv-managed interpreter (>=3.11, see pyproject.toml).

Testing Guidelines

Testing is validation-driven:

• Primary check: make validate.
• Scope: verifies presence and correctness of frontmatter, heading requirements, and skill discovery via */SKILL.md.
• For validator updates, test both pass and fail paths (for example, a missing description should fail).

Commit & Pull Request Guidelines

Use clear, conventional commit messages such as:

• feat: add antithesis-xyz skill
• fix: enforce SKILL.md name/dir match in validator

PRs should include:

• What changed and why.
• Validation evidence (make validate output).
• A changelog label on every customer-facing change: changelog - breaking or changelog - non-breaking. Ask the user which label to apply if you are unsure.
• Any follow-up work for future PRs or limitations. Omit if irrelevant.

Automation: do not bump versions or edit the changelog by hand

Scripts in .ci-scripts/ run on merge and handle these chores for you. Do not propose or perform them as part of a PR.

• update_skill_versions.py manages metadata.version in every SKILL.md.
• changelog.py appends an entry to CHANGELOG.md from the PR title and the changelog - breaking / changelog - non-breaking label. The label controls the entry:
  • Always set one of the two labels when the PR changes what customers get: skill content, skill assets, or a new or removed skill. Use changelog - breaking when the change removes or renames a skill, or changes behavior that users rely on. Use changelog - non-breaking for all other customer-facing changes. Breaking entries are prefixed with BREAKING CHANGE:.
  • Set no label when the PR only touches repository internals, such as CI, validation tooling, or these guidelines. Without a label the merge workflow adds no entry.
  • Ask the user which label to apply if you are unsure.

Edit SKILL.md content freely, but leave the metadata.version field alone, and do not edit CHANGELOG.md directly unless directly requested by the user.