Documentation

Everything About Skills

Skills are reusable knowledge packages that teach AI agents how to think, work, and build. Learn how to discover, install, and create Skills for any workflow.

Explore Skills Create a Skill

01 · Overview

What are Skills?

Skills are reusable knowledge packages that teach AI agents how to think, build, and operate within specific domains.

Think of a Skill as a portable brain module. Instead of repeating the same instructions every time you talk to an AI, you package your expertise into a SKILL.md file that the agent loads automatically when relevant.

Skills are lazy-loaded — the AI only pulls in what it needs, keeping token usage low while maintaining deep expertise. They work across Claude Code, Codex CLI, ChatGPT, and any agent that can read markdown context.

The Flow

How a Skill activates

01 · Input

User Request

"Help me optimize this React component"

02 · Routing

AI Agent

Analyzes intent, scans available Skills, finds match

03 · Activation

Loads Relevant Skill

react-optimization.md — lazy-loaded into context

04 · Context

Knowledge Injected

Patterns, rules, examples, decision rubrics applied

05 · Expertise

Agent Becomes Specialized

Now reasons like a senior React performance engineer

06 · Output

Expert Output

Production-grade, consistent, repeatable result

Real examples

Frontend Design Skill

Teaches component architecture, accessibility patterns, and responsive design.

Brand Guideline Skill

Enforces brand voice, color systems, and typography rules across all outputs.

YouTube Transcript Skill

Structures video content extraction, timestamps, and summary generation.

React Optimization Skill

Guides memoization, re-render prevention, and bundle optimization.

02 · Why Skills

Core Advantages

Why Skills are the best way to scale AI expertise across your team.

Token Efficiency

Lazy-loaded on demand. The AI only loads what it needs — context stays lean, costs stay low.

Reusability

Write once, use everywhere. A single Skill works across projects, teams, and platforms.

Domain Expertise

Encode deep knowledge — frameworks, patterns, company standards — into actionable packages.

Consistency

Every team member gets the same expert guidance. No drift between how people use AI.

Cross-Platform

Works with Claude Code, Codex CLI, ChatGPT, and any agent that reads markdown context.

Easy Sharing

Share via Git repos, npm packages, or direct transfer. Install in seconds.

03 · Compare

Skills vs MCP

Two complementary systems that solve fundamentally different problems.

RECIPE

KITCHEN

“Skills are the recipe. MCP is the kitchen.”

They work together, not against each other.

Skills

Knowledge layer

Teaches the AI how to think and what patterns to follow.

Markdown-based

Plain SKILL.md files — no build step, no dependencies.

Zero infrastructure

Drop a folder and it works. No servers, no config.

Teaches workflows

Encodes best practices, standards, and decision-making.

MCP

Execution layer

Connects the AI to external tools, APIs, and databases.

JSON-RPC servers

Structured protocol with request/response patterns.

Requires infrastructure

Needs servers to be running and configured.

Handles integrations

Reads databases, calls APIs, executes commands.

Use Skills when…

Teaching AI your coding standards

Encoding design system rules

Standardizing review workflows

Sharing domain expertise across the team

Use MCP when…

Connecting to databases or APIs

Running external tools and services

Querying live data sources

Executing system-level commands

04 · Compare

Skills vs Prompts

From one-time instructions to persistent, structured intelligence.

Skills

Permanent & reusable

Persist across sessions — never retyped.

Structured

Metadata, organization, and clear conventions.

Auto-loaded

Pulled in automatically when relevant.

Shareable

Via Git, installable in seconds, version-controlled.

Prompts

One-time

Disappears after the conversation ends.

Freeform

No structure, no conventions.

Manual

Copy-pasted by hand every single time.

Fragile

Shared as raw text, lost after the session.

05 · Compare

Skills vs Projects

Skills

Portable knowledge

Reusable workflows and expertise that transfer across projects.

Not project-bound

“React Optimization” works in any React codebase.

Projects

Persistent context

Tied to one workspace — codebase, env, history.

Workspace-specific

Everything specific to that particular project.

06 · Compare

Skills vs Subagents

Skills

The what & how

Knowledge and capabilities any agent can use.

Shapes behavior

Structured reference material that guides reasoning.

Subagents

The who

Specialized workers that execute tasks autonomously.

Consume Skills

They load Skills to do their work better and consistently.

07 · Decision

When to Use Skills

A quick guide on when Skills shine — and when simpler approaches work fine.

Use Skills when

Repetitive workflows that need consistency

Company coding standards and conventions

Reusable expertise across multiple projects

Team-wide consistency in AI-assisted work

Complex multi-step processes

Domain knowledge that shouldn't be lost

Skip Skills when

One-time, simple tasks

Quick experimentation or prototyping

Basic prompts already give good results

The task is different every time

You're the only user and won't reuse it

08 · Anatomy

Skill Structure

Every Skill follows a clean, predictable folder layout.

Layout

react-optimization/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── examples.md
├── assets/
│   └── diagram.svg
└── scripts/
    └── analyze.sh

SKILL.md

The core file. All knowledge, instructions, and metadata the AI needs. The only required file.

references/

Docs, code examples, API references the Skill pulls from when needed.

assets/

Diagrams, screenshots, architecture images that provide context.

scripts/

Optional automation — linting, analysis, or code generation.

09 · Mechanics

How Skills Work

A four-step process that happens automatically behind the scenes.

Scan

On startup, the AI scans your skills directory and indexes all available Skills by their metadata and descriptions.

Match

When you make a request, the AI matches your task to the most relevant Skill based on context, keywords, and intent.

Load

Only the matched Skill's context is lazy-loaded into the conversation. No wasted tokens on irrelevant Skills.

Execute

The AI applies the Skill's knowledge — patterns, rules, examples — to produce expert-level output.

10 · Setup

Installation

Get started with Skills in your preferred AI tool.

bash

# Clone a skill into your skills directory
git clone https://github.com/user/skill-name \
  ~/.claude/skills/skill-name

# Or create one from scratch
mkdir -p ~/.claude/skills/my-skill
touch ~/.claude/skills/my-skill/SKILL.md

Skills path: ~/.claude/skills/

11 · Build

Creating a Skill

Build your first Skill in five steps.

Create a folder

Name it descriptively using kebab-case. This becomes the Skill's identifier.

Write your SKILL.md

Add metadata (name, version, tags), instructions, rules, and examples.

Add supporting files

Reference docs in references/, images in assets/, scripts in scripts/.

Test your Skill

Use it in a real conversation and iterate on output quality.

Share it

Push to GitHub, publish on theskillcity, or share the folder.

Example SKILL.md

markdown

---
name: react-optimization
version: 1.0.0
description: React performance optimization patterns
author: your-name
tags: [react, performance, optimization]
---

# React Optimization Skill

## Objective
Guide the AI to apply React performance best
practices including memoization, code-splitting,
and render optimization.

## Rules
1. Check for unnecessary re-renders first
2. Use React.memo for pure display components
3. Prefer useMemo/useCallback for expensive work
4. Implement code-splitting at route boundaries

## Examples

### Before
const List = ({ items, filter }) => {
  const f = items.filter(filter);
  return f.map(i => <Item key={i.id} {...i} />);
};

### After
const List = memo(({ items, filter }) => {
  const f = useMemo(
    () => items.filter(filter), [items, filter]
  );
  return f.map(i => <Item key={i.id} {...i} />);
});

12 · Wisdom

Best Practices

Guidelines for building effective, maintainable Skills.

Keep Skills focused

One Skill, one domain. A focused Skill is more accurate and reliable than a broad one.

Write clear descriptions

Help the AI understand when and how to apply it — the difference between used and ignored.

Include before/after examples

Examples dramatically improve output. Show what bad looks like and what good looks like.

Organize references logically

Clear filenames and headers. The AI navigates these files — make it easy.

Avoid overly broad Skills

A "do everything" Skill dilutes quality. Split into focused, composable Skills.

Version and iterate

Track changes with Git. Continuously refine based on real usage and feedback.

Discover the toolingbehind modern intelligence

The operating system for AI infrastructure discovery. Search a live map of MCP servers, AI agents, LLM tools, automation systems, and developer infrastructure.

react-optimization/ ├── SKILL.md ├── references/ │ ├── patterns.md │ └── examples.md ├── assets/ │ └── diagram.svg └── scripts/ └── analyze.sh

# Clone a skill into your skills directory git clone https://github.com/user/skill-name \ ~/.claude/skills/skill-name # Or create one from scratch mkdir -p ~/.claude/skills/my-skill touch ~/.claude/skills/my-skill/SKILL.md

--- name: react-optimization version: 1.0.0 description: React performance optimization patterns author: your-name tags: [react, performance, optimization] --- # React Optimization Skill ## Objective Guide the AI to apply React performance best practices including memoization, code-splitting, and render optimization. ## Rules 1. Check for unnecessary re-renders first 2. Use React.memo for pure display components 3. Prefer useMemo/useCallback for expensive work 4. Implement code-splitting at route boundaries ## Examples ### Before const List = ({ items, filter }) => { const f = items.filter(filter); return f.map(i => <Item key={i.id} {...i} />); }; ### After const List = memo(({ items, filter }) => { const f = useMemo( () => items.filter(filter), [items, filter] ); return f.map(i => <Item key={i.id} {...i} />); });