postgres-skills: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.

For the complete Agent Skills specification, see: https://agentskills.io/specification

Repository Overview

A collection of skills for coding agents for working with Postgres. Skills are packaged instructions and documentation that extend the agent's capabilities.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    references/           # Optional: additional documentation
      REFERENCE.md        # Detailed technical reference
      {topic}.md          # Domain-specific files
    scripts/              # Optional: executable scripts
      {script-name}.sh    # Bash scripts (preferred)
    assets/               # Optional: static resources
      templates/          # Document/config templates
      images/             # Diagrams, examples

Naming Conventions

• Skill directory: kebab-case, must match name in frontmatter (e.g., postgres-best-practices)
• Name field: 1-64 chars, lowercase alphanumeric and hyphens only, no consecutive hyphens (--), must not start/end with -
• SKILL.md: Always uppercase, always this exact filename
• Scripts: kebab-case.sh (e.g., deploy.sh, fetch-logs.sh)

SKILL.md Format

The SKILL.md file must contain YAML frontmatter followed by Markdown content.

Frontmatter (required fields)

---
name: skill-name
description: A description of what this skill does and when to use it. Include trigger phrases. Max 1024 characters.
---

Frontmatter (optional fields)

---
name: skill-name
description: A description of what this skill does and when to use it.
license: Apache-2.0
compatibility: Requires git, docker, and network access
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Read
---