Openkata Rule Conventions

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:

1. Determine placement — Ask whether this rule is:

• Local → .agents/rules//
• Distributable → rules//

1. Create CHANGELOG.md — Every rule gets a changelog

starting at v1.0.0 with an initial ### Added entry. Follow the markdown-style rule for formatting.

```markdown # Changelog

## [1.0.0] - YYYY-MM-DD

### Added

• Initial release of `` rule.

```

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

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

1. Acknowledge sources — If the rule draws on external

style guides or standards, create references/ACKNOWLEDGMENTS.md listing each source with a link, license, what was adapted, and the version it was adopted in.

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

Naming

• Distributable rules: no prefix, pattern-based
• -style — formatting/coding conventions
• -naming — naming conventions
• -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//
• Distributable rules go in rules// 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."

1. create-rule produces rules/sql-naming/RULE.md
2. This skill activates: asks local or distributable?
3. 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

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.