What Are Skills

The Gem Metaphor

Just as precious gems are formed by compressing raw materials under immense pressure over time, skills are formed by distilling years of domain expertise into concentrated, structured knowledge.

A skill is a reusable package of proven practices that AI agents can discover, load, and follow to perform specialized tasks with the depth and nuance of a human expert. Skills capture what actually works — the methodologies, protocols, and judgment honed through real-world experience.

The Agent Skills Standard

SkillGem builds on the Agent Skills open standard — a lightweight, portable format for extending AI agent capabilities.

Skills are supported by over 20 platforms including Claude Code, Cursor, Gemini CLI, VS Code, GitHub Copilot, Roo Code, and many more. Write once, deploy everywhere.

Skills vs Agents & MCP Tools

The AI ecosystem has three distinct layers. Skills are fundamentally different from agents and MCP tools — and understanding the difference is key to understanding why skills unlock a new economy.

Agents are the runtime — they reason, plan, and execute. MCP tools are the hands — they connect agents to databases, APIs, and external services. Skills are the brain — they encode proven practices that tell agents what to do and how to think about a domain.

This is what makes skills uniquely accessible and uniquely valuable. A medical specialist with no coding background can create a skill that guides any AI agent through a diagnostic protocol refined over years of practice. A veteran litigator can encode contract review methodology that works across Claude Code, Cursor, Gemini CLI, and every other platform that supports the standard. The expertise — the practices that actually work — is the product, not the infrastructure.

Skills as the Knowledge Layer for MCP Tools

MCP tools give agents capabilities. Skills teach agents how to use those capabilities well.

An agent with access to a dozen MCP tools — a database, a file system, a web browser, an API client — has raw power but no guidance. It's like handing someone a fully equipped workshop with no training. Skills bridge the gap: they analyze a set of MCP tools, understand what's possible through their compositions, and encode the effective usage patterns.

MCP Tools (capabilities)          Skills (usage patterns)
┌──────────────┐
│  database    │──┐
├──────────────┤  │    ┌────────────────────────────────┐
│  web-search  │──┼──▶ │  market-research               │
├──────────────┤  │    │  "Search → Analyze → Store →   │
│  spreadsheet │──┘    │   Summarize → Report"          │
└──────────────┘       └────────────────────────────────┘

┌──────────────┐
│  github      │──┐
├──────────────┤  │    ┌────────────────────────────────┐
│  terminal    │──┼──▶ │  code-review-workflow           │
├──────────────┤  │    │  "Fetch PR → Run tests → Check │
│  filesystem  │──┘    │   patterns → Draft review"     │
└──────────────┘       └────────────────────────────────┘

The process works like this:

1. Inventory — Examine the available MCP tools, their capabilities, inputs, and outputs
2. Map compositions — Identify which tools can chain together and what workflows emerge from their combinations
3. Capture patterns — Encode the effective sequences, error handling, and decision points as skills
4. Declare dependencies — The skill declares which MCP tools it requires, so agents know what's needed before activation

This turns a bag of tools into a playbook. A skill like data-pipeline-builder might compose a database tool, a file system tool, and a visualization tool into a proven workflow — when to query, how to transform, where to store intermediate results, and what to do when things fail. The individual tools don't change; the skill adds the expertise of someone who's built hundreds of pipelines.

Three Authorship Paths

Skills can be created through any combination of human and AI effort:

• Human-authored — A domain expert writes instructions directly, capturing proven practices, judgment, and methodology refined over years in structured Markdown.
• AI-generated — An agent synthesizes skills from documentation, research papers, or observed patterns. The Skill Builder uses this approach with human guidance to extract and codify what works.
• Composed — New skills are assembled from existing ones, combining proven practices from multiple domains into something greater than any single source.

Skills Are Everywhere

Proven practices already exist — scattered across blog posts, X threads, articles, conference talks, and code repositories. Skills give them a standard form that agents can actually use.

Any source of expertise can become a skill:

• An X post or thread — A practitioner shares a deployment checklist or debugging technique that went viral. That's a skill waiting to be packaged.
• A blog post or article — A deep-dive on database optimization or API design patterns. The Skill Builder can distill it into structured, agent-ready instructions.
• A research paper — A novel methodology, algorithm, or clinical protocol. The skill makes cutting-edge research immediately actionable by any agent.
• A conference talk — The key takeaways and methodologies from an expert presentation, codified for reuse.
• A GitHub repository — Every repo should have a skill, just as every repo has a README. The README tells humans how to use the project. A SKILL.md tells agents — how to contribute, how to debug, how the architecture works, what patterns to follow.

