# Openkata Skill Conventions

> 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.

- Skill: `tovrleaf/openkata-skill-conventions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tovrleaf/openkata-skill-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tovrleaf/openkata-skill-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tovrleaf (https://skillmd.com/u/tovrleaf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tovrleaf/openkata-skill-conventions

---


# 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-style rule for formatting.

3. **Import to Tessl** — Run
   `tessl skill import --workspace openkata <skill-directory>`
   to generate `.tessl-plugin/plugin.json` (ADR 0006). The
   `--workspace openkata` flag ensures the correct prefix.

4. **Create `.tesslignore`** — Add a `.tesslignore` file to the
   skill directory containing `CHANGELOG.md`.

5. **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>
   ```

6. **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`
   - Contain a ## Boundaries section (DOES / Does NOT)
   - Pass the skill design checklist
   - Survive 2–3 positive and 1 negative representative
     prompt

   After the quality check passes, persist the review
   score to `.tessl-plugin/plugin.json` (set the
   `"score"` field to the numeric percentage).

7. **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.

## Naming

- Distributable skills: no prefix, pattern-based
  - `create-<artifact>` — produces a new file
  - `review-<artifact>` — evaluates quality
  - `<domain>-conventions` — enforces standards
  - `<name>-workflow` — multi-phase process
- Local skills: always `openkata-` prefixed
  - `openkata-review-<artifact>` — repo-specific review
  - `openkata-<domain>-conventions` — repo-specific standards
  - `openkata-<name>-release` — repo-specific release process

## Conventions

- Skill names are lowercase-hyphenated: `create-profile`,
  `commit-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
- Distributable skills must not reference local skills
  (e.g., openkata-review-skill, openkata-ryu-release).
  Keep distributable skills self-contained and portable.
- ACKNOWLEDGMENTS.md format — one line per source:
  `- [name](url) (license) — what was adapted (adopted in vX.Y.Z)`
- Changelogs document skill-facing changes only — dev-only
  artifacts (tile.json, tessl.json) are not changelog-worthy
- Frontmatter uses `metadata` block for `version` and `tags`:
  ```yaml
  metadata:
    version: "1.0.0"
    tags: "category:workflow"
  ```

## RATIONALE.md

Every distributable skill and rule should include a
`RATIONALE.md` at its root. This file explains design
decisions, trade-offs, and why the skill is structured
the way it is.

- Visible on the website as a "Rationale" tab
- Distributed in archives (users see it)
- Excluded from the Files tab (like CHANGELOG.md)
- Each heading answers one "why" question
- Keep entries concise — a paragraph per decision

## Example Scenario

User: "Create a skill for database migrations."

1. create-skill produces `skills/migrate-database/SKILL.md`
2. This skill activates: determines distributable placement
3. Creates CHANGELOG.md, runs `tessl skill import`,
   creates .tesslignore, offers symlink, runs quality gate

## Boundaries

**DOES:**
- Add changelog, tile.json, symlink, and acknowledgments to skills
- Determine placement (local vs distributable)
- Enforce quality gate before commit

**Does NOT:**
- Create the skill itself (that's `create-skill`)
- Run tessl review/optimize (that's `openkata-review-skill`)
- Publish or release skills