AGENTS.md · supabase/agent-skills

Sections

1. Prerequisites
2. Repository Structure
3. Commands
4. Releases
5. Creating a New Skill
6. Writing SKILL.md Files
7. Reference File Format
8. What NOT to Include

First lines (shown under the repo's MIT license)

# AGENTS.md

Guidance for AI coding agents working with this repository.

> **Note:** `CLAUDE.md` is a symlink to this file.

## Prerequisites

This project uses `pnpm` for dependency management and task execution. Use the
Node.js version declared in [`.node-version`](/Users/pedrorodrigues/supabase-agent-skills/.node-version),
then install dependencies with `pnpm install`.

## Repository Structure

```
skills/
  {skill-name}/
    SKILL.md
    references/ (optional)
```

## Commands

Run tasks with `pnpm`.

```bash
pnpm install                     # Install dependencies
pnpm test                        # Run tests
```

**Before completing any task**, run `pnpm test` to ensure CI passes.

## Releases

This repository uses Release Please on `main`.

- Merge conventional commits using `feat:` and `fix:` prefixes so Release Please can open or update the release PR.
- Release Please opens **one combined release PR** that bumps the root version and the version of any skill whose files were touched. Unrelated skills are not bumped. Do not bump skill versions manually.
- When the PR is merged, GitHub Actions creates one GitHub release (tag `v{version}`) with all skill tarballs and `index.json`. Per-skill packages use `skip-github-release: true` — no separate GitHub release is created for them, but their `metadata.version` in `SKILL.md` and their `CHANGELOG.md` are committed as part of the release PR.

If you change shipped skill contents under `skills/`, make sure the change is represented with an appropriate conventional commit so it is included in the next release.

## Creating a New Skill

Skills follow the [Agent Skills Open Standard](https://agentskills.io/).

1. Create directory: `mkdir -p skills/{skill-name}/references`
2. Create `SKILL.md` following the format below
3. Add `references/_sections.md` defining sections
4. Add reference files: `{prefix}-{reference-name}.md`
5. Register the skill in `release-please-config.json` as a new package and seed its version in `.release-please-manifest.json`:
   ```json
   // release-please-config.json — add under "packages":
   "skills/{skill-name}": {
     "release-type": "simple",
     "skip-github-release": true,
     "changelog-path": "skills/{skill-name}/CHANGELOG.md",
     "extra-files": [
       {
         "type": "generic",
         "path": "skills/{skill-name}/SKILL.md",
         "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""]
       }
     ]
   }
   ```
   ```json
   // .release-please-manifest.json — add:
   "skills/{skill-name}": "0.0.0"
   ```
6. Run `pnpm test`
7. Commit the new skill with a `feat:` prefix so Release Please bumps it from `0.0.0` to `0.1.0` on first release. Using `fix:` would produce `0.0.1` instead.

---

## Writing SKILL.md Files

SKILL.md is the core of every skill. It consists of **YAML frontmatter**
followed by **Markdown instructions**.

### Frontmatter (Required)

```yaml
---
name: skill-name
description: What this skill does and when to use it.
metadata:
  author: supabase
  version: "0.0.0"
---
```

| Field         | Required | Constraints                                                                     |
| ------------- | -------- | ------------------------------------------------------------------------------- |
| `name`        | Yes      | 1-64 chars. Lowercase alphanumeric and hyphens only. Must match directory name. |
| `description` | Yes      | 1-1024 chars. Describe what the skill does AND when to use it.                  |
| `license`     | No       | License name or reference to bundled license file.                              |
| `metadata`    | No       | Arbitrary key-value pairs. Always include `version: "0.0.0"` — Release Please bumps it on first release. |

### Name Field Rules

- Lowercase letters, numbers, and hyphens only (`a-z`, `0-9`, `-`)
- Must not start or end with `-`
- Must not contain consecutive hyphens (`--`)
- Must match the parent directory name

```yaml
# Valid
name: pdf-processing
name: data-analysis

# Invalid
name: PDF-Processing # uppercase not allowed
name: -pdf # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed
```

### Description Field (Critical)

The description is the **primary trigger mechanism**. Claude uses it to decide
when to activate the skill.

**Include both:**

1. What the skill does
2. Specific triggers/contexts for when to use it

```yaml
# Good - comprehensive and trigger-rich
description: >
  Supabase database best practices for schema design, RLS policies,
  indexing, and query optimization. Use when working with Supabase
  projects, writing PostgreSQL migrations, configuring Row Level Security,
  or optimizing database performance.

# Bad - too vague
description: Helps with databases.
```

**Do not put "when to use" in the body.** The body loads only after triggering,
so trigger context must be in the description.

### Body Content

The Markdown body contains instructions for using the skill. Write
concisely—Claude is already capable. Only add context Claude doesn't already
have.

**Guidelines:**

- Use imperative form ("Create the table", not "You should create the table")
- Keep under 500 lines; move detailed content to `references/`
- Prefer concise examples over verbose explanations
- Challenge each paragraph: "Does this justify its token cost?"

**Recommended structure:**

1. Quick start or core workflow
2. Key patterns with examples
3. Links to reference files for advanced topics