Step 1

What a skill actually is

A Markdown file with two required lines of front matter and a body.

A skill is a Markdown file. The front matter carries a name and a description — nearly every shipped skill has both, and nothing else is required. Everything after it is prose the agent reads when the skill is selected.

Front matter	Used by	What it does
name	Nearly all	The id. Matches the folder, and is what an agent's skill list refers to.
description	Nearly all	One or two sentences saying what the skill does and when to reach for it. This is the line the agent reads when deciding whether to load it.
allowed-tools	A few	The tools this skill may call, named exactly. Only needed when a skill drives a specific tool — a research skill that only reasons declares nothing.
metadata, license, compatibility	A few	Housekeeping. None of it changes how the skill behaves.

Checked against the product on October 15, 2026

Step 2

Start from the 300-plus that already exist

Most agents are assembled, not authored.

Step 2 of the agent builder, SKILLS & TOOLS, opens on the catalogue: more than 300 skills, filtered ALL, RESEARCH, OTHER, BUSINESS, PERSON and UI, each with a count. CREATE CUSTOM SKILL sits at the top, and the header counts what you have selected.

The agents Grep ships are built this way. Know Your Business runs on six catalogue skills — business-sanctions-screening, business-adverse-media-screening, high-risk-country-screening, high-risk-industry-screening, us-business-verification-middesk and ati-tools-reference. None of them was written for that agent alone.

Checked against the product on October 15, 2026

Step 3

The description is the trigger

It is not a summary. It is how the agent decides to load the skill at all.

An agent reads descriptions to choose. A description that says only what the skill is about gives it nothing to match on; the ones in the catalogue that work name the job and the trigger together.

“Screen businesses against sanctions lists and watchlists using ComplyAdvantage with detailed sanctions analysis and jurisdiction assessment.” — names the action, the subject and the tool.
“Classifies businesses into Merchant Category Codes (MCC) based on their activities, products, and services. Use when user asks about MCC codes, business classification…” — states outright when to reach for it.
“Use when calling particle:* sponsor/advertising tools, when the user asks about podcast sponsors… For podcast content search and transcripts see particle-podcasts-api instead.” — says when NOT to load it, which is how two overlapping skills stay apart.

Checked against the product on October 21, 2026

Step 4

What a real skill looks like inside

Measured across every shipped skill, not prescribed.

There is no required structure, but the catalogue has settled into one. Counting headings across every shipped skill, the most common are Overview, Best Practices, References, Error Handling or Troubleshooting, and Workflows; Common Patterns, Core Capabilities and When to Use follow.

Length	Skills	What that size usually is
Under 230 lines	a quarter of them	One tool, one procedure. An API reference or a single check.
Around 680 lines	the median	A workflow with decision points, examples and failure handling.
Over 1,700 lines	a quarter of them	A domain methodology — how a practitioner works, not how one tool works.

Checked against the product on October 15, 2026

Step 5

Declare the tools, and only the ones you use

A declaration is a grant. What is not declared is not reachable.

Only a few of the shipped skills declare allowed-tools. The EIN document check declares two — Bash and mcp__parcha_custom_tools__visual_document_verification — and gets exactly those.

This is not documentation. Grants are per declaration: an agent reaches the tools its skills and config asked for, and nothing else. Declaring a tool you do not use widens what the agent will try; leaving out one you do use means the skill fails mid-run.

Checked against the product on October 15, 2026

Step 6

The part nothing can check for you

Four questions the product cannot answer. They are judgement, and they are marked as judgement.

Everything above can be pointed at a file or a screen. What follows cannot: it is how the people who wrote the good skills in this catalogue seem to work, and you should treat it as argument rather than fact.

One job per skill. The catalogue splits by task — sanctions screening, adverse media, country risk — rather than by domain, and an agent picks three of them.
Say what to do when the evidence is thin. The skills that hold up name the failure cases; the ones that read well and behave badly assume the happy path.
Order of operations beats the final answer. A skill that says which source to trust first is reusable; one that only describes a good conclusion is not.
Show one worked example. Every long skill in the catalogue has one, and it is the part an agent imitates most directly.