Understanding Skills
Skills are markdown files (SKILL.md) that teach your AI assistant domain knowledge about a set of tools — workflow patterns, data model concepts, and API gotchas that aren't captured in tool descriptions.
What is a Skill?
A SKILL.md file is a document that gives your AI assistant contextual expertise for a specific domain.
Tools tell your AI what it can do. Skills tell it how to do it well.
For example, PostHog has 40+ tools for analytics, experiments, and feature flags. The tool descriptions explain parameters, but they don't tell your AI that:
$pathnamegives cleaner results than$current_urlfor URL breakdowns- Experiment results come from a separate endpoint, not the experiment object
- Session recording snapshots require a two-step blob key fetch
- You should always test a query with
posthog_run_querybefore saving it as an insight
A SKILL.md file captures this kind of knowledge so your AI doesn't have to learn it through trial and error.
Skills vs Tool Descriptions
| Tool Descriptions | Skills | |
|---|---|---|
| Scope | Single tool | Entire domain / MCP server |
| Content | Parameters, types, required fields | Workflows, gotchas, data model relationships |
| Updated | Automatically via MCP | Manually authored domain knowledge |
| Example | "event: string (required)" | "Always discover event definitions before writing queries" |
How Skills Work
Skills follow the open SKILL.md standard — a simple format with YAML frontmatter and markdown body:
---
name: posthog
description: Domain knowledge for PostHog product analytics tools
---
# PostHog
PostHog organizes everything under Organizations → Projects...
## Data Model
- **Events** are the atomic unit...
## Workflows
- **Ad-hoc analysis**: List event definitions → run query → save as insight...
## Gotchas
- **`$pathname` vs `$current_url`**: Use `$pathname` for cleaner breakdowns...
When your AI assistant loads the skill, it gains this knowledge before making any tool calls.
Skills + MCP servers
Skills and MCP servers are designed to work together:
- The MCP server provides authenticated tool access — your AI can call PostHog APIs, create HubSpot contacts, or query your database
- The skill provides domain expertise — your AI knows the right patterns, avoids common mistakes, and follows optimal workflows
You can use skills without MCP servers (just domain knowledge), and MCP servers without skills (tools with trial-and-error learning). But together, your AI assistant becomes genuinely competent at the task.
Where Skills Live
Every MCPBundles MCP server can have an associated skill. Skills are:
- Browsable at mcpbundles.com/skills
- Downloadable as SKILL.md files from any MCP server or skill page
- Available via MCP — call the
get_skilltool on/bundle/{slug}endpoints that have a skill configured (no parameters needed; the MCP server is auto-detected). On the hub, passbundle_slug.
Composed MCP server skills
When you create a custom server by composing multiple MCP servers (e.g., PostHog + HubSpot), the get_skill tool automatically merges skills from all constituent MCP servers into a single document. Your AI gets domain knowledge for every service in the composition.