Tool Engineering · ~7 min

Skills as a Tool-Engineering Surface

The first eleven lessons engineered the typed tool. But a tool isn't the only thing you hand an agent. A skill is a second surface — packaged knowledge the agent discovers and loads — and it answers questions a schema can't.

A JSON schema defines what is structurally valid. It cannot express how to use the tool well — the team convention, the ID-format gotcha, the "don't call this on a closed cycle" rule. That gap is exactly what an Agent Skill fills: a folder with a SKILL.md the agent discovers by description and loads only when the task matches.

1 Knowledge, not behavior

A skill's primary content is what the agent needs to know, not do. Domain rules, ID formats, valid filter values, and quality checklists are knowledge; tool calls and shell sequences are behavior. The Agent Skills open standard defines a skill as a folder with a SKILL.md markdown entrypoint, with scripts as an optional secondary artifact — the core is knowledge, and that is what makes it portable across 30+ tools without modification.

The anti-pattern is the skill script: a skill that embeds tool_call(...) sequences directly. It works in exactly one harness and breaks when that harness's API shifts. A knowledge-only skill tells the agent what good looks like and lets the agent decide how in its own environment.

2 The description is the load gate

Here the course's oldest lesson returns in a new place. A tool's name and description decide whether the agent selects it (Lesson 2); a skill's description decides whether the agent loads it at all. It is the one part always present in context, so it must earn its tokens. The craft is the same shape:

Write the body as a delta from baseline behavior: only the conventions and edge cases the model would otherwise get wrong. The highest-signal section is ## Gotchas — the cases where the model would do something plausible but wrong, naming both the mistake and the correct alternative. That is the same poka-yoke instinct from Lesson 2, moved off the schema and into prose.

3 Three shapes, and a context lever

Skills are not all the same shape. Match the shape to whether the skill carries executable logic — and notice the shapes echo decisions you already know:

A skill can also be forked into an isolated context — Claude Code and VS Code both expose context: fork in the frontmatter. The skill runs in a subagent; only its distilled result crosses back, keeping search hits and intermediate scratch out of the main chat. That is Lesson 11's cost ledger again: the auxiliary tokens never enter the window you're budgeting.

4 When a skill is the wrong surface

The discipline's standing caveat reappears, sharpened for packaging. A skill is overhead when:

• The knowledge is too sparse — one URL or one rule is better inline or in CLAUDE.md; a skill adds indirection without payoff.
• Portability isn't a goal — single-tool, single-developer projects gain nothing from the cross-tool format.
• The API changes daily — a skill with stale Gotchas is worse than no skill; it actively misdirects.
• The library is large — past ~40 skills, descriptions get truncated to fit, stripping the trigger words that drive selection. The selection cliff (L9) has a skills twin.

And the security note that scales with reuse: each skill from an external registry is a prompt-injection vector. A published audit of 3,984 skills found 13.4% with critical-severity issues. Review third-party skills like any other dependency — pinned, reviewed, sandboxed — not trusted because they loaded cleanly.