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/:

   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:

  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