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

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.

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
  1. Very specific:

    After the generic create-rule skill workflow, also do:

    line 21
  2. Distinctive:

    Follow the markdown-style rule for formatting.

    line 29
  3. Distinctive:

    Every convention is literally enforceable

    line 56
  4. Distinctive:

    Always ask the user before running destructive commands

    line 71
  5. Distinctive:

    Every rule gets a CHANGELOG.md

    line 75
  6. Distinctive:

    Keep rules focused — one rule, one concern

    line 77
  7. Distinctive:

    Add CHANGELOG.md, symlinks, and ACKNOWLEDGMENTS.md to rules

    line 91
  8. Very specific:

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

    line 96
  9. Distinctive:

    Run tessl commands (rules don't use tessl)

    line 97

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

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

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.

    # 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/:
    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

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.