# Kiln Conventions

Kiln's code conventions and per-area gotchas, plus a diff gate that enforces the...

- Repository: https://github.com/Kiln-AI/Kiln (5247 stars)
- Category: Writing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add Kiln-AI/Kiln --skill kiln-conventions -g -a claude-code -y`
Codex: `npx skills add Kiln-AI/Kiln --skill kiln-conventions -g -a codex -y`
Cursor: `npx skills add Kiln-AI/Kiln --skill kiln-conventions -g -a cursor -y`
Gemini CLI: `npx skills add Kiln-AI/Kiln --skill kiln-conventions -g -a gemini-cli -y`

## Description

Kiln's code conventions and per-area gotchas, plus a diff gate that enforces the mechanical ones. Invoke before writing or changing any Python, TypeScript or Svelte code in the Kiln repo (libs/core, libs/server, app/desktop, app/web_ui), and when reviewing such a change. Covers comments, startup and entry points, globals and module state, config reads, module layering, library-vs-app rules and async I/O.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# kiln-conventions

One set of rules for how code is written in Kiln, the facts about the current code that are easy to get wrong, and a cheap check on the lines you add. Existing code is grandfathered: the rules apply to what your change adds or modifies.

Docs-only and spec-only changes don't need this skill.

## 1. Read the rules

Read `references/rules.md` in full. It is short, and every rule has a ❌/✅ example.

## 2. Read the reference for each area you touch

Pick the references from the paths you are editing. Read only those.

| Paths | Reference |
|---|---|
| `libs/core/**` | `references/core.md` |
| `libs/server/**`, `app/desktop/**` | `references/server_desktop.md` |
| `app/web_ui/**` | `references/web_ui.md` |

UI changes (anything under `app/web_ui` that renders) also need the `kiln-ui` skill (`.agents/skills/kiln-ui/SKILL.md`) for visual design and house controls. This skill covers code structure only.

## 3. Write the code

Follow the rules even where the surrounding code doesn't (rules.md H24). Don't copy a nearby pattern that breaks a rule, and don't rewrite neighbouring code to comply unless your change already touches it.

## 4. Run the gate on your change

From the repo root:

```
uv run python .agents/skills/kiln-conventions/scripts/conventions_gate.py --worktree               # uncommitted changes + untracked files
uv run python .agents/skills/kiln-conventions/scripts/conventions_gate.py --range origin/main...HEAD  # a branch or PR
uv run python .agents/skills/kiln-conventions/scripts/conventions_gate.py --files <path>...          # whole files or directories (audits)
```

It prints one line per hit, `SEV<TAB>RULE<TAB>path:line<TAB>snippet`, then a summary. Exit 1 means at least one FAIL.

The rest: https://github.com/Kiln-AI/Kiln/blob/HEAD/.agents/skills/kiln-conventions/SKILL.md