Supabase Agent Skills — Symlinked Config + Task Runner

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, then install dependencies with pnpm install.

Repository Structure

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

Commands

Run tasks with pnpm.

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.

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:

   // 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]+)\""]
       }
     ]
   }

   // .release-please-manifest.json — add:
   "skills/{skill-name}": "0.0.0"

1. Run pnpm test
2. 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)

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

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

# 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

# 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.