Agent Skills Best Practices

Rules that keep Postgres Agent Skills accurate, safe, and aligned with PostgreSQL 18.4 production policy.

How to Use This List

Stack pin block in every skill. PostgreSQL 18.4, psql client, Patroni/pgBackRest versions per ADR (Agent Skills Basics).
Mandatory sections: What, When, Inputs, Outputs, Guardrails, Stack pin, Example prompts.
One skill per decision domain. No mega-skill mixing incident + migration + backup.
Version skills when guardrails change. Semver in README or git tag on skill folder.
Link human authoritative docs. EXPLAIN and migrations cookbooks stay source of truth.

No prod DDL from agent without ticket. Human merges migration PR after staging proof.
No pg_terminate_backend without blocker evidence. Incident skill outputs PID; human executes.
No DROP SLOT / DROP DATABASE without named approver. Document in guardrails.
Staging default for EXPLAIN (ANALYZE). Prod EXPLAIN only with read-only incident policy.
Rollback SQL required in migration skill outputs. Forward-only teams still document manual down.
Postmortem bullets become guardrails within 5 days. SEV1 learning loop closes.

End every skill output with command block. psql, flyway migrate, patronictl list, exit codes.
Reject prose-only "done". Agent must show verification query results template.
Attach table scale queries for migration/explain skills. Row counts from pg_class.reltuples.
INCIDENT skill preserves log bundle commands. df, pg_locks, replication views in one script.
FAILOVER skill records RTO timestamps. Minutes from trigger to successful write.

Name skill explicitly in prompt. "Use Migration Safety Skill on V12__..."
Skill registry with owners. Platform DBA maintains docs/skills/README.md.
Quarterly skill review calendar. After Postgres 18.x minor release notes scan.
Never auto-merge agent PRs. Same review bar as human-authored SQL.
Log skill failures in #database. Improve inputs list when agents guess wrong.
Pair first-time skill users. Pairing on Query PRs for EXPLAIN skill.

Skills orchestrate; docs teach. Fundamentals pages are not replaced by skills.
Do not duplicate pganalyze. Advisor skepticism stays in essential tools docs.
Managed vs self-hosted branches. RDS failover steps differ from Patroni; document both or split skills.
Air-gapped sites omit SaaS steps. Skills work offline with open-source tooling only.

How many skills does a team need?

Minimum four: EXPLAIN review, migration safety, failover drill, incident triage. Add upgrade skill when multi-major jumps are frequent.

Skills in Cursor vs Claude Code vs Copilot?

Keep SKILL.md portable markdown in repo. Tool-specific paths symlink to same content. Stack pin is universal.

Should juniors invoke incident skill?

Yes with on-call buddy. Skill structures thinking; human executes destructive actions.

Stack versions: This page was written for PostgreSQL 18.4, Flyway 10+, Patroni 4.x, and pgBackRest 2.55+.