Skills
A skill is deep procedural context that W1 loads only when the task calls for it — the way you would hand a new colleague the runbook, not recite it every morning.
What a skill is#
A skill is a folder with a SKILL.md in it. It holds a procedure — how your team does releases, how a client's brand copy is written, which five commands verify a deploy — in enough detail that W1 can follow it without you explaining it again.
W1 sees a one-line index of every available skill at all times, and loads the full text of one only when the task calls for it. That is the whole design: you can have forty skills installed without any of them costing you anything until the day one is relevant.
Skills are where depth belongs.
Project instruction files are read on every turn, so they should stay short. A long procedure belongs in a skill, which is read on the turn that needs it.
Where W1 looks#
Skills are discovered from your project folder, in this order, least specific first:
<project>/.codex/skills/
<project>/.claude/skills/
<project>/.agents/skills/
<project>/.w1/skills/
<project>/skills/If you already keep skills for another agent, W1 finds them where they are — you do not need to copy or convert anything. The same skill vendored into several of those directories collapses to one entry rather than appearing three times, and an explicit <project>/skills/ copy wins over one sitting in a tool directory.
Alongside your project's skills, W1 ships a set of bundled ones, and plugins can carry their own. A project skill overrides a bundled skill with the same name.
Writing one#
The minimum is a folder and a SKILL.md with frontmatter:
---
name: deploy-check
description: Verify a production deploy — the five checks that must pass, in order, and what each failure means. Use after any deploy to the live site.
---
# Deploy check
## 1. The build actually shipped
...Both fields are read from the first line they appear on, so keep each one on a single line — a YAML block scalar (description: >) is not parsed, and the skill will load with an empty description.
Two fields carry the weight:
name— what W1 calls it. Keep it short and specific.description— this is the only part W1 sees before deciding to load the skill, so it has to say both what this is and when to use it. "Release process" is a bad description. "Run a full release: version bump, changelog, tag, publish, and the smoke tests that gate it — use when asked to cut a release" is a good one.
Everything after the frontmatter is ordinary Markdown, loaded in full when the skill is read. Put the real detail there: exact commands, the order they run in, what each failure mode means, the things that look fine but are not.
Verify the verifier.
A skill that references a script, a path or a flag that no longer exists reads as authoritative right up until it ships the wrong thing. When a skill's commands drift from the repo, fix the skill — a stale skill is worse than no skill.
Larger skills#
A skill that has grown too big for one file can be a cluster: a short router in SKILL.md that describes the sub-topics, with the detail in leaf files next to it. W1 reads the router first and then only the leaf it needs. Mark it with cluster: true in the frontmatter.
When a skill fires#
W1 reads a skill when the task matches its description, not because you invoked it by name — although you can ask for one by name and it will. If a skill you expected to be used was not, the description is almost always the reason: it described what the skill is without saying when it applies.