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.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- openkata-eval-runnerSkill
- openkata-optimize-skillsSkill
- openkata-review-ruleSkill
- openkata-review-skillSkill
- openkata-rule-conventionsSkill
- openkata-ryu-releaseSkill
- commit-conventionsSkill
- create-adrSkill
- create-evalsSkill
- create-profileSkill
- create-ruleSkill
- create-skillSkill
- critical-thinkingSkill
- github-create-prSkill
- git-worktreeSkill
- grill-meSkill
- grill-with-docsSkill
- makefile-conventionsSkill
- spec-workflowSkill
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
- Very specific: line 19
After the generic create-skill workflow, also do:
- Distinctive: line 27
Follow the markdown-style rule for formatting.
- Very specific: line 52
After the quality check passes, persist the review score to .tessl-plugin/plugin.json (set the "score" field to the numeric percentage).
- Distinctive: line 77
Always ask the user before running Tessl commands — do not run lint, review, or optimize without confirmation
- Very specific: line 82
Every skill must have a .tessl-plugin/plugin.json generated by tessl skill import, and a .tesslignore
- Distinctive: line 84
Every skill gets a CHANGELOG.md
- Distinctive: line 87
Keep distributable skills self-contained and portable.
- Very specific: line 102
Every distributable skill and rule should include a RATIONALE.md at its root.
- Distinctive: line 112
Keep entries concise — a paragraph per decision
- Distinctive: line 126
Add changelog, tessl files, symlink, and acknowledgments to skills
- Very specific: line 131
Create the skill itself (that's create-skill)
- Very specific: line 132
Run tessl review/optimize (that's openkata-review-skill)
≈ “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.
Files
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:
- Determine placement — Ask whether this skill is:
- Local →
.agents/skills/<name>/ - Distributable →
skills/<name>/
- Local →
- Create CHANGELOG.md — Every skill gets a changelog
starting at v1.0.0 with an initial
### Addedentry. Follow the markdown-style rule for formatting. - Import to Tessl — Run
tessl skill import --workspace openkata <skill-directory>to generate.tessl-plugin/plugin.json(ADR 0006). The--workspace openkataflag ensures the correct prefix. - Create
.tesslignore— Add a.tesslignorefile to the skill directory containingCHANGELOG.mdandevals/. - 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> Quality check (mandatory gate) — Do not commit until all checks pass. Follow the
review-skillworkflow 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).- Score 95%+ on
- Acknowledge sources — If the skill draws on external
practices, add or update
references/ACKNOWLEDGMENTS.mdwith 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 filereview-<artifact>— evaluates quality<domain>-conventions— enforces standards<name>-workflow— multi-phase process
- Local skills: always
openkata-prefixedopenkata-review-<artifact>— repo-specific reviewopenkata-<domain>-conventions— repo-specific standardsopenkata-<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.jsongenerated bytessl 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
metadatablock forversionandtags: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."
- create-skill produces
skills/migrate-database/SKILL.md - This skill activates: determines distributable placement
- 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
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
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.

