I spent an evening reviewing Addy Osmani’s agent-skills against my own. The overlap was bigger than I expected, but so was the pattern I kept seeing: Zod schemas, TypeScript patterns, React conventions. Useful in one codebase, meaningless in the next.
That is the wrong layer to encode. The question is not whether agents can load skills. They can. The question is what those skills should contain.
What to bundle
I added six skills after the review: build discipline, debugging triage, interface design, code simplification, git workflow, and deprecation. I improved the existing ones with ideas like severity labels, change sizing, and Chesterton’s Fence. The full set is seventeen skills now, covering plan through review.
Acolyte makes skills first-class tools. skill-list returns available skill names and descriptions, skill-activate loads a skill into the session. The agent sees the index, recognizes when structured guidance would help, and pulls in the right skill without me asking.
Universal and project-specific
Not all skills belong in every project. Build discipline, debugging triage, and the review orchestrator apply everywhere. A benchmark skill that runs a specific script and updates a specific doc does not.
So the skills split into two sets. Fifteen universal skills ship with Acolyte and work in any project. Four project-specific skills stay in the repo. The universal ones are embedded in the binary via build-time text imports — the agent has engineering knowledge the moment it starts, not after someone copies files into the right directory.
Methodology, not opinions
Making skills universal forced a harder question: what is actually universal? The first pass had Zod schemas, TypeScript patterns, bun run verify, React effect discipline. All useful in Acolyte, all meaningless in a Python project or a Go CLI.
The real value in a debugging skill is not which test runner to call. It is the triage structure: stop, reproduce, localize, fix root cause, guard with a test. The real value in a build skill is not the commit format. It is the discipline: one slice, verify, commit, repeat. Strip away the project-specific details and you are left with engineering methodology that works anywhere.
So the bundled skills became language-agnostic and project-agnostic. The project-specific knowledge moved to where it belongs: project rules that are always loaded, and a project skill that the agent can activate when it needs deeper context about the codebase it is working in.
Three layers, each with a different job. Bundled skills carry universal methodology. Project rules carry invariants. Project skills carry the map. The full set is documented at acolyte.sh/skills.
Teaching, not constraining
There is a pattern here that connects to the broader direction of Acolyte. I removed behavioral guards because they constrained the model instead of supporting it. I removed modes because they imposed my assumptions about workflow. Now I am adding skills, which sounds like the same thing, but the mechanism is different.
Guards and modes were always-on constraints. The model could not opt out. Skills are on-demand knowledge. The model activates them when it recognizes the situation calls for structured guidance. The difference is agency. A constraint says “you cannot do this.” A skill says “here is how to do this.”
That is closer to how engineers actually work. Nobody follows a debugging checklist on every keystroke. But when something breaks, a good engineer has a mental model for triage: stop, reproduce, localize, fix root cause, guard with a test. The skill encodes that mental model so the agent can reach for it when it needs it.
The goal is not an agent that follows rules. It is an agent that knows how to be an engineer.