siujamo
6beb72688e
Document the process for adding or modifying a skill, frontmatter requirements, style (British English), commit conventions, and the licence under which contributions are accepted.
62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
# 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)).
|