# Openkata Rule Conventions

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

- Skill: `tovrleaf/openkata-rule-conventions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tovrleaf/openkata-rule-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tovrleaf/openkata-rule-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tovrleaf (https://skillmd.com/u/tovrleaf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tovrleaf/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/<name>/`
   - **Distributable** → `rules/<name>/`

2. **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-name>` rule.
   ```

3. **Symlink if distributable** — For rules in `rules/`, ask
   the user if they want it symlinked into `.agents/rules/`:
   ```bash
   ln -s ../../rules/<name> .agents/rules/<name>
   ```

4. **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.

5. **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
  - `<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."

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