openkata-rule-conventions
Skill1 starsChanged 17 days agoMITView on GitHub
Applies OpenKata project conventions when creating or updating rules in this repository. Creates CHANGELOG.md, places symlinks for distributable rules, and writes ACKNOWLEDGMENTS.md for externally sourced rules — on top of the generic create-rule workflow. Use when adding a rule to OpenKata, creating a new kata rule, setting up a rule in this repo, or updating an existing OpenKata rule alongside create-rule.
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-ryu-releaseSkill
- openkata-skill-conventionsSkill
- 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
9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
After the generic create-rule skill workflow, also do:
- Distinctive: line 29
Follow the markdown-style rule for formatting.
- Distinctive: line 56
Every convention is literally enforceable
- Distinctive: line 71
Always ask the user before running destructive commands
- Distinctive: line 75
Every rule gets a CHANGELOG.md
- Distinctive: line 77
Keep rules focused — one rule, one concern
- Distinctive: line 91
Add CHANGELOG.md, symlinks, and ACKNOWLEDGMENTS.md to rules
- Very specific: line 96
Create the rule itself (that's create-rule)
- Distinctive: line 97
Run tessl commands (rules don't use tessl)
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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 Rule Conventions
Project-specific additions to the create-rule workflow. This
skill activates alongside the generic create-rule and adds
OpenKata conventions.
Additional Steps
After the generic create-rule skill workflow, also do:
- Determine placement — Ask whether this rule is:
- Local →
.agents/rules/<name>/ - Distributable →
rules/<name>/
- Local →
Create CHANGELOG.md — Every rule gets a changelog starting at v1.0.0 with an initial
### Addedentry. Follow the markdown-style rule for formatting.# Changelog ## [1.0.0] - YYYY-MM-DD ### Added - Initial release of `<rule-name>` rule.- Symlink if distributable — For rules in
rules/, ask the user if they want it symlinked into.agents/rules/:ln -s ../../rules/<name> .agents/rules/<name> - Acknowledge sources — If the rule draws on external
style guides or standards, create
references/ACKNOWLEDGMENTS.mdlisting each source with a link, license, what was adapted, and the version it was adopted in. - Quality check (mandatory gate) — Do not commit until
all checks pass:
- Pass the rule design checklist from
create-rule - Every convention is literally enforceable
- RULE.md is under 100 lines
- Pass the rule design checklist from
Naming
- Distributable rules: no prefix, pattern-based
<domain>-style— formatting/coding conventions<domain>-naming— naming conventions<domain>-system— system-level constraints
- Local rules: always
openkata-prefixed
Conventions
- Rule names are lowercase-hyphenated:
git-naming,markdown-style - Always ask the user before running destructive commands
- Local rules go in
.agents/rules/<name>/ - Distributable rules go in
rules/<name>/with a symlink in.agents/rules/ - Every rule gets a CHANGELOG.md
- Changelogs document rule-facing changes only
- Keep rules focused — one rule, one concern
Example Scenario
User: "Create a rule for SQL naming conventions."
- create-rule produces
rules/sql-naming/RULE.md - This skill activates: asks local or distributable?
- Creates CHANGELOG.md, symlinks into
.agents/rules/, adds ACKNOWLEDGMENTS.md referencing the SQL style guide
Boundaries
DOES:
- Add CHANGELOG.md, symlinks, and ACKNOWLEDGMENTS.md to rules
- Determine placement (local vs distributable)
- Enforce quality gate before commit
Does NOT:
- Create the rule itself (that's
create-rule) - Run tessl commands (rules don't use tessl)
- Publish or release rules
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.

