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//
• Distributable → skills//

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

1. Import to Tessl — Run

tessl skill import --workspace openkata to generate .tessl-plugin/plugin.json (ADR 0006). The --workspace openkata flag ensures the correct prefix.

1. Create .tesslignore — Add a .tesslignore file to the

skill directory containing CHANGELOG.md.

1. Symlink if distributable — For skills in skills/, ask

the user if they want it symlinked into .agents/skills/: ``bash ln -s ../../skills/ .agents/skills/ ``

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

1. 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- — produces a new file
• review- — evaluates quality
• -conventions — enforces standards
• -workflow — multi-phase process
• Local skills: always openkata- prefixed
• openkata-review- — repo-specific review
• openkata--conventions — repo-specific standards
• openkata--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//
• Distributable skills go in skills// 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tovrleaf
• Source: tovrleaf/openkata
• License: MIT

Install and usage instructions live in the source repository linked above.