A skill is one Markdown file with a YAML header. The header tells the directory what the skill is.
Everything below the header is the instruction the agent follows. That is the whole format, and it is
what all 803 published skills use.
This imports cleanly. Copy it, change the values, and you have a valid skill.
---
name: PostgreSQL Query Reviewer
description: Reviews PostgreSQL queries for missing indexes, sequential scans,
and N+1 patterns, then rewrites them with an explanation of each change.
version: 1.0.0
executionType: prompt-only
category: database
license: MIT
tags:
- postgresql
- performance
- sql
permissions:
- read:filesystem
---
# PostgreSQL Query Reviewer
## What this does
Reads a SQL query and reports the specific reasons it is slow, then gives a
rewritten version.
## When to use it
Use it when a query is slow and you have the EXPLAIN output, or when you want a
second opinion before shipping a migration.
## Steps
1. Ask the user for the query and, if they have it, the EXPLAIN ANALYZE output.
2. Identify sequential scans on tables over 10,000 rows.
3. Identify missing indexes on JOIN and WHERE columns.
4. Identify N+1 patterns where a query runs inside a loop.
5. Return a rewritten query and a numbered list of what changed and why.
## Output
A rewritten query in a SQL code block, followed by a numbered list of changes.
Never return a rewritten query without the explanation.
## Limits
Covers PostgreSQL 12 and later. Does not cover partitioned table planning or
foreign data wrappers.
Frontmatter fields
The header sits between two --- lines at the very top of the file. Only
name and description are required. Everything else improves how the
skill is found and how much people trust it.
SKILL.md frontmatter fields
Field
Type
Required
Notes
name
string
Required
The display name. Keep it under 60 characters so it does not wrap on a card.
name: PostgreSQL Query Reviewer
description
string
Required
One or two sentences saying what the skill does. This becomes the meta description on the listing page, so write it for a person, not for a keyword.
description: Reviews PostgreSQL queries for missing indexes, sequential scans, and N+1 patterns, then rewrites them.
version
string
Optional
Semantic version. Bump it when the behaviour changes so people know a re-download is worth it.
version: 1.2.0
tags
list
Optional
A YAML list. Up to 10 tags. Each tag becomes a browsable page, so use words people search for rather than internal shorthand.
tags:
- postgresql
- performance
- sql
executionType
enum
Optional
How the skill runs. One of the six values below. If you leave it out, the importer infers it from what the repository contains.
executionType: script-assisted
category
string
Optional
One category slug. Anything unrecognised is mapped to the closest existing category rather than rejected.
category: database
runtimes
list
Optional
Which agents the skill was tested against. Leave it out if the skill is plain instructions that work anywhere.
runtimes:
- claude
- cursor
permissions
list
Optional
What the skill needs access to. Declare this honestly. It is shown on the listing page and it is the first thing the trust review checks.
permissions:
- read:filesystem
- network:outbound
dependencies
list
Optional
Tools or packages that must already be installed. Name the command, not the package manager.
dependencies:
- psql
- python3
license
string
Optional
SPDX identifier. Without one, people cannot tell whether they are allowed to use the skill at work.
license: MIT
author
string
Optional
Your name or handle. Defaults to the GitHub owner of the repository.
author: jane-dev
Write tags as a real YAML list, one item per line under the key. A single line
such as tags: a, b, c is accepted, but it is stored as one string and each tag
then has to be split apart later, which is worth avoiding.
Execution types
The execution type tells someone what installing your skill will cost them before they read a
line of it. Pick the one that matches what the repository actually contains.
prompt-only
The whole skill is instructions. Paste it in and the agent follows it. Nothing to install.
Two older values still appear in imported data and are mapped automatically:
scripted becomes script-assisted, and mcp-server becomes
mcp-backed. Use the canonical values in new files.
Writing the instructions
Everything below the closing --- is what the agent reads. Write it as instructions
to a capable colleague who has not seen your codebase.
Say what it does in one sentence first. An agent that has to infer the goal from the steps will drift from it.
Say when to use it and when not to. Scope is what stops a skill being applied to the wrong problem.
Number the steps. Ordered steps get followed in order. A prose paragraph gets summarised.
Describe the output exactly. Name the format, the sections, and anything that must never be omitted.
State the limits. Versions covered, cases not covered, assumptions made. This is what stops a confident wrong answer.
Never put credentials, tokens, internal hostnames, or private URLs in a SKILL.md file.
Everything you publish is public and gets copied onto other people's machines. Use a
placeholder and document which environment variable holds the real value.
Repository layout
Both of these import correctly.
One skill per repository
my-skill/
SKILL.md the skill, required
README.md optional, for people browsing GitHub
LICENSE strongly recommended
scripts/ only for script-assisted skills
review.py
templates/ only for template-pack skills
report.md
Each folder containing a SKILL.md becomes its own listing, with its own page and its own slug.
Submit the repository once and every skill inside it is picked up.
What the importer checks
These run automatically when you submit. Nothing here needs a human first.
Import validation rules
Check
Rule
If it fails
Repository reachable
The URL must be a public GitHub repository.
The submission is rejected immediately with the reason shown on screen.
SKILL.md present
At least one SKILL.md at the root or in a subfolder.
Rejected. Nothing is created.
Frontmatter parses
Opens and closes with --- and contains valid key and value pairs.
Rejected, with the line number that failed.
name and description
Both present and not empty.
Rejected.
Tag count
At most 10 tags.
Extra tags are dropped. The skill still imports.
Slug uniqueness
The slug comes from the name and must not already exist.
A suffix is added automatically. The skill still imports.
Category and runtime values
Unknown values are mapped to the closest known slug.
Nothing fails. The mapped value is shown on the listing.
Human review
Permissions, scripts, and outbound network calls are read by a person.
Sent back with specific notes, not a generic rejection.
Common mistakes
The frontmatter does not parse
The opening --- must be the first line of the file, with nothing above
it, not even a blank line or a byte order mark. Save as UTF-8 without BOM.
Tags arrive as one long string
That happens when tags are written on a single line. Use a YAML list with two space
indentation and a dash per item. Each tag then gets its own browsable page.
The description is a keyword list
The description becomes the meta description on your listing page. A keyword list
reads badly in a search result and gets rewritten by Google anyway. One or two plain
sentences about what the skill does will do more for you.
Permissions are missing
This is the most common reason a submission is sent back. If the skill reads files,
runs commands, or makes network calls, declare it. Declaring access is not a
weakness in a listing. Undeclared access found during review is.
No licence file
Without a licence, nobody can use your skill at work, because their legal team has
no basis to approve it. Add a LICENSE file and set the license field.
MIT and Apache-2.0 are the two most used here.
Ready to publish?
Paste your repository URL. The importer reads the SKILL.md, builds the listing, and shows you exactly what
it found before anything goes live.
