How chisel works

Chisel is a pair of deterministic checkers and a set of agent skills that teach the same patterns. The two halves only make sense together.

Roles

• Checker (chisel / chisel-js): a deterministic program that finds rule violations in real code. It never reasons; it just finds them.
• Skills (skills/*/SKILL.md): structured Markdown an LLM reads to learn the patterns for a layer. A skill is advice: it explains why and how.

Two checkers enforce the rulebook, six skills teach it. Backend and frontend follow the same architectural intent.

The loop

The agent writes code. It may have read a skill first, or it may not have. That is the point: chisel check . runs after the code exists, and every violation names the skill that teaches the pattern it skipped. The agent gets pointed at your preferences at exactly the moment it violated them. It runs chisel explain <rule-id> for the fix, reads the skill, fixes, and re-checks. When the check exits zero, the loop ends.

The same loop works for a human at a keyboard, a pre-commit hook blocking a commit, or CI failing a pull request. The contract is identical.

What skills are

Each skill is a small Markdown document that explains the architectural patterns for one layer. Chisel ships six:

Skill	Teaches	Used by
architecting-fullstack	monorepo layout (Pattern A TS-monolith vs Pattern B BFF)	both
building-python-backend	FastAPI service/controller/repository patterns	chisel
building-sveltekit-frontend	$effect, onMount, store patterns	chisel-js
designing-svelte-ui	shadcn component rules, Tailwind tokens	chisel-js
qa	one-assert-per-test, fakes over mocks	both
planning-features	feature planning / decomposition	both

Every rule is cross-referenced to the skill that teaches it: chisel check . --json embeds skill_name on every message so an agent knows what to read next.

Why one target per run?

Tools like OpenCode discover skills from more than one directory. If Chisel wrote the same skill into both .agents/skills/ and .opencode/skills/, the tool would surface it twice. So you pick one --target per run, and re-run to install into another directory.

Severity tiers

ERRORblocks · not suppressible · always a real bug or architectural violation

WARNINGblocks · suppressible with a reason · a strong convention you can opt out of

INFOnever blocks · logged for awareness

Suppression is per-line: # noqa: rule-id — reason (Python) or <!-- noqa: rule-id — reason --> (Svelte). See Turn off a rule for a file for project-level exemptions too.

---

Next: Where this fits in agentic engineering →