# 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`: validates all SKILLS align with the specification.
- `make validate-changelog`: validates CHANGELOG.md format.

## 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 (`# ...`).

## 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).
- Any follow-up work or limitations.

For notable changes (new skills, breaking changes, significant fixes), add a
`changelog - breaking` or `changelog - non-breaking` label to the PR. A bot
updates `CHANGELOG.md` automatically on merge using the PR title — breaking
entries are prefixed with `BREAKING CHANGE:`. Do not edit `CHANGELOG.md`
directly.