Keep agent skills in an open source repo your team reviews

A skill is a folder in the repo, and that is the point

The Agent Skills format is an open standard, and a skill is a directory containing, at minimum, a SKILL.md file. The frontmatter carries name and description; the Markdown under it is the instruction set. Scripts go in scripts/, reference documents in references/, and templates, images or data in assets/.

In a Kortix project the path is skills/<name>/SKILL.md, and reference files can sit beside it. The line that decides which agent may load it lives in kortix.yaml, in the same repository and the same change request as the file itself.

A skill typed into a settings screen has no diff and no author you can ask. Held in the repository it has both, plus a history you can read next quarter. When an instruction turns out to be wrong, the fix becomes a patch, and a patch can be reviewed by someone who did not write it.

The format is built for that kind of loading, and the Agent Skills specification sets the budget. Metadata is about 100 tokens and loads for every skill at startup; the full SKILL.md body loads when the skill is activated, with under 5,000 tokens recommended; bundled files load only when read. A repository can hold ten skills without putting ten instruction sets in every prompt.

Which copy of a skill a session loads

A session looks in the managed kortix-* skills, then skills/, then .kortix/opencode/skills/; pi also reads harnesses/pi/skills/. The first skill of a name wins.

The managed layer is the one you cannot overwrite. Kortix copies its managed kortix-* skills into every session; a project cannot override one of the same name. A new project commits only skills/kortix-cli, and git ignores the rest in the session. A managed skill reaches an agent only when the grant list names it, which is why the grant example lists kortix-cli.

What the skills key in kortix.yaml accepts

Which skills an agent may load is a grant in kortix.yaml, set for each agent. A skill in skills/ is usable only when that agent's grant allows it.

The key takes three shapes (read the docs):

• all allows every skill.
• [] allows none.
• A list of names allows those skills.

A name in that list has to match the skill's folder and its frontmatter name. kortix.yaml declares the machine image, connectors and triggers, and secret names and grants. Secret values never appear in the repo, and an agent's skill reach shows up as one line in the diff beside the skill it names.

A change to a skill is a change request

A session clones the project repo onto a new branch named after the session id. The agent commits and opens a change request, and a person with project.gitops.merge reviews and merges it. Session work reaches main through a change request. Merge is default-deny for agents.

That path covers the agent's own instructions too. An agent can edit its own configuration on its session branch and propose the change. A person approves it.

The reviewer has four things to read, and only the first is obvious:

• the body change, in the skill's own language;
• new files under references/ or scripts/, which load later and are easy to miss in a collapsed diff;
• the description line, when the trigger changed, because description is what the agent reads to decide when to load the skill;
• the lockfile entry, when the skill comes from another repository.

Pinning a skill that lives in another repository

skills-lock.json pins each skill by source repository, skillPath and a computedHash, in the same spirit as a dependency lockfile. A ref pins a tag as well.

The hash is the part that earns its keep. Upstream can rewrite a skill whenever its maintainers like; your copy stays the one you reviewed until somebody bumps the hash, and the bump appears as a one-line diff in the same change request as the decision to take it. A skill with no hash is a floating instruction that changes under you, quietly, between two runs of the same agent. Kortix's own repository is the worked example. Kortix keeps its own skills as folders under .agents/skills/ in the repository, each one a SKILL.md, from kortix-brand and kortix-release to ponytail, composio and agent-browser, and pins the borrowed ones in skills-lock.json.

Validate the file before anyone reads the diff

The specification's reference library skills-ref validates a skill's frontmatter and naming: skills-ref validate ./my-skill. It settles the mechanical questions, the ones a reviewer should not spend time on. name is 1 to 64 characters of lowercase letters, digits and hyphens, and must match the folder name. description is 1 to 1024 characters, and should say both what the skill does and when to use it. Optional fields such as compatibility and metadata carry limits the validator checks for you. The specification also recommends keeping the main SKILL.md under 500 lines and moving reference material into separate files.

Validation answers whether the file is legal. It cannot answer whether the skill belongs in the repository, which is what the reviewer and the change request are for.

The failure mode: a skill nobody can audit

Four projects copy the same skill folder. Three of them edit their copy. Nobody owns the fourth. The grant list says all, because enumerating names took five minutes nobody had, and no lockfile records which upstream commit is folded into the version now running. Months later a behavior change has to be traced back to an instruction file that no person read before it shipped.

Nothing in that story is exotic. It is the default outcome of treating instructions as text in a box rather than as a file with an owner, and it costs more to untangle than the setup would have cost on day one.

The fix is unglamorous: one folder per skill, a named grant list per agent, a hash on every skill that comes from elsewhere, and a merge that a person performs. Then the question a team actually asks in an incident, which instructions did this agent run last Tuesday and who approved them, has an answer in a git repo you own. That is the setup Kortix runs on. Open source. Read it, fork it, audit it.