README.md  →  for humans   →  "Here's how to install and use this project"
SKILL.md   →  for agents   →  "Here's how to work with this codebase effectively"

The README explains what a project is. The skill encodes how to work with it — the conventions, the gotchas, the patterns that experienced contributors already know. An agent loading a repo's skill can immediately contribute at the level of a seasoned team member.

Anatomy of a Skill

At its core, a skill is a folder containing a SKILL.md file with metadata and instructions:

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

The SKILL.md file uses YAML frontmatter followed by Markdown content:

---
name: medical-triage
description: Guides initial patient assessment using evidence-based
  protocols. Use when triaging patients or evaluating symptoms.
---

# Medical Triage

## When to use this skill
Use this skill when assessing patient symptoms and determining
urgency levels...

## Assessment protocol
1. Check vital signs against baseline thresholds
2. Evaluate symptom severity using the ESI scale
3. ...

Required frontmatter fields:

Progressive Disclosure

Skills are designed for efficient context management. Agents don't load everything at once:

1. Discovery (~100 tokens) — Only the name and description are loaded at startup, just enough to know when the skill might be relevant.
2. Activation (<5,000 tokens) — When a task matches, the agent reads the full SKILL.md instructions into context.
3. Resources (as needed) — Scripts, references, and assets are loaded only when the instructions call for them.

Example Skills

Skills can capture expertise across any domain:

Skill Graphs & Bundles

A single skill captures one domain. A skill graph captures how domains connect — and that's where the real power lives.

A skill graph is a directed set of skills with declared dependencies and data flow between them. When an agent activates one skill in the graph, it can pull in related skills as needed, assembling a team of expertise for complex tasks.

                    ┌─────────────────┐
                    │  due-diligence   │  (bundle)
                    └────────┬────────┘
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
     ┌────────────┐  ┌────────────┐  ┌────────────┐
     │  financial  │  │   legal    │  │  technical │
     │  analysis   │  │  review    │  │  audit     │
     └──────┬─────┘  └─────┬──────┘  └──────┬─────┘
            ▼              ▼                ▼
     ┌────────────┐  ┌────────────┐  ┌────────────┐
     │  valuation  │  │  contract  │  │  security  │
     │  models     │  │  clauses   │  │  scanning  │
     └────────────┘  └────────────┘  └────────────┘

A skill bundle is a named, versioned package of a skill graph — a curated collection designed to work together for a specific use case. Bundles declare the entry skill, the dependency graph, and how data flows between skills.

---
name: due-diligence
type: bundle
description: Comprehensive startup due diligence combining
  financial, legal, and technical assessment.
skills:
  - financial-analysis@^2.0
  - legal-review@^1.5
  - technical-audit@^1.0
  - valuation-models@^3.0
  - contract-clauses@^1.2
  - security-scanning@^2.1
entry: financial-analysis
flow:
  financial-analysis: [valuation-models, legal-review]
  legal-review: [contract-clauses, technical-audit]
  technical-audit: [security-scanning]
---

Why Graphs Matter

• Collective expertise — No single expert covers every angle. Graphs combine specialists into a team that's greater than the sum of its parts.
• Composable by anyone — You don't need to author every skill in a bundle. Curate the best skills from different authors and compose them into a workflow.
• Revenue sharing — When a bundle is used, x402 payments are split across all contributing skill authors proportionally.
• Independent evolution — Each skill in the graph versions independently. Upgrade one component without touching the rest.
• Emergent capability — Skills in a graph share execution context. The output of one skill becomes the input of the next, creating capabilities none could achieve alone.

Bundles as Products

Skill bundles are themselves skills — they follow the same standard, use the same discovery and payment infrastructure, and build the same on-chain reputation. A bundle author who curates excellent combinations earns reputation and revenue just like an individual skill author.

This creates a new role in the agentic economy: the skill curator. Domain experts who understand how different areas of expertise connect can compose graphs that solve complex, multi-disciplinary problems — due diligence, clinical workflows, full-stack development, regulatory compliance — without writing a single skill from scratch.

Next Steps

Learn how to create your own skill with the AI-assisted Skill Builder, or explore how the Skill Gateway enables remote skill access.