diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1865d03 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing + +Guidelines for adding or modifying a skill in this catalogue. + +## Adding a Skill + +1. Pick a short, kebab-case name (`my-skill`). +2. Create a directory and a `SKILL.md` inside it: + ``` + mkdir my-skill + ``` +3. Start `SKILL.md` with the required frontmatter: + ```yaml + --- + name: my-skill + description: ... + --- + ``` +4. Open a pull request against `main`. + +### Frontmatter + +- `name` must match the directory name. Claude Code uses it to identify the skill. +- `description` controls when the skill is invoked. Be specific: name the file types, project shapes, and user requests that should trigger it. A vague description (for example, "helps with Java") will fire too often and add noise. +- The body of `SKILL.md` is loaded into the conversation when the skill fires. Keep it dense and self-contained. + +## Modifying a Skill + +Edit the skill's `SKILL.md` in place. Open a PR. If the change alters the skill's public contract (the `description`, the rules, or the inputs/outputs the skill expects), call it out in the PR description so reviewers can decide whether the change should also trigger a version bump in any catalogue that consumes it. + +## Style + +- **British English** is the default for all prose, code comments, and commit messages. Use the `british-english` skill to self-review before requesting review. +- Use sentence case in headings ("Adding a skill", not "Adding A Skill"). +- Code samples should be runnable, or marked clearly when truncated for brevity. + +## Commit Messages + +Use conventional commits. For this repository: + +| Type | When | +|---|---| +| `feat` | A new skill, or a new feature within an existing skill | +| `fix` | A behavioural correction | +| `docs` | README, CONTRIBUTING, LICENCE, or doc-only edits | +| `chore` | Tooling, `.gitignore`, build configuration | + +See the `commit-message` skill for the full format. + +## Review + +Reviewers check for: + +- Frontmatter correctness and specificity +- Compliance with any cross-cutting rules (for example, the four-layer architecture in the `spring-boot` skill) +- British English conformance +- A concrete example for every non-trivial claim + +## Licence + +By contributing, you agree that your contributions are licensed under the MIT Licence (see [`LICENCE`](LICENCE)).