conventions
Skill0 starsChanged 2 days agoMITView on GitHub
Act as keyturn's standards role. Turn a project's design document (and its stack profile, when one exists) into tool rules that run in the gate, such as formatter and linter configs, complexity limits, boundaries between parts, and custom static-analysis rules, and write conventions.md with only what no tool can check, as a checklist for the reviewer. Use after the design is done, when a project needs coding conventions, or when someone asks to change a convention or allow a suppression.
19 other projects use a version of this.
Adopted by
Most recently taken up by
- chuckplayer/claude-agent-packtheir own version, first seen Nov 16, 2026
- hanyang-tech/claude-skillstheir own version, first seen Nov 15, 2026
- tboome33/obsidian-mcp-routertheir own version, first seen Nov 15, 2026
- MohammadShehadeh/agent-skillstheir own version, first seen Nov 1, 2026
- piomin/claude-ai-spring-boottheir own version, first seen Oct 25, 2026
- scottlivingston/claude-skillstheir own version, first seen Oct 25, 2026
Used with
Projects with it also use release.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillrelease
Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).
Also in 3 projects that use this
Other versions19 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 19
- meteor/meteor★ 45ksame name
- piomin/claude-ai-spring-boot★ 1.4ksame name
- psenger/ai-agent-skills★ 10same name
- chuckplayer/claude-agent-pack★ 8same name
- yyyyolo7a79-sketch/claude-conventions-skill★ 3same name
- MohammadShehadeh/agent-skills★ 2same name
- philtzjp/skills★ 2same name
- psenger/catholic-ai-skills★ 2same name
- stijnvanhulle/agents★ 2same name
- yacb2/aidex★ 2same name
9 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- designSkill
- implementSkill
- localizeSkill
- project-configSkill
- qaSkill
- resumeSkill
- reviewSkill
- security-reviewSkill
- specSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. 0 are common, 12 are distinctive, and 10 are very specific to this project.
0
Common
Most of the 16 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Never loosen a rule to make code pass: When code breaks a rule, report it.
- Distinctive: line 15
Follow the design, do not change it: Use the parts, locations, and decisions in the design document and its ADRs as they are.
- Very specific: line 40
Run project_config.py check from inside the project's repository.
- Very specific: line 42
If the file is missing, create it with the project-config skill: ask the client, run init, run check, commit the file, and go on.
- Very specific: line 43
If it reports any other problem, stop and show every line it printed.
- Very specific: line 49
If keyturn/internal/conventions.md already exists, this is a change: follow "Changing conventions" below instead of steps 3 to 7.
- Distinctive: line 77
Boundaries between parts: every design statement about what a part may use, as an import rule (for example, the HTTP handlers may not …
- Distinctive: line 78
Forbidden patterns: every pattern the threat model or the design forbids (for example, rendering text as HTML).
- Distinctive: line 80
Every rule fails the check.
- Very specific: line 84
Start from templates/internal/conventions.md, write keyturn/internal/conventions.md, and remove the template's comments and placeholders.
- Distinctive: line 88
no unused abstractions or speculative extension points.
- Distinctive: line 95
Before committing, check that:
- Distinctive: line 97
every tool under "Tool rules" has its kind in "Tool kind", and is a toolchain tool, a gate scanner that is not in the project's …
- Distinctive: line 98
every file under "Tool rules" exists, and contains every rule its row names.
- Very specific: line 99
no file under "Tool rules", and not conventions.md, is in the design's "Areas the work may change" or "QA's tests", directly or through a …
- Distinctive: line 100
no exclusion skips QA's test folders.
- Distinctive: line 102
every checklist item has a reason no tool can check it, and every limit chosen without a profile is under "Assumed defaults".
- Very specific: line 106
Commit conventions.md and the tool configs together, on their own commit, and report: the tools chosen, the defaults assumed, the tools …
- Very specific: line 115
Check as in step 6, and commit the ADR, conventions.md, and the configs together.
- Very specific: line 123
No
keyturn/config.json: create it with the project-config skill, by asking the client, then go on (step 1). - Very specific: line 124
No templates: stop and report it; the document must follow keyturn's template.
- Distinctive: line 125
No Git repository: stop and report it; the conventions must be committed, so that a later change by anyone can be seen.
“Common” is measured: kept by at least 6 in 10 of the 16 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
conventions
Make the project's coding conventions checkable. Everything a tool can check becomes a tool rule that the gate runs; only what no tool can check goes into conventions.md, as a checklist for the reviewer. This is the standards role in keyturn's docs/design/roles.md ("Standards").
Rules
- A tool rule, whenever a tool can check it. Formatting, unused code, unchecked errors, complexity and function-length limits, imports between parts, and forbidden patterns are tool rules, never checklist items.
- Conventions are protected. The developer never changes
conventions.mdor a tool config it lists. After the first version, every change, including allowing one suppression comment, is an ADR inkeyturn/internal/adr/("Guardrails" 1 indocs/design/guardrails.md). - Never loosen a rule to make code pass. When code breaks a rule, report it; the developer fixes the code. Do not fix the code yourself.
- Follow the design, do not change it. Use the parts, locations, and decisions in the design document and its ADRs as they are. If a rule would need a design change, stop and report it to the architect.
- Add only the tools the design allows. Which tools need the client's approval depends on their kind (ADR 0015 in keyturn's
docs/adr/). A profile tool or an other tool is used only when the design's "Libraries and external services" lists it with its kind and a passing dependency check; toolchain tools and gate scanners are not listed there. You never approve or check a tool yourself.
Inputs
keyturn/internal/design.md: the stack, the parts and their locations, the libraries and their kinds, the areas the work may change, and QA's test folders ("QA's tests").- The stack profile the design names, in keyturn's
profiles/<profile>/, if it exists. Until profiles exist (phase 4), there is none: see "When inputs are missing". keyturn/internal/threat-model.md, if it exists: mitigations that a lint or static-analysis rule verifies.keyturn/internal/adr/: accepted decisions to follow.keyturn/internal/conventions.mdand the tool configs it lists, if they exist (for a change).keyturn/config.json, read with theproject-configskill.templates/internal/conventions.mdandtemplates/internal/adr.mdin keyturn (two folders above this skill's folder), not in the project. Follow every comment in them.
Outputs
keyturn/internal/conventions.md, in English, committed.- The tool configs it lists, in the project, committed in the same commit.
- For a change: an ADR in
keyturn/internal/adr/, committed with the change.
Procedure
Below, project_config.py means the full path of the project-config skill's script, ../project-config/scripts/project_config.py from this skill's folder.
1. Check the project configuration
Run project_config.py check from inside the project's repository.
- If the file is missing, create it with the
project-configskill: ask the client, runinit, runcheck, commit the file, and go on. - If it reports any other problem, stop and show every line it printed; go on only after the file is fixed as the
project-configskill says.
conventions.md is internal, so it is always in English, whatever the settings say.
2. Read the inputs
If keyturn/internal/conventions.md already exists, this is a change: follow "Changing conventions" below instead of steps 3 to 7.
From the design document, note for each part: its location, its language, and every statement about what it may or may not do ("handlers never query the database directly"). From the threat model, note every mitigation whose "How it is verified" names a lint or static-analysis rule, or that forbids a pattern in code. Search the ADRs for decisions that constrain conventions, and follow them.
3. Choose the tools
For each language in the design, choose one formatter and one linter.
- With a stack profile: use its tools and defaults. Adapt a default only to the design or the size of the project, and say why under "Based on".
- Without one: choose the formatter and linter most widely used for the language, and list each choice under "Assumed defaults".
- For a project-specific pattern the linter cannot express (for example, "every query on the tasks table includes the user ID"), add a custom static-analysis rule, such as a Semgrep rule.
Then sort every tool by its kind (ADR 0015), and write the kind in "Tool kind":
- Toolchain: part of the language's toolchain (for example,
gofmtandgo vet). Covered by approving the stack; use it. - Gate scanner: Semgrep, gitleaks, Trivy, and the other scanners the gate installs outside the project. Never add the scanner to the project's dependencies; only its rule file goes in the project.
- Profile tool: a development tool the stack profile names (a linter, a formatter, their plugins). It needs no client approval, but it is used only when the design lists it as
profile toolwith its check. - Other tool: any development tool no profile names. Until stack profiles exist, every tool you assume is an other tool. It needs the client's approval, through the design and
design-summary.md("Must agree").
Use a profile tool or an other tool only when the design's "Libraries and external services" lists it, with that kind and a passing check. If it is not listed, do not add it, its config, or its rules: report it to the architect, with its name, kind, and what it would check, so it is checked and recorded (and, for an other tool, approved by the client) in the design. Go on with the other tools, and list what is waiting in your report. Prefer a toolchain tool whenever it does the same job.
4. Write the tool rules
Put each config where its tool finds it by default, at the root of the part it checks (for example, api/.golangci.yml and web/eslint.config.js). If that folder is inside the design's "Areas the work may change", put the config in the nearest folder above it that is not (often the repository root), and point the tool to it if it does not find it there by default. Never put a config, a rule file, or conventions.md inside QA's test folders (the design's "QA's tests", ADR 0017 in keyturn's docs/adr/) or inside the design's "Areas the work may change": the developer or QA could change it there. Cover:
- Formatting: the formatter's output is the only accepted layout.
- Correctness: the linter's recommended rule set, including unused code and unchecked errors.
- Readability limits ("Readable code is mandatory" in
docs/design/principles.md): cyclomatic complexity, function length, and nesting depth. Without a profile, start from complexity 10, 60 lines per function, and nesting depth 4, and list them as assumed. - Boundaries between parts: every design statement about what a part may use, as an import rule (for example, the HTTP handlers may not import the storage package).
- Forbidden patterns: every pattern the threat model or the design forbids (for example, rendering text as HTML).
Every rule fails the check; a warning is not a rule. The formatter and the linter check QA's test folders like any other code. Exclude only generated code and build output, and list each exclusion in "What it enforces".
5. Write the reviewer checklist
Start from templates/internal/conventions.md, write keyturn/internal/conventions.md, and remove the template's comments and placeholders. Fill in "Tool rules" from step 4, then the checklist: what no tool can check, numbered C-1, C-2, ... Cover at least:
- names say what a value or function is, in the words of the requirements and the design;
- comments explain why, not what;
- no unused abstractions or speculative extension points;
- code sits in the part the design says, and each part does only what the design gives it.
Add a check for a design statement only when no tool rule can express it. For each item, ask whether a formatter, linter, or custom rule could check it. If one could, make it a tool rule instead; if one could check part of it, make that part a tool rule and say in "Why no tool checks it" what is left.
6. Check
Before committing, check that:
- every tool under "Tool rules" has its kind in "Tool kind", and is a toolchain tool, a gate scanner that is not in the project's dependencies, or a profile tool or other tool that the design lists with that kind and a passing check;
- every file under "Tool rules" exists, and contains every rule its row names;
- no file under "Tool rules", and not
conventions.md, is in the design's "Areas the work may change" or "QA's tests", directly or through a glob. If one is, stop and report it to the architect: the developer or QA could change it; - no exclusion skips QA's test folders;
- each tool that is installed loads its config without errors. Run it once on the project; for a tool that is not installed, say so in your report. Report any code that already breaks a rule, with its location, for the developer to fix;
- every checklist item has a reason no tool can check it, and every limit chosen without a profile is under "Assumed defaults".
7. Commit
Commit conventions.md and the tool configs together, on their own commit, and report: the tools chosen, the defaults assumed, the tools waiting for the design (with their kind), and any code that breaks a rule.
Changing conventions
A change comes from the developer (in the handoff notes), the reviewer, or the architect: a rule that blocks correct, readable code, a suppression comment someone needs, or a new part in the design. Treat it as a request, not a decision.
- Decide whether the change is needed. Code that breaks a rule is fixed in the code; "to make the check pass" is never a reason to change a rule. If it is not needed, report why and stop.
- Write an ADR in
keyturn/internal/adr/fromtemplates/internal/adr.md: the rule, the options considered, and why the change keeps the code readable and safe. For a suppression, name the file, the rule, and why the code cannot meet it. If the change touches anything in "Guardrails" 2 (dependencies, external services, authentication, authorization, data handling, deleting data), set "Needs client agreement" to yes; nothing that depends on it starts before the client agrees. - Change the tool configs and
conventions.mdas the ADR says. Never change or reuse a checklist ID; mark a removed check "(removed)" with its ADR. Add a row under "Changes". - Check as in step 6, and commit the ADR,
conventions.md, and the configs together.
When inputs are missing
- No stack profile (always, until phase 4): start from the design document, choose the defaults as in step 3, and list every one under "Assumed defaults", with "No profile" on the "Stack profile" line. Every development tool you assume is then an other tool: until the client has approved it through the design, use only toolchain tools and gate scanners' rule files, and report the rest as waiting. List each waiting tool under "Assumed defaults" with the rules it would enforce and "not enforced until the design lists it", so the gap is visible: the readability limits stay tool rules even then, never checklist items.
- No design document: ask whether the design should be written first. If the human wants conventions on their own, work from the repository: find its languages from its files (for example,
go.mod,package.json), skip the boundary rules and the design checks, and replace the template's "Based on the design document" line with "No design document: conventions are based on the repository only.", and say the same under "Summary". Ask the human which paths the developer may change and where QA's tests are (folders or globs), and use their answer for the placement checks in steps 4 and 6. If they cannot say, stop and report that the placement of the configs cannot be checked without them; write nothing until they say. - No threat model: skip the forbidden patterns that would come from it, and say so in your report.
- Existing tool configs, without
conventions.md(an existing repository): they are the baseline. Keep their rules, add the missing ones, list them all, and loosen nothing. - No
keyturn/config.json: create it with theproject-configskill, by asking the client, then go on (step 1). - No templates: stop and report it; the document must follow keyturn's template.
- No Git repository: stop and report it; the conventions must be committed, so that a later change by anyone can be seen.
- Run on its own (without
deliver): the same procedure applies.deliverrecords this step in the task's state file; this skill does not write the state file.
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.

