skills/supabase-postgres-best-practices
1
0
Fork 0
mirror of https://github.com/supabase/agent-skills.git synced 2026-03-27 10:09:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix: add how to write a skill to agent.md (#16)

Browse Source
This commit is contained in:
Pedro Rodrigues
2026-01-27 17:07:36 +00:00
committed by GitHub
parent 7aa8ecc25f
commit e5417d1a90
1 changed files with 129 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
AGENTS.md
View File

@@ -29,43 +29,142 @@ npm run validate -- {skill-name} # Validate specific skill
npm run check # Format and lint (auto-fix)
```
**Before completing any task**, run `npm run check` and `npm run build` to ensure CI passes.
**Before completing any task**, run `npm run check` and `npm run build` to
ensure CI passes.
## 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` with required frontmatter:
```yaml
---
name: skill-name
description: What this skill does and when to use it.
license: MIT
metadata:
author: your-org
version: "1.0.0"
---
```
2. Create `SKILL.md` following the format below
3. Add `references/_sections.md` defining sections
4. Add reference files: `{prefix}-{reference-name}.md`
5. Run `npm run build`
## SKILL.md Format (Agent Skills Spec)
---
## 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 # Required: must match directory name
description: Description of skill. # Required: what it does and when to use
license: MIT # Optional: license
metadata: # Optional: arbitrary key-value pairs
author: your-org
version: "1.0.0"
name: skill-name
description: What this skill does and when to use it.
---
```
| 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 (e.g., `author`, `version`). |
### 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
```markdown
## Quick Start
Create a table with RLS:
[concise code example]
## Common Patterns
### Authentication
[pattern with example]
## Advanced Topics
- **Complex policies**: See
[references/rls-patterns.md](references/rls-patterns.md)
- **Performance tuning**: See
[references/optimization.md](references/optimization.md)
```
### Progressive Disclosure
Skills use three loading levels:
1. **Metadata** (~100 tokens) - Always loaded for all skills
2. **Body** (<5k tokens recommended) - Loaded when skill triggers
3. **References** (as needed) - Loaded on demand by Claude
Keep SKILL.md lean. Move detailed reference material to separate files and link
to them.
---
## Reference File Format
Reference files in `references/` extend skills with detailed documentation.
```markdown
---
title: Action-Oriented Title
@@ -78,24 +177,18 @@ tags: keywords
1-2 sentence explanation.
**Incorrect:**
\`\`\`sql
-- bad example
\`\`\`
**Incorrect:** \`\`\`sql -- bad example \`\`\`
**Correct:**
\`\`\`sql
-- good example
\`\`\`
**Correct:** \`\`\`sql -- good example \`\`\`
```
## Impact Levels
## What NOT to Include
| Level | Improvement | Use For |
| ----------- | ----------------------------- | ---------------------------------------------------------- |
| CRITICAL | 10-100x or prevents failure | Security vulnerabilities, data loss, breaking changes |
| HIGH | 5-20x or major quality gain | Architecture decisions, core functionality, scalability |
| MEDIUM-HIGH | 2-5x or significant benefit | Design patterns, common anti-patterns, reliability |
| MEDIUM | 1.5-3x or noticeable gain | Optimization, best practices, maintainability |
| LOW-MEDIUM | 1.2-2x or minor benefit | Configuration, tooling, code organization |
| LOW | Incremental or edge cases | Advanced techniques, rare scenarios, polish |
Skills should only contain essential files. Do NOT create:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
The skill should contain only what an AI agent needs to do the job.