agentleFS
tovrleaftovrleaf/openkata/.agents/skills/openkata-skill-conventions/SKILL.md

openkata-skill-conventions

Skill1 starsChanged 17 days agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 6 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After the generic create-skill workflow, also do:

    line 19
  2. Distinctive:

    Follow the markdown-style rule for formatting.

    line 27
  3. Very specific:

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

    line 52
  4. Distinctive:

    Always ask the user before running Tessl commands — do not run lint, review, or optimize without confirmation

    line 77
  5. Very specific:

    Every skill must have a .tessl-plugin/plugin.json generated by tessl skill import, and a .tesslignore

    line 82
  6. Distinctive:

    Every skill gets a CHANGELOG.md

    line 84
  7. Distinctive:

    Keep distributable skills self-contained and portable.

    line 87
  8. Very specific:

    Every distributable skill and rule should include a RATIONALE.md at its root.

    line 102
  9. Distinctive:

    Keep entries concise — a paragraph per decision

    line 112
  10. Distinctive:

    Add changelog, tessl files, symlink, and acknowledgments to skills

    line 126
  11. Very specific:

    Create the skill itself (that's create-skill)

    line 131
  12. Very specific:

    Run tessl review/optimize (that's openkata-review-skill)

    line 132

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 and evals/.
  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 .tessl-plugin/plugin.json generated by tessl skill import, and a .tesslignore
  • 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 (.tessl-plugin/, .tesslignore, 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
  • Stored with each version, but left out of installs and archives (like CHANGELOG.md)
  • 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, tessl files, 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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.