# Contributing to SKILLS-GROK

Thanks for improving the skill library. This document is the single process for humans and agents.

## Principles

- **Clarity over cleverness** — a junior engineer should follow the skill without guessing.
- **Composable** — skills do one job well; link related skills instead of mega-blobs.
- **Evidence** — workflows that produce code must demand verification, not vibes.
- **Security & privacy by default** — never teach unsafe shortcuts without explicit risk callouts.
- **Repo independence** — this library must not depend on any application repository.

## Development setup

```bash
git clone https://github.com/leonardeco/SKILLS-GROK.git
cd SKILLS-GROK
```

Optional: point Grok at the local skills folder (see [docs/install.md](./docs/install.md)).

## Workflow

1. Create a branch: `feat/<skill-name>` or `fix/<skill-name>`.
2. Edit under `skills/`, `docs/`, `templates/`, or `scripts/` as needed.
3. Keep `catalog/skills.yaml` and `README.md` aligned.
4. Run validation:

   ```powershell
   # Windows
   pwsh -File .\scripts\validate-skills.ps1
   ```

   ```bash
   # Unix
   ./scripts/validate-skills.sh
   ```

5. Update `CHANGELOG.md` under `[Unreleased]`.
6. Open a PR using the template.

## Skill quality bar

| Check | Requirement |
|---|---|
| Name | `^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$`, equals folder name |
| Frontmatter | `name` + `description` required |
| Description | What + when + `Use when the user runs /<name>` |
| Body | Actionable steps; no pure marketing copy |
| References | Every `references/foo.md` link in SKILL.md must exist |
| Secrets | Zero credentials or real PII |
| Scope | No hard dependency on a single product repo |

Full contract: [docs/skill-spec.md](./docs/skill-spec.md).

## Commit messages

Prefer Conventional Commits:

- `feat(full-dev-team): ...`
- `docs: ...`
- `chore(ci): ...`
- `fix(validate): ...`

## Code review focus

Reviewers check:

1. Spec compliance (`skill-spec.md`)
2. Validation green
3. Catalog/README sync
4. Security/privacy posture
5. That the skill is actually usable as an agent prompt

## License

By contributing, you agree that your contributions are licensed under the MIT License (see [LICENSE](./LICENSE)).