The Agent Skill Model
An agent skill is a structured playbook, written as a SKILL.md file, that tells an AI assistant exactly what to do, what to ask for, and what never to do on a specific database task.
//
Search across all documentation pages
An agent skill is a structured playbook, written as a SKILL.md file, that tells an AI assistant exactly what to do, what to ask for, and what never to do on a specific database task.
This page builds the mental model behind that structure for PostgreSQL 18.4 teams: why a skill looks the way it does, how its parts interact, and where it stops and human judgment begins.
A skill exists to answer one narrow question well, and that narrowness is deliberate rather than a limitation.
Each SKILL.md file names a single decision domain - migration lock-risk scoring, EXPLAIN plan critique, a Patroni failover drill, or SEV1 incident triage - and does not try to cover general database knowledge.
The file itself is structured, not prose, with fixed sections: what the skill does, when to invoke it, its required inputs, its expected outputs, and its guardrails.
Guardrails are the section that makes a skill different from a tutorial, because a tutorial teaches a human how to think while a guardrail tells an agent what it is never allowed to do regardless of context.
A useful analogy is a pilot's checklist: it does not explain aerodynamics, it constrains a specific, repeatable decision to a known-safe procedure every time it runs.
Skills live beside the platform or application repo, typically under a path like .cursor/skills/ or an organization-wide registry, so they travel with the codebase they govern.
Human cookbook pages elsewhere on this site, such as the EXPLAIN and migration sections, remain the authoritative source of database knowledge; a skill only orchestrates how an agent should apply that knowledge in the moment.
The reason skills need a stack pin at all is that a language model's training data has a cutoff, and Postgres has kept moving past it.
Without an explicit pin, an agent will default to older idioms - SERIAL instead of IDENTITY, or a plain CREATE INDEX where CONCURRENTLY is required - because those patterns dominated its training distribution.
Pinning the stack inside the skill file itself, rather than trusting the agent to infer it, turns an implicit assumption into an explicit, auditable constraint that travels with every invocation.
Guardrails interact with outputs in a specific way: a well-formed skill never lets an agent claim success without producing something a human can independently verify, such as a lock-check query or a staging migration log.
This is the difference between an agent asserting "the index migration is safe" and an agent producing the actual pg_locks query a reviewer can re-run to confirm that claim.
Skills also compose, meaning one invocation's output can become the trigger for the next: a migration safety score above a threshold can hand off to an EXPLAIN review of the query the new index is meant to serve.
The snippet below shows the shape of that hand-off contract as it might appear inside a skill file's Outputs section, kept intentionally small since the point is the shape, not the full playbook.
## Outputs
- Lock risk score (low/medium/high)
- Safer DDL alternative if applicable
- Verification query a human can re-run on staging
## Guardrails
- Never suggest non-CONCURRENT index on a hot production table
- Never execute DDL without explicit human approvalThat structure is what lets a reviewer trust the output without re-deriving it from scratch.
The most consequential design choice in a skill file is what belongs in guardrails versus what belongs in guidance, and mature teams tend to write their guardrails directly from postmortems.
Every SEV1 or SEV2 incident that traced back to an agent-suggested action is a candidate for a new guardrail line, which means the guardrail section is effectively a team's accumulated near-miss history in executable form.
A skill's authority is also bounded by scope: a migration-safety skill should never silently expand into query-optimization advice, because mixing decision domains erodes the narrowness that made the contract trustworthy in the first place.
Team invocation policy matters as much as the file contents, since a skill that anyone can trigger against production without a named human approver defeats the guardrail model entirely.
At scale, organizations maintain a skill registry - an index mapping each skill to its trigger condition and an owning rotation - so that "who do I ask" and "which skill applies" are answered the same way every time.
As Postgres itself evolves across major versions, every skill's stack pin becomes a maintenance liability that has to be revisited on the same cadence as the cluster's own upgrade calendar.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| No skill, ad hoc prompting | Fastest to start, zero maintenance | Agent defaults to stale training-data assumptions every time | One-off exploratory questions, not repeated operational tasks |
| Skill without enforced guardrails | Faster authoring, lower review overhead | Nothing stops an agent from proposing an unsafe action | Low-stakes read-only tasks like documentation lookups |
| Full skill contract (trigger + inputs + guardrails + verifiable outputs) | Reproducible, auditable, safe to hand to less-experienced operators | Requires ongoing authorship and postmortem-driven upkeep | Any recurring high-stakes decision: migrations, failover, incident response |
A structured SKILL.md file that constrains an AI assistant to one decision domain - like migration safety or EXPLAIN review - with explicit inputs, guardrails, and verifiable outputs.
Because a language model's training data predates current idioms, and without an explicit pin it will default to older syntax and less safe defaults than a modern cluster actually needs.
The guardrails section, since it encodes the specific actions a team has already learned - often through a postmortem - that an agent must never take.
Yes - a common pattern is one skill's output becoming the trigger for a second skill, such as a migration score handing off to an EXPLAIN review of the affected query.
No - the human pages remain the authoritative explanation of the underlying concept, and the skill only governs how an agent applies that concept in a specific moment.
That overlap is itself a signal the skill registry needs tightening, since ambiguity about which playbook applies undermines the whole point of having narrow, named skills.
No - even a fully guardrailed skill is designed to produce a proposal and verification steps for a human to approve, not to execute changes unsupervised.
Most teams write a new guardrail line directly from each postmortem, turning a specific near-miss or incident into a permanent constraint on future invocations.
Typically beside the platform or application code they govern, such as .cursor/skills/, so the playbook travels with the same version history as the schema it operates on.
It's an output a human can independently re-run and confirm, like a lock-check query, rather than a bare claim of success that has to be taken on faith.
The specific decision domains here are Postgres-flavored, but the contract shape - trigger, inputs, guardrails, verifiable outputs - is a general pattern for any high-stakes, repeated operational task.
Stack versions: This page was written for PostgreSQL 18.4 clusters using Patroni 3.x for high availability; specific migration-runner and backup-tool versions referenced by individual skills are pinned on their own pages.
Reviewed by Chris St. John·Last updated Jul 15, 2026