Authoring a skill
How to write Agent Skills that agents can actually discover and use.
A skill is a self-contained unit of agent know-how: a SKILL.md file plus any supporting files it references. ContextPie stores each skill, embeds it for discovery, and serves it over your hosted MCP endpoint so agents can pull it at runtime. This guide covers what makes a skill discoverable and well-scoped.
Anatomy of a skill
Every skill is one SKILL.md (the instructions an agent loads) and zero or more supporting files. ContextPie classifies supporting files by kind:
| Kind | Purpose | Example |
|---|---|---|
instructions | Extra prose the agent loads on demand | escalation-policy.md |
doc | Reference material | api-reference.md |
script | Runnable helper | migrate.py |
template | Boilerplate to copy | pr-description.md |
The agent fetches these one at a time, only when SKILL.md tells it to. See Progressive disclosure.
Description and trigger phrases dominate discovery
Discovery is semantic. ContextPie embeds only the skill's name + description + trigger_phrases (OpenAI text-embedding-3-small, 1536-dim) and matches an agent's query by cosine similarity. File bodies are never embedded. That means your description and trigger phrases are the entire surface an agent searches against — get them right or the skill stays invisible.
Writing a distinct, well-scoped description
Write one sentence that states what the skill does and when to reach for it. Make it distinct from your other skills so they don't compete for the same queries.
Weak: "Helps with database stuff." Strong: "Run zero-downtime Postgres schema migrations using our expand/contract workflow."
Good vs weak trigger phrases
Trigger phrases are the real-world ways an agent might ask for this skill. Cover synonyms and intents, not keywords.
Good:
- "add a column without downtime"
- "safely alter a production table"
- "expand contract migration"
Weak:
- "migration" # too broad, collides with everything
- "database" # not an intent
- "do the thing" # meaningless
Let Draft with AI do the first pass
You don't have to start from a blank file. Draft with AI generates a first-pass SKILL.md, description, and trigger phrases from a short prompt — then you refine. Once saved, the skill is embedded and live. Next: Connecting an agent.