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.
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.
Summary
- Core Idea: A skill is an operational contract with fixed parts - trigger, inputs, guardrails, outputs - that constrains an agent to one decision domain at a time.
- Why It Matters: Without a contract, an agent falls back on generic training-data assumptions, which routinely means outdated syntax and unsafe defaults on a modern, version-pinned cluster.
- Key Concepts: decision domain, guardrails, stack pin, verifiable output, skill composition.
- When to Use: Reach for this model whenever you are deciding whether a task belongs to a skill invocation, a human runbook, or plain conversation with the agent.
- Limitations / Trade-offs: A skill only ever encodes what its authors have already learned, so it is a lagging artifact that must be updated after every relevant incident or policy change.
- Related Topics: migration safety scoring, EXPLAIN plan review, failover drills, incident triage.
Foundations
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.
Mechanics & Interactions
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.
Advanced Considerations & Applications
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 |
Common Misconceptions
- "A skill replaces the human runbook it's based on" - a skill orchestrates how an agent should act, while the human cookbook page it references remains the authoritative explanation of why.
- "Skills and always-on rules are the same thing" - a rule is a constant constraint like "no production DDL in chat," while a skill is an invoked playbook with its own inputs and outputs; teams typically need both.
- "Once written, a skill stays correct" - a skill's stack pin and guardrails go stale the moment the underlying Postgres version, extension set, or incident history moves past what the file assumes.
- "An agent following a skill can be trusted to run production DDL unsupervised" - even a well-guardrailed skill's outputs are designed for human verification before execution, not autonomous action.
- "More skills always means more safety" - an overlapping or poorly scoped skill registry creates confusion about which playbook actually applies, which itself becomes a new failure mode.
FAQs
What exactly is an "agent skill" in the context of Postgres work?
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.
How is a skill different from just asking the agent a good prompt?
- A skill is written once and reused, while a prompt is written fresh each time.
- A skill's guardrails apply regardless of how the invoking prompt is phrased.
- A skill's outputs are structured for verification; an ad hoc answer usually is not.
Why does a skill need to pin the PostgreSQL version explicitly?
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.
What's the most important section of a skill file?
The guardrails section, since it encodes the specific actions a team has already learned - often through a postmortem - that an agent must never take.
Can skills call other skills?
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.
Does a skill ever replace the human cookbook pages on this site?
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.
What happens if two skills seem to apply to the same task?
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.
Should a skill ever let an agent run DDL against production automatically?
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.
How do teams decide when a new guardrail is needed?
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.
Where should SKILL.md files live in a repo?
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.
What's a "verifiable output" and why does it matter so much?
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.
Is this model specific to Postgres, or does it apply to any database?
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.
Related
- Agent Skills Basics - the ten concrete examples this page's model generalizes from.
- Migration Safety Skill - a full skill built on this contract shape.
- EXPLAIN Review Skill - the query-plan decision domain in practice.
- Failover Drill Skill - the HA decision domain in practice.
- Incident Triage Skill - the SEV1 decision domain in practice.
- Migrations Basics - the human cookbook a migration skill defers to.
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.