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 expertise that AI agents can discover, load, and follow to perform specialized tasks with the depth and nuance of a human expert.

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.

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:

Field Required Description
name Yes Lowercase, hyphens only, max 64 characters. Must match folder name.
description Yes Max 1024 characters. What the skill does and when to use it.
license No License name or reference to bundled license file.
metadata No Arbitrary key-value pairs (author, version, etc.).

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:

medical-triage

Guides initial patient assessment using evidence-based protocols. Evaluates symptoms against the ESI scale and recommends urgency levels.

legal-contract-review

Reviews contracts for common pitfalls, missing clauses, and ambiguous language. Flags issues by severity with plain-English explanations.

data-analysis-pipeline

Structures exploratory data analysis with statistical rigor. Guides hypothesis formation, test selection, and result interpretation.

sourdough-baking

Expert bread-making from starter maintenance to final bake. Covers timing, temperature, hydration ratios, and troubleshooting.

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.