Skills

A skill is a SKILL.md file with a short frontmatter and Markdown instructions that Kiln hands to agents at the start of each run.

#Where skills live

If an agent skill has the same name as a shared skill, validation warns that it shadows the shared one. An agent skill under an agent directory that has no agent.md is an error.

Other files in a skill directory, such as scripts or examples, are allowed in the tree but are not sent to agents. Only the SKILL.md body is.

#A skill file

---
name: house-style
description: Named exports, zod at boundaries
owner: platform
version: "2"
---
Use named exports. Validate every external input with zod.

#How agents receive skills

At the start of a run, Kiln writes each skill to the harness's skills folder in the repository working copy:

Kiln adds each file it writes to the clone's .git/info/exclude, so the skills never end up in a commit or pull request. Only those files are excluded: the repository's own skills in the same folder stay under version control, and changes to them are committed as usual. If the repository already has a skill with the same name, Kiln does not overwrite it, and the agent uses the repository's version.

The run's start state records the skill names, so a replay uses the same set.

#Sharing skills between factories

Kiln keeps an org-wide catalog of skills. It lists every skill in every factory's applied tree, plus published skills, with owner, version, the factories that use it and a usage count. Usage goes up by one each time a run receives the skill.

• Publish a shared skill from a factory to make it a catalog listing. Publishing again bumps the version unless the skill sets its own version.
• Install a listing into another factory. For a factory with a config repo, Kiln opens a pull request that adds skills/<name>/SKILL.md, labeled kiln:skills. For a Kiln-managed factory, Kiln applies the change directly.

Installing is a definition change, so it goes through the same validation and review as any other.

#Memories

Memories are conventions and decisions a factory has learned, such as "Use named exports". They live in the definition tree as memories/<slug>.md:

---
title: Use named exports
tags: [typescript]
author: implement
---
Learned while building "Add a logo".

How a memory gets there:

1. An agent proposes it by adding memories: [{ "title": "...", "body": "..." }] to its .kiln/result.json, or a person proposes one. A proposal with the same title as an existing one is not duplicated.
2. A person accepts or rejects it. Accepting a memory for a config-repo factory opens a pull request labeled kiln:memory. For a Kiln-managed factory, Kiln applies it directly.
3. On later work runs, Kiln ranks memories against the prompt and adds up to five of them to the agent's instructions under "Factory memories".

#Related pages

• Factory agents
• Definitions as code
• Harnesses
• Self-improvement