Skills are reusable instruction sets — packaged as markdown files — that extend what AI coding agents can do. Think of them as plugins for your AI assistant: install a skill, and your agent automatically gains new capabilities like code review checklists, deploy workflows, SEO audits, or framework-specific coding conventions.

Unlike one-off prompts that you type and forget, skills persist across sessions and activate automatically when relevant. They work across Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI, Cline, Factory, Amp, and any tool that supports the Agent Skills open standard.

This guide walks you through discovering, installing, and using your first skill in under 10 minutes.

Why Use Skills?

Most developers interact with AI assistants using ad-hoc prompts — typing instructions from scratch every time. Skills solve three problems with that approach:

Consistency. A skill encodes best practices once. Every team member gets the same code review checklist, the same deploy workflow, the same security audit — without remembering to ask for it.
Reusable expertise. Install a skill someone else built (or that you built for a past project) and immediately benefit from their domain knowledge. The Machina directory has over 22,000 published skills across marketing, security, DevOps, frontend, backend, and more.
Context efficiency. Skills use progressive disclosure — your AI agent reads only a short description at startup (~80 tokens), loads the full instructions only when relevant (~2,000 tokens), and pulls in supporting files only during execution. This keeps your context window clean.

How Skills Work

Every skill lives in its own directory and contains at minimum a SKILL.md file:

my-skill/
├── SKILL.md           # Main instructions (required)
├── references/        # Supporting docs the skill can pull in
│   └── checklist.md
└── templates/         # Templates the skill can use
    └── output.md

The SKILL.md file has two parts — YAML frontmatter and a markdown body:

---
name: code-review
description: Reviews pull requests for security, performance, and style issues.
---

# Code Review

You are a code reviewer. When the user asks you to review code or a PR...

## What to Check
- Security vulnerabilities (OWASP top 10)
- Performance bottlenecks
- Style consistency with project conventions
...

The name field becomes the slash command (/code-review), and the description tells your AI agent when to activate the skill automatically — no slash command needed.

Progressive Disclosure

Skills load in three stages to keep your context window efficient:

Discovery — At session start, your agent reads only each skill's name and description (~80 tokens per skill). This is how it knows what skills are available.
Activation — When a skill's description matches your current task, the full markdown body loads (~2,000 tokens median). You can also trigger this manually with a slash command.
Execution — During task completion, the skill can pull in additional files (scripts, templates, reference docs) on demand.

This means you can install dozens of skills without bloating your context window — only the relevant one loads at the right time.

Step 1: Browse and Discover Skills

Head to machina.directory/skills to explore the directory. You can:

Browse by category using tags like marketing, security, devops, frontend, or testing
Search by keyword using the search bar (e.g., "code review" or "deploy workflow")
Use semantic search by toggling the AI search mode — describe what you need in plain English (e.g., "a skill that helps me write better commit messages") and the directory finds the closest matches

Each skill listing shows its description, compatibility, install count, and a preview of the instructions. Click into any skill to see the full SKILL.md content before installing.

Step 2: Install Your First Skill

Installation depends on which editor you use. Pick your platform below.

Claude Code

Claude Code reads skills from two locations:

Personal skills (available in all your projects):

mkdir -p ~/.claude/skills/my-skill

Copy the SKILL.md file into ~/.claude/skills/my-skill/SKILL.md.

Project skills (shared with your team via version control):

mkdir -p .claude/skills/my-skill

Copy the SKILL.md file into .claude/skills/my-skill/SKILL.md, then commit it to your repo.

Project skills take priority over personal skills when both exist with the same name.

Cursor

Cursor uses rule files in the .cursor/rules/ directory. Skills from Machina that support Cursor are available as .mdc files:

mkdir -p .cursor/rules

Copy the .mdc rule file into .cursor/rules/. Cursor rules support four modes:

Always Apply — loaded on every interaction
Auto — the agent decides based on the description (equivalent to skill auto-triggering)
Glob-matched — applies only to files matching a pattern (e.g., *.tsx)
Manual — activated via @rule-name mention

Windsurf and Other Editors

Windsurf, Codex CLI, Gemini CLI, and other tools that support the Agent Skills open standard read the same SKILL.md format. Place skills in the .skills/ or .claude/skills/ directory depending on the tool — check your editor's docs for the exact path.

Using the OpenClaw CLI

If the skill is published on ClawHub, you can install it with a single command:

npx clawhub install <skill-slug>

This downloads the skill and places it in the correct directory for your current tool. Run npx clawhub list to see all installed skills, or npx clawhub update --all to refresh them.

Step 3: Configure and Customize

Most skills work out of the box, but you can customize them for your project:

Edit the instructions. Open the SKILL.md file and modify the markdown body. Add project-specific conventions, remove sections that don't apply, or expand areas that matter most to your team.

Adjust the frontmatter. Key options you can change:

Field	What it does
`name`	The slash command name (e.g., `/code-review`)
`description`	Controls when the skill auto-activates — make this specific to reduce false triggers
`user-invocable`	Set to `false` to hide from the slash menu (agent-only skill)

Add supporting files. Create a references/ or templates/ directory next to SKILL.md and add any files the skill should reference. Mention them in your instructions with relative paths — the agent will load them when needed.

Step 4: Verify Your Skill Works

After installation, confirm everything is connected:

In Claude Code: Type / and look for your skill name in the autocomplete menu. Alternatively, describe a task that matches the skill's description — it should activate automatically. If it doesn't, check that the file is in the correct directory and the description field accurately describes when the skill should trigger.

In Cursor: Open the command palette and check that your rule appears in the rules list. Create or open a file that matches the rule's glob pattern (if using glob-matched mode) and verify the AI follows the rule's instructions.

Quick test: Ask your AI assistant to do something the skill covers. For example, if you installed a code review skill, paste a code snippet and ask "review this code." The agent should follow the skill's specific checklist rather than giving a generic review.

Common Questions

How many skills can I install?

There is no hard limit. Thanks to progressive disclosure, only the relevant skill loads into context at any given time. The discovery layer (names and descriptions) uses roughly 80 tokens per skill, so even 100 installed skills add only ~8,000 tokens to your session startup — well within any modern context window.

Do skills slow down my AI assistant?

No. Skills load on demand. At session start, only the lightweight discovery metadata loads. The full skill body loads only when you invoke it or when the agent determines it's relevant. Unused skills have zero performance impact.

Can I create my own skills?

Yes. Create a new directory, write a SKILL.md file with frontmatter and instructions, and place it in the appropriate skills folder for your editor. You can also submit your skill to Machina to share it with the community and get it listed in the directory.

Do skills work offline?

Yes — skills are local markdown files. Once installed, they work entirely offline with no network dependency. The only time you need internet access is to download new skills from the directory or update existing ones.

What's the difference between skills and cursor rules?

Skills follow the Agent Skills open standard and use the SKILL.md format. Cursor rules use Cursor's native .mdc format. Both serve the same purpose — giving your AI agent persistent instructions — but the file format and directory location differ. Many skills on Machina are available in both formats, so you can install whichever matches your editor.

Next Steps

You're set up with your first skill. Here's where to go from here:

Browse all skills — explore 22,000+ skills across every category
Set up MCP servers — connect external tools and APIs to your AI assistant
Write your own cursor rules — create custom rules for your team's coding conventions
Submit a skill — share what you've built with the community

Getting Started with Skills