SKILL.md Specification

SKILL.md is the core file of every skill. It's a markdown file with YAML frontmatter that AI agents read to learn domain-specific knowledge and instructions.

File format

---
name: skill-name
description: What this skill does
license: MIT
compatibility: Any requirements
metadata:
  author: github-username
  version: "1.0.0"
allowed-tools:
  - tool-name
---

# Skill Title

Markdown content that the AI agent reads...

Frontmatter fields

name (required)

name: my-database-tool

The skill's identifier. Rules:

Lowercase letters, numbers, and hyphens only
Must start with a letter or number
Maximum 64 characters
Must match the regex: ^[a-z0-9][a-z0-9-]*$

This is the bare name — scoping (@org/) is handled at publish time.

description (required)

description: Best practices and MCP tools for working with PostgreSQL

Key	Description
`author`	GitHub username of the author
`version`	Skill version (informational; the authoritative version is in `shipables.json`)

---
name: postgres
description: PostgreSQL best practices, query patterns, and MCP tools
license: MIT
compatibility: Requires network access for MCP server
metadata:
  author: janesmith
  version: "1.3.0"
---

# PostgreSQL

## When to use this skill

Use this skill when working with PostgreSQL databases including:
- Writing and optimizing SQL queries
- Designing schemas and migrations
- Managing connections and transactions

## Query patterns

### Use parameterized queries

Always use parameterized queries to prevent SQL injection:

\`\`\`sql
-- Good
SELECT * FROM users WHERE id = $1;

-- Bad - SQL injection risk
SELECT * FROM users WHERE id = ' + userId + ';
\`\`\`

### Prefer specific columns

Avoid SELECT *. List the columns you need:

\`\`\`sql
SELECT id, name, email FROM users WHERE active = true;
\`\`\`

## Migrations

Run migrations sequentially. Never modify an applied migration.
Create a new migration file for each schema change.

## Common mistakes

- Forgetting to add indexes on foreign keys
- Using TEXT instead of VARCHAR with length constraints
- Not closing database connections in error paths

SKILL.md Specification

File format

Frontmatter fields

name (required)

description (required)

license

compatibility

metadata

allowed-tools

Body content

Best practices

Supported markdown features

Parsing

Example