---
name: openkata-skill-conventions
description: >
  Applies OpenKata project conventions when creating or updating
  skills in this repository. Adds Tessl integration, changelog
  management, versioning, and symlink placement on top of the
  generic create-skill workflow. Use alongside create-skill when
  working in the OpenKata repo.
---

# OpenKata Skill Conventions

Project-specific additions to the `create-skill` workflow. This
skill activates alongside the generic `create-skill` and adds
OpenKata conventions.

## Additional Steps

After the generic `create-skill` workflow, also do:

1. **Determine placement** — Ask whether this skill is:
   - **Local** → `.agents/skills/<name>/`
   - **Distributable** → `skills/<name>/`

2. **Create CHANGELOG.md** — Every skill gets a changelog
   starting at v1.0.0 with an initial `### Added` entry.
   Follow the markdown-consistency rule for formatting.

3. **Import to Tessl** — Run
   `tessl skill import <skill-directory>` to generate `tile.json`
   (ADR 0006).

4. **Symlink if distributable** — For skills in `skills/`, ask
   the user if they want it symlinked into `.agents/skills/`:
   ```bash
   ln -s ../../skills/<name> .agents/skills/<name>
   ```

5. **Quality check (mandatory gate)** — Do not commit until
   all checks pass. Follow the `review-skill` workflow to
   lint, review, and optimize. The skill must:
   - Score 95%+ on `tessl skill review`
   - Pass the skill design checklist
   - Survive 2–3 positive and 1 negative representative
     prompt

6. **Acknowledge sources** — If the skill draws on external
   practices, add or update `references/ACKNOWLEDGMENTS.md`
   with the source, license, what was adapted, and the version
   it was adopted in.

## Conventions

- Always ask the user before running Tessl commands — do not
  run lint, review, or optimize without confirmation
- Local skills go in `.agents/skills/<name>/`
- Distributable skills go in `skills/<name>/` with a symlink
  in `.agents/skills/`
- Every skill must have a `tile.json` generated by
  `tessl skill import`
- Every skill gets a CHANGELOG.md
- Changelogs document skill-facing changes only — dev-only
  artifacts (tile.json, tessl.json) are not changelog-worthy