The Agent Skill Model
An AI coding assistant already knows how to write a Fastify route, upgrade a Node version, or triage a memory leak in general - that knowledge came from its training, not from your team.
//
Search across all documentation pages
An AI coding assistant already knows how to write a Fastify route, upgrade a Node version, or triage a memory leak in general - that knowledge came from its training, not from your team.
What it doesn't know, by default, is which Node version your fleet is on, which HTTP framework your org standardizes on, which log fields are mandatory, or which shortcuts a past incident taught you never to take again. An Agent Skill is how a team encodes that gap - the specific, local, version-pinned decisions - into something an assistant can actually be handed at the moment it needs them, instead of hoping a prompt happens to mention all of it.
This page is the model underneath the rest of this section. Agent Skills Basics shows the concrete anatomy of a SKILL.md file and ten worked examples; API Scaffold Skill, Queue Worker Skill, Node Upgrade Skill, and Incident Triage Skill are each a specific skill built on the shape described here.
SKILL.md - that scopes an AI assistant's default behavior to one team's specific conventions for one recurring backend task.A decision domain is the scope a single skill owns - "scaffold a new API service," "upgrade Node across a fleet," "triage a production incident" - and the first rule of the model is that one skill covers exactly one domain. A skill that tries to cover everything stops being a specific contract and becomes a vague, general-purpose prompt with extra formatting, which defeats the point.
A skill is invoked at a trigger - a moment in the work where its specific guidance applies, rather than sitting passively as background reading the way a wiki page does. "Scaffold a new service," "we're moving to the next LTS," "pods are getting OOMKilled" are all triggers; the skill exists specifically to be reached for at that moment, not browsed ahead of time.
A useful analogy is a runbook handed to a new on-call contractor on their first day. It doesn't re-teach them how Linux or Node works - they already know that. It tells them exactly which conventions apply here: which dashboard to check first, which command is safe to run under pressure, which shortcut past incidents proved was a mistake. That's the difference between a skill and a tutorial - a tutorial builds general knowledge; a skill applies specific, local knowledge at the exact moment it's needed.
Every skill is built from three parts, and a SKILL.md file missing any one of them is closer to a doc than a skill:
OOMKilled pod restarts and a p95 latency jump within an hour of deploy - specific, recognizable conditions, not "when something seems wrong." trigger recognized ──▶ skill loaded ──▶ guardrails applied ──▶ output produced
│ │ │ │
"OOMKilled" in stack pin + "rollback before hypothesis tree,
pod logs decision tree deep profiling" diagnostic commands,
for this domain enforced here comms skeleton
The stack pin - the exact Node/TypeScript/framework versions a skill assumes - exists because an assistant's training data spans years of API history, and without an explicit pin it has no reliable way to know which era of guidance is current for your fleet right now. Every skill in this section states its stack pin in the header for exactly this reason; a skill without one is implicitly trusting the model to guess correctly, which it often won't.
The output side of the contract matters as much as the input side: Agent Skills Basics requires skill outputs to end in verifiable commands - npm test, tsc, npm audit - specifically so a human isn't left evaluating an assistant's prose confidence, but can run something objective and see whether it actually passes.
A skill's guardrails narrow the space of likely mistakes, but they are not a substitute for review - the model producing output under a skill's guidance is still the same underlying model, applying the same reasoning process, just with better local context to reason from. Treating skill output as pre-approved because it followed a contract is a mistake; the contract exists to make output checkable, not to make checking optional.
Skills also age, the same way any version-pinned artifact does. A skill written against Node 20 as Active LTS becomes actively misleading once the fleet moves to 24 - not neutral, actively wrong, because it will confidently apply outdated guardrails to a newer runtime. Node Upgrade Skill is itself an example of a skill whose entire job is keeping the rest of the fleet's stack pins current, which makes skill maintenance a genuine ongoing cost, not a one-time authoring task.
There's a real security dimension specific to skills that scaffold code: a guardrail like "never hardcode secrets, always reference the platform's secret manager" is only valuable if it's explicit, because a generic assistant asked to "add config for a database connection" has no way to know your org's convention is environment injection rather than a literal connection string in a file.
Skills are deliberately positioned as a layer on top of existing human documentation, not a replacement for it - Agent Skills Basics states this directly: human cookbook pages remain authoritative, and a skill's job is to route an assistant to the right convention at the right moment, not to become the new source of truth itself.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Raw prompting, no skill | Fast to start, no maintenance overhead | Drifts to generic training defaults; conventions repeated (or forgotten) every time | One-off, low-stakes tasks with no house convention to violate |
| Agent Skill (this model) | Encodes specific, version-pinned conventions; reusable across the team | Needs authoring and upkeep as the stack evolves | Recurring, decision-domain-scoped tasks with a real cost to getting defaults wrong |
| Full agent autonomy, no human review | Fastest iteration loop, no human bottleneck | No objective check on output; guardrails alone don't catch everything | Rarely appropriate for production backend changes - even skill-guided output benefits from review |
A structured SKILL.md contract - triggers, inputs/outputs, guardrails, and a stack pin - that scopes an AI assistant's behavior to one team's specific conventions for one recurring backend task.
Documentation is written for a human to read and internalize over time; a skill is written to be invoked at a specific trigger and to produce a checkable output. A skill without triggers, an input/output contract, and guardrails is functionally just a doc with extra formatting.
You can, but it doesn't scale - conventions get forgotten, phrased inconsistently, or simply omitted under time pressure, and the assistant quietly falls back to its generic training defaults whenever a specific instruction is missing. A skill exists precisely so that context doesn't depend on someone remembering to type it out correctly every time.
Triggers (when to invoke it), an input/output contract (what it needs and what it produces), and guardrails (explicit boundaries on what it should never do). A SKILL.md missing any of the three is closer to a passive doc than an invocable skill.
Because an assistant's training data spans multiple years of API and framework history, and without an explicit pin it has no reliable way to know which era of guidance currently applies to your fleet - the pin removes that ambiguity outright.
It's the specific scope a skill owns - scaffolding, upgrades, incident triage, queue setup. Limiting a skill to one domain keeps its triggers and guardrails specific and checkable; a skill that tries to cover everything degrades into a vague general-purpose prompt.
No - a skill's guardrails reduce the likelihood of a wrong default, but the output still needs to pass the same objective checks (tests, type checking, audit) and the same human review any other change would. Skill outputs are explicitly required to end in verifiable commands for this reason.
An AI coding assistant, at the moment its trigger condition is recognized - either because a human explicitly invokes it or because the assistant's tooling matches the current task to a known skill's trigger.
Yes, and arguably faster, because a stale skill doesn't just become outdated - it actively and confidently applies old guardrails and version pins to a newer stack, which is worse than no guidance at all. Node Upgrade Skill exists specifically to keep other skills' stack pins current.
It shouldn't by design - skills are meant to route to and reinforce the authoritative human documentation, not diverge from it. A skill that drifts out of sync with its referenced cookbook pages is a sign the skill itself needs updating.
No - a guardrail is an instruction shaping what the assistant should avoid doing while producing output; a test is an objective, automated check run against the output afterward. Guardrails reduce how often a test needs to catch something in the first place, but they don't replace running it.
A one-off task with no repeated convention to encode and no real cost if the assistant's generic default is used - writing a skill for something that will only ever come up once is pure overhead with no return.
Stack versions: This page was written for Node.js 24.18.0 (Active LTS), TypeScript 5.6+, Fastify 5, and NestJS 11.
Reviewed by Chris St. John·Last updated Jul 15, 2026