# AgentSkills.site > A practical reference for agent skills. ## Ecosystems - [Hermes Agent Skills: The Practical Guide](https://agentskills.site/hermes-agent-skills/): What Hermes Agent skills are, where they live, and the eight sources you can install them from. - [The Best Hermes Agent Skills](https://agentskills.site/best-hermes-agent-skills/): Eight Hermes skills worth installing, and exactly what each one is good for. - [How to Install Hermes Agent Skills](https://agentskills.site/how-to-install-hermes-agent-skills/): Install Hermes Agent and start adding skills — every command, verified. - [Hermes Agent Skills on GitHub](https://agentskills.site/hermes-agent-skills-github/): Where to find Hermes skills on GitHub, and how to tell a good repo from a risky one. - [Claude Code Skills: The Practical Guide](https://agentskills.site/claude-code-skills/): What Claude Code skills are, where they live, and the frontmatter fields that only work in Claude Code. - [The Best Claude Code Skills](https://agentskills.site/best-claude-code-skills/): The Claude Code skills worth installing, verified against the actual repos, not another roundup. - [How to Install Claude Code Skills](https://agentskills.site/how-to-install-claude-code-skills/): The three real ways to add a Claude Code skill, and when to use each one. - [Claude Code Skills on GitHub](https://agentskills.site/claude-code-skills-github/): Where to find Claude Code skills on GitHub, and how to vet one before you run it. - [Codex Skills: The Practical Guide](https://agentskills.site/codex-skills/): What Codex skills are, the two skill directories that both still work, and how Codex decides to load one. - [The Best Codex Skills](https://agentskills.site/best-codex-skills/): The Codex skills worth installing, taken from the real catalog rather than another roundup. - [How to Install Codex Skills](https://agentskills.site/how-to-install-codex-skills/): Three ways to add a Codex skill, and which directory each one actually writes to. - [How to Create a Codex Skill](https://agentskills.site/how-to-create-a-codex-skill/): Write a SKILL.md that Codex will actually trigger, then package it so other people can use it. - [Codex Skills vs AGENTS.md](https://agentskills.site/codex-skills-vs-agents-md/): Which one to reach for, and why context cost is the deciding factor. - [Cursor Skills: The Practical Guide](https://agentskills.site/cursor-skills/): All eight directories Cursor loads skills from, and the two frontmatter fields that only exist here. - [Cursor Skills vs Rules](https://agentskills.site/cursor-skills-vs-rules/): Cursor's own migration tool defines which rules should have been skills. Here's what it converts, and what it leaves alone. - [How to Install Cursor Skills](https://agentskills.site/how-to-install-cursor-skills/): Five ways to get a skill into Cursor, and the one that needs no work at all if you already run Claude Code. - [The Best Cursor Skills](https://agentskills.site/best-cursor-skills/): The 19 already installed, the reviewed marketplace, and the test for whether an outside skill will work here. - [OpenClaw Skills: The Practical Guide](https://agentskills.site/openclaw-skills/): The six directories OpenClaw loads from in priority order, and the gating metadata that decides what the agent ever sees. - [How to Install OpenClaw Skills](https://agentskills.site/how-to-install-openclaw-skills/): Every install form and the directory it actually writes to — including two commands that look alike and aren't. - [The Best OpenClaw Skills](https://agentskills.site/best-openclaw-skills/): The 51 skills already in the box, and why ClawHub's download counts can't rank the rest. - [Are OpenClaw Skills Safe?](https://agentskills.site/openclaw-skills-security/): What ClawHub's audits check, what they can't catch, and what the independent research actually found. - [How to Create an OpenClaw Skill](https://agentskills.site/how-to-create-an-openclaw-skill/): Write a skill that hides itself when its dependency is missing, then publish it to ClawHub. ## The standard, across ecosystems - [Agent Skills Not Working: A Diagnostic Reference](https://agentskills.site/agent-skills-not-working/): Why a skill doesn't load, doesn't appear, or doesn't trigger — sorted by mechanism, traced to the issue or document it came from. - [Where to Find Agent Skills](https://agentskills.site/where-to-find-agent-skills/): Seven kinds of source, what each one's provenance is worth, and what their download numbers actually count. - [SKILL.md: The Agent Skill File Format](https://agentskills.site/skill-md/): Every frontmatter field with its real constraints, and where five runtime implementations diverge from the spec. - [Agent Skills Compatibility: Which Agents Support SKILL.md](https://agentskills.site/agent-skills-compatibility/): What support means in each runtime, with explicit evidence levels — and the field that silently breaks a skill. - [Agent Skills vs MCP](https://agentskills.site/agent-skills-vs-mcp/): Two layers, not two options — argued from the manifests and hooks that already ship, rather than from analogy. ## Tools and browsing - [Agent Skills Library](https://agentskills.site/skills/): Search and browse a curated, source-verified set of agent skills. - [Browse Agent Skills by Topic](https://agentskills.site/topics/): Skills grouped into a small set of broad categories. - [Agent Skill Creators](https://agentskills.site/creators/): Every person and organization this site has catalogued a source from. - [Agent Skill Sources](https://agentskills.site/sources/): Every repository, plugin marketplace, and bundled collection catalogued. - [AgentSkills Doctor](https://agentskills.site/doctor/): A deterministic, offline skill-stack recommender — no model call. - [SKILL.md Validator](https://agentskills.site/skill-md/validate/): Check a skill against the specification and five real runtimes, in the browser. - [SKILL.md Validator — Rule Reference](https://agentskills.site/skill-md/rules/): Every rule the validator checks, each with its own page and sources. - [About AgentSkills.site](https://agentskills.site/about/): What this site is, how it's researched, and what it deliberately isn't. - [Skills dataset (JSON)](https://agentskills.site/skills.json): The full skills/topics/creators/sources dataset as structured JSON. ## Full text - [Full text export](https://agentskills.site/llms-full.txt): Every editorial page on this site, inlined as markdown. --- ## About ## What this is AgentSkills.site is an independent reference site about agent skills — the `SKILL.md`-based system, standardized at [agentskills.io](https://agentskills.io), that lets AI agents load specialized capabilities on demand. We publish focused, verified guides organized around specific agent ecosystems. Three are live: **Hermes Agent**, the open-source agent built by Nous Research; **Claude Code**, Anthropic's agentic coding CLI; and **Codex**, OpenAI's coding agent. We are not affiliated with Nous Research, Anthropic, OpenAI, or any agent vendor we write about. We don't sell a product related to any of these tools. ## Why this exists Search results for emerging technical topics like this fill quickly with content that either lightly rewrites the official documentation, or ranks things ("best skills," "top tools") without saying what the ranking is actually based on. Neither is that useful if you're trying to get something working. We wrote each page in this cluster only after checking what already ranks and identifying a clear reason for the page to exist beyond paraphrasing that. Sometimes that reason is missing information — a mechanic nobody explained, a fact scattered across multiple docs pages that nobody had assembled in one place. Just as often it's substantially better synthesis, organization, verification against primary sources, or a more usable structure than what's already out there — the individual facts don't have to be novel for the page to be worth publishing, as long as putting them together this way is. The research notes behind this cluster are the basis for what got published; pages that didn't clear that bar didn't get written. ## Editorial methodology **Primary sources first.** For factual and technical claims — commands, file paths, configuration keys, system behavior — we go to the official documentation and the official GitHub repository directly, not to secondary writeups. Where we cite a command or path, we cross-checked it against the documented source and, where practical, against the actual source code in the repository (not just the marketing docs site). **Community sources are cited as what they are.** When we reference a community repository, a third-party tool, or a claim made by an unofficial source, we attribute it as such — we don't launder a repo's own marketing claim ("70+ verified skills") into a fact we assert independently. **No fabricated testing.** We do not claim to have run software, installed skills, or benchmarked anything unless we actually did. Where a page discusses expected behavior based on documentation rather than direct testing, it says so. **Official facts vs. our interpretation.** Where we're explaining documented behavior, we say what's documented. Where we're offering a recommendation, a category judgment, or a "here's what we'd check" — that's clearly framed as editorial judgment, not as a vendor's stated fact. **No fake precision.** If public evidence doesn't support a ranking or a specific number, we say that directly instead of presenting a guess as data. This is why our "best skills" coverage uses stated criteria and categories rather than a numbered list. ## Corrections and updates Software documentation changes, and so does the skills ecosystem this site covers. When we're made aware of something that's gone stale or turns out to be wrong, we update the affected page and its "Updated" date. We don't quietly rewrite history — if a page's core claims change materially, that's a new "Updated" date, not a silent edit. This site does not use invented author personas or fabricated credentials. Pages are published under editorial ownership of AgentSkills.site as a whole, not an individual byline, because that's an accurate description of how they're produced. ## Reusing this data The structured dataset behind [the skills library](/skills/) — skills, topics, creators, sources, and this site's own analysis fields (what a skill does, when to use it, when not to) — is published as JSON at [`/skills.json`](/skills.json), under **CC-BY-4.0**, attributed to AgentSkills.site. That license covers this dataset's structure and our own analysis; it doesn't relicense the underlying skills themselves, which stay under whatever license their own source carries (recorded per source in the export). Two other machine-readable exports exist for the same reason this site exists for humans — so the facts don't have to be re-derived from HTML: [`/llms.txt`](/llms.txt) is a short index of every page, and [`/llms-full.txt`](/llms-full.txt) inlines the full text of all of them. Every rule the [SKILL.md validator](/skill-md/validate/) checks also has a real page at [`/skill-md/rules/`](/skill-md/rules/), sourced the same way as everything else here. ## What's next The architecture here is built to extend to other agent ecosystems — OpenClaw, Cursor, and others — as separate, equally researched clusters, without restructuring what already exists. We'd rather ship one excellent cluster than five thin ones, so new clusters go up when they clear the same bar the existing ones did, not on a schedule. --- ## The Best Claude Code Skills We haven't run these ourselves, so this is a sourcing job, not a hands-on review: every install command below comes from actually reading the repo's `.claude-plugin/marketplace.json` or `SKILL.md`, not from a listicle. Full method is below the shortlist. ## The shortlist | Skill / plugin | Best for | Trust context | Install | |---|---|---|---| | `superpowers` | Structured development methodology (TDD, planning, debugging discipline) | External, community — 272k+ stars, MIT, self-hosted plugin marketplace | `/plugin marketplace add obra/superpowers` then `/plugin install superpowers@superpowers-dev` | | `document-skills` | Generating/editing Word, PDF, PowerPoint, Excel files | Official (Anthropic) — Proprietary license | `/plugin marketplace add anthropics/skills` then `/plugin install document-skills@anthropic-agent-skills` | | `example-skills` | Building/evaluating your own skills, MCP servers, testing, frontend design | Official (Anthropic) | `/plugin marketplace add anthropics/skills` then `/plugin install example-skills@anthropic-agent-skills` | | `claude-api` | Building on the Claude API/SDK | Official (Anthropic) | `/plugin marketplace add anthropics/skills` then `/plugin install claude-api@anthropic-agent-skills` | | `audit-context-building` | Understanding a codebase before a security review | External, vendor-official (Trail of Bits) | `/plugin marketplace add trailofbits/skills` then `/plugin install audit-context-building@trailofbits` | | `nvidia-skills` | GPU acceleration, CUDA, robotics, Physical AI workflows | External, vendor-official (NVIDIA) — Apache-2.0 | `/plugin marketplace add NVIDIA/skills` then `/plugin install nvidia-skills@nvidia-official` | | `book-to-skill` | Turning a technical book or doc set into a reusable skill | External, community — MIT, cross-agent | `npx skills add virgiliojr94/book-to-skill --agent claude-code` | ## Why each one, with the caveat that matters **`superpowers` — best for development methodology.** obra/superpowers is large and independently popular (272,580 stars as of this writing, MIT), and ships its own self-hosted plugin marketplace — `.claude-plugin/marketplace.json` names it `superpowers-dev`, authored by Jesse Vincent. It bundles skills for brainstorming, planning, TDD, systematic debugging, and code review into one methodology rather than one narrow task. This is the same framework Nous Research separately adapted into Hermes Agent's own bundled skills, under a different name, which says something about how widely its approach has been copied. Caveat: it's opinionated about *process*, not just capability — it'll only help if you actually follow the workflow it enforces. **`document-skills` — best official document generation.** One plugin bundling four Anthropic-authored skills — `xlsx`, `docx`, `pptx`, `pdf` — each with a long, specific `description` telling Claude exactly when to trigger (down to phrases like "Word doc" or "the deck"). Caveat: these are Proprietary-licensed (LICENSE.txt in the repo has the actual terms), not MIT — read the license before redistributing, even though using them inside Claude Code is unrestricted. **`example-skills` — best official grab-bag.** A single plugin bundling twelve Anthropic reference skills at once: `skill-creator`, `mcp-builder`, `webapp-testing`, `frontend-design`, `canvas-design`, `theme-factory`, `brand-guidelines`, and five more. You can't install just one through the plugin route — it's all twelve or none — though nothing stops you copying a single skill's folder into `~/.claude/skills/` by hand if you only want one. `skill-creator` in particular is worth knowing about even if you install nothing else from this bundle: it's what runs the eval workflow described on [the flagship page](/claude-code-skills/#evaluating-a-skill-with-skill-creator). **`claude-api` — best for building on the Claude API.** A single, narrow official skill: Claude API and SDK documentation, packaged so Claude can reference it while you build an LLM-powered app rather than guessing at method signatures. **`audit-context-building` — best for pre-audit codebase understanding.** One of several plugins in Trail of Bits's own marketplace (`trailofbits`, per their `marketplace.json`) — a well-known security research firm, not an anonymous contributor. It reads a codebase function by function, records what each one assumes and depends on, and writes the results to files instead of filling up your conversation. Trail of Bits also publishes narrower security plugins (smart-contract auditing, for one) in the same marketplace if your need is more specific than general codebase review. Caveat: CC-BY-SA-4.0, not MIT — a share-alike license, worth knowing if you plan to fork or redistribute it. **`nvidia-skills` — best for GPU/CUDA/robotics work.** NVIDIA's own marketplace (`nvidia-official`) ships one plugin that acts as a router across their full catalog: GPU acceleration, CUDA, agent training, data loading, inference, robotics, Physical AI, Omniverse, and simulation workflows. Apache-2.0. Explicitly built to work in both Claude Code and Codex, per NVIDIA's own repo description — genuinely useful if your work touches any of those domains, genuinely irrelevant otherwise. **`book-to-skill` — best for turning a document into a skill.** A standalone, MIT-licensed, cross-agent skill (works in Claude Code, GitHub Copilot CLI, and Amp) that converts a PDF, EPUB, DOCX, or plain-text document into a structured skill — extracting frameworks and mental models rather than producing a summary. Real standalone traction (over 20,000 stars) for a single-purpose tool, not a mega-registry. Caveat: it needs shell access to run its own extraction script, so review what that script does before granting it — the repo's own notes say `allowed-tools` is deliberately left out of its frontmatter to stay agent-neutral, meaning each host agent, Claude Code included, prompts you for shell and file permissions on first use rather than the skill pre-approving itself. ## Where public evidence runs out The long tail here is enormous — GitHub search turns up dozens of "awesome-claude-code-skills" registries, each claiming its own curated count, and hundreds of narrow single-purpose repos for specific frameworks, languages, and internal workflows. Star counts on the narrow ones cluster low and close together, and there's no independent usage signal beyond stars and push recency. If you need something specific that isn't above, evaluate the candidates yourself against the [repository checklist](/claude-code-skills-github/#how-to-evaluate-a-skill-before-installing-it) rather than trust a ranked list — ours or anyone else's — that would be guessing at that scale. ## How we decided what belongs here Same weighting as elsewhere on this site: **provenance** first (official Anthropic skills and named-vendor marketplaces — Trail of Bits, NVIDIA — get priority over anonymous community repos); **verifiability** (every install command above came from reading the actual `marketplace.json` or `SKILL.md`, not a blog post); **maintenance signal** (push recency — the only real observable signal; no download telemetry exists for any of this); and **breadth vs. specificity** (seven picks covering genuinely different jobs, not seven variations on the same one). We didn't pad this to ten — three more candidates were considered and dropped because we couldn't independently verify their install path or maintenance status to the same standard. ## Sources - [obra/superpowers (GitHub)](https://github.com/obra/superpowers) — `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json` - [anthropics/skills (GitHub)](https://github.com/anthropics/skills) — `.claude-plugin/marketplace.json` - [trailofbits/skills (GitHub)](https://github.com/trailofbits/skills) — `.claude-plugin/marketplace.json` - [NVIDIA/skills (GitHub)](https://github.com/NVIDIA/skills) — `.claude-plugin/marketplace.json` - [virgiliojr94/book-to-skill (GitHub)](https://github.com/virgiliojr94/book-to-skill) — `SKILL.md` - Repository metadata (stars, license, last-push date) pulled directly via the GitHub API, August 2026 --- ## Claude Code Skills on GitHub ## Start with the official repository [github.com/anthropics/skills](https://github.com/anthropics/skills) is Anthropic's own reference skills repo — 17 skills including the document family (`docx`, `pdf`, `pptx`, `xlsx`), `skill-creator`, `mcp-builder`, `webapp-testing`, and `frontend-design`. Worth knowing before you install any of these: the document skills are Proprietary-licensed (LICENSE.txt has the terms), and most of the rest say only "complete terms in LICENSE.txt" — none of this is MIT, unlike a lot of what shows up further down this page. ## Official plugin marketplaces Plugins can bundle skills with agents, hooks, and MCP servers. Anthropic runs three catalogs, with real differences in how much vetting each one implies: | Marketplace | What it is | Added | |---|---|---| | `claude-plugins-official` | Curated directly by Anthropic | Automatically, on first interactive launch | | `claude-plugins-community` ([anthropics/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)) | Third-party plugins that passed automated validation + safety screening, pinned to a commit SHA | `/plugin marketplace add anthropics/claude-plugins-community` | | `claude-code-plugins` (in [anthropics/claude-code](https://github.com/anthropics/claude-code)`/plugins`) | Demo/example plugins, not vetted for production use | `/plugin marketplace add anthropics/claude-code` | Full install commands: [how to install Claude Code skills](/how-to-install-claude-code-skills/#5-install-a-skill-bundled-in-a-plugin). ## Real vendor and community skill sources | Source | What it actually is | |---|---| | [`obra/superpowers`](https://github.com/obra/superpowers) | A large, independently popular software-development-methodology skill framework — brainstorming, planning, TDD, debugging. MIT-licensed. This is the same framework Nous Research separately adapted for Hermes Agent's own bundled skills. | | [`trailofbits/skills`](https://github.com/trailofbits/skills) | Trail of Bits — a well-known security research firm — publishing their own skills for security research, vulnerability detection, and audit workflows. CC-BY-SA-4.0. | | [`NVIDIA/skills`](https://github.com/NVIDIA/skills) | NVIDIA's own skills for Physical AI, robotics, simulation, CUDA, and RAG workflows, explicitly built to work in Claude Code and Codex both. Apache-2.0. | | [`vercel-labs/skills`](https://github.com/vercel-labs/skills) | Not a skill catalog — the `npx skills` installer tool itself (see [how to install](/how-to-install-claude-code-skills/#4-install-with-npx-skills)). MIT-licensed, cross-agent. | Beyond these, there's a long tail of "awesome-claude-code-skills"-style community registries — several exist, each claiming its own curated count. Treat those claims as the repo's own marketing, the same way you'd treat a "70+ verified skills" claim anywhere else: real, but self-reported, not independently audited. GitHub is only one of the places skills are distributed — [where to find agent skills](/where-to-find-agent-skills/) covers registries, marketplaces and vendor packs alongside it, and what each source's download numbers actually count. ## How to evaluate a skill before installing it Claude Code has no automated scanner for a hand-written or `npx skills`-installed skill — see [is a skill checked for anything before it runs?](/how-to-install-claude-code-skills/#is-a-skill-checked-for-anything-before-it-runs) That makes this checklist do more work here than on ecosystems with an install-time security gate. **1. Does the `description` actually match what you'd say?** Claude matches your request against it. A vague or overly broad description means the skill fires on requests it shouldn't, or never fires at all. **2. What's in `allowed-tools`?** This is the field that matters most for risk. It pre-approves tools for the entire turn that invokes the skill without asking you — including Bash commands matching a pattern. A skill granting itself broad `Bash(*)` access is a real thing to notice, not a formality. **3. Does it use `context: fork`?** A forked skill runs as a background subagent with its own tool access and no view of your conversation history. Check what `agent` it specifies and what that agent type can do before trusting a forked skill with anything sensitive. **4. What do the `!`-injected commands do?** Anything on a line starting with `` !`command` `` runs before Claude ever sees the skill content. Read every injected command the same way you'd read a `postinstall` script — it runs unconditionally, with no confirmation prompt, the moment the skill loads. **5. Is it a plugin or a standalone skill?** A plugin from the community marketplace passed automated validation and safety screening; a standalone `SKILL.md` you copied from a repo passed through nothing. Know which one you're installing. **6. License and last commit.** Same as anywhere else: check there is one, and that push recency (not stars) is your real signal for whether something is still maintained. ## Sources - [anthropics/skills (GitHub)](https://github.com/anthropics/skills) - [Claude Code — Discover and install plugins (official docs)](https://code.claude.com/docs/en/discover-plugins) - [Claude Code — Skills (official docs)](https://code.claude.com/docs/en/skills) - Live GitHub repository search conducted August 2026 for Claude-Code-skill-related repositories --- ## Claude Code Skills: The Practical Guide ## What Claude Code skills are **Claude Code** is Anthropic's agentic coding CLI — it also runs in the browser, a desktop app, VS Code, JetBrains, Slack, and CI/CD, but the terminal is the reference environment. A **skill** is a directory with a `SKILL.md` file: YAML frontmatter that tells Claude when to use it, plus markdown instructions Claude follows once it does. Type `/skill-name` to run one directly, or let Claude load it automatically when your request matches its description. Claude Code skills follow the **[Agent Skills](https://agentskills.io) open standard**, which Anthropic originally developed and which now works across Claude Code, Cursor, VS Code, Gemini CLI, and others. Claude Code is close to the reference implementation, and it extends the base spec with fields the standard doesn't define — invocation control, subagent execution, dynamic context injection. Which fields are portable and which are Claude-Code-only matters the moment you try to share a skill outside Claude Code, and it's the first thing this page covers. The portable half is documented in [SKILL.md, the format itself](/skill-md/). **Custom commands and skills are the same thing now.** A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work identically. Skills just add optional extras: a directory for supporting files, more frontmatter, and the ability for Claude to load them automatically. ## Where skills live Where you put a skill determines who can use it, and conflicts resolve in a fixed order: | Location | Path | Applies to | |---|---|---| | Enterprise | Managed settings | Everyone in your organization | | Personal | `~/.claude/skills//SKILL.md` | All your projects | | Project | `.claude/skills//SKILL.md` | This project only | | Plugin | `/skills//SKILL.md` | Wherever the plugin is enabled | When two skills share a name: **enterprise overrides personal, and personal overrides project.** A skill at any of those levels also overrides a bundled skill with the same name (but not the bundled skill's alias — a project `code-review` skill replaces `/code-review`, but typing the bundled alias `/review` still runs the original). Plugin skills are namespaced (`/plugin-name:skill-name`), so they never collide with anything else. A skill or command from any local source overrides a same-named skill synced from your claude.ai account. Project skills also load from every `.claude/skills/` between your starting directory and the repository root, and — separately — from nested `.claude/skills/` directories *below* your starting directory the first time Claude touches a file there. A nested skill with the same name as one above it doesn't override; both stay available, with the nested one addressable as `apps/web:deploy` while the unqualified `/deploy` still runs the higher-level one (and Claude is told to also consider the nested variant when it's relevant). Claude Code watches skill directories for changes and picks up edits within the session — no restart needed, unless you create a brand-new top-level skills directory that didn't exist when the session started. Worth knowing if you use more than one agent: these directories aren't private to Claude Code. [Cursor reads `~/.claude/skills/` and `.claude/skills/` directly](/cursor-skills/#where-cursor-looks-for-skills) for compatibility, so a skill written here is already available there with nothing to copy. OpenClaw takes the other approach and offers [a migration command](/openclaw-skills/#coming-from-claude-code) instead. ## The SKILL.md format, and what only works in Claude Code ```text my-skill/ ├── SKILL.md # required ├── template.md # optional: for Claude to fill in ├── examples/ │ └── sample.md └── scripts/ └── validate.sh # optional: Claude can execute this ``` Only `SKILL.md` is required. `name` and `description` are the only frontmatter fields most skills need — `description` is what Claude matches against your request, so put the key use case first. Here's the split that matters if you plan to use a skill anywhere besides Claude Code. The full Claude Code frontmatter has about twenty optional fields. Package a skill for claude.ai uploads, the Skills API, or `anthropics/skills`' own `package_skill.py`, and only **six** of them are allowed: | Portable (works everywhere) | Claude-Code-only | |---|---| | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` | `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `disallowed-tools`, `model`, `effort`, `context`, `agent`, `background`, `hooks`, `paths`, `shell` | Include a Claude-Code-only field when packaging for one of those portable paths, and validation fails outright with `Unexpected key(s) in SKILL.md frontmatter`, rather than silently dropping it. The reverse isn't a problem: every field in the left column plus every field in the right column works fine inside Claude Code itself — the restriction only bites when a skill leaves Claude Code. The two frontmatter fields worth knowing by name: - **`disable-model-invocation: true`** — only you can run it, with `/name`. Use for anything with side effects: `/deploy`, `/commit`, sending a message. Claude is explicitly blocked from working around this if it tries. - **`user-invocable: false`** — only Claude can run it. Use for background knowledge — conventions, context — that isn't a meaningful action for a person to trigger by hand. ## How skills are discovered and loaded Skill descriptions load into context at session start so Claude knows what's available; full `SKILL.md` content loads only when a skill actually runs, and it stays in the conversation for the rest of the session — Claude doesn't re-read the file on later turns, so write instructions as standing guidance, not one-time steps. If you have a lot of skills, the description listing itself has a budget: 1% of the model's context window by default. When it overflows, Claude Code drops descriptions starting with your least-used skills first. `/doctor` shows the listing's context cost; raise the budget with the `skillListingBudgetFraction` setting if you need to. Auto-compaction carries invoked skills forward, but not indefinitely: after a summary, Claude Code re-attaches each skill's most recent invocation (up to 5,000 tokens each), sharing a combined 25,000-token budget across all of them — most-recently-invoked first. If a skill seems to stop influencing behavior after compaction, re-invoke it. ## Skills you don't need to install Claude Code ships with bundled skills in every session — they aren't installed from anywhere, and third-party "best skills" lists routinely fold them in as if they were: `/code-review`, `/debug`, `/loop`, `/batch`, `/claude-api`, `/doctor`, and the trio that launches and verifies your app — `/run`, `/verify`, and `/run-skill-generator`, which records a per-project launch recipe the first time it has to figure one out from scratch. Turn all of them off except `/doctor` with the `disableBundledSkills` setting. ## Skills vs. commands vs. plugins vs. subagents vs. MCP Five terms, five different jobs: | Concept | What it is | How it's invoked | |---|---|---| | **Command** (`.claude/commands/*.md`) | The older, flatter precursor to skills — same frontmatter, no supporting-file directory | `/name` | | **Skill** | `SKILL.md` plus optional bundled files — instructions, invoked directly or model-matched | `/name`, or automatically when relevant | | **Plugin** | A packaged bundle that can include skills, agents, hooks, and MCP servers together | Installed via `/plugin install`, skills namespaced as `/plugin:name` | | **Subagent** | A separate agent configuration (system prompt, tools, model) that can preload skills as reference material | Delegated to, or run via a skill with `context: fork` | | **MCP server** | An external protocol connection giving Claude new tools | Configured separately; skills can instruct Claude to use MCP-provided tools | That last row is the one people most often read as a choice between two things. It isn't — [Agent Skills vs MCP](/agent-skills-vs-mcp/) works through the distinction using the manifests and dependency declarations that already ship, including the plugin format that packages both together. A skill with `context: fork` runs as a forked subagent in the background by default (set `background: false` to wait for it inline) — useful for research or review tasks that shouldn't crowd your main conversation. The built-in `Explore` and `Plan` agent types skip loading `CLAUDE.md` to keep their context small, so a forked skill using one of them sees only its own `SKILL.md` content and that agent's system prompt. ## Dynamic context injection A line starting with `` !`command` `` runs a shell command *before* the skill content reaches Claude, and the output replaces the placeholder — Claude sees real data, not the command that produced it: ```yaml --- name: pr-summary description: Summarize changes in a pull request context: fork agent: Explore allowed-tools: Bash(gh *) --- ## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` ## Your task Summarize this pull request... ``` A failed command aborts the whole invocation — Claude never sees the skill for that run. With the default bash shell, append `|| true` to any command you expect to sometimes exit non-zero. This never runs for a skill synced from your claude.ai account; those commands reach Claude as literal text instead, so a skill that depends on injected context behaves differently once synced. ## Evaluating a skill with skill-creator Anthropic's official [`skill-creator` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator) (`/plugin install skill-creator@claude-plugins-official`) automates the only real way to know a skill works: a baseline comparison, run with the skill available and again with it disabled, on realistic prompts in a fresh session each time. It stores test cases in `evals.json`, runs each in an isolated subagent, grades output against your assertions, and rolls the results into a with-skill-vs-without-skill benchmark — plus a blind A/B between two versions of a skill, so you can confirm an edit actually helped before you commit it. ## Common setup questions **Do commands and skills conflict?** A file in `.claude/commands/` and a skill with the same name both create the same slash command — the skill wins. **Where should I start looking for skills?** See [the best Claude Code skills](/best-claude-code-skills/) for a shortlist verified against the actual repos, and [Claude Code skills on GitHub](/claude-code-skills-github/) for how to vet a repository yourself. **Is a skill scanned for anything dangerous before it runs?** Not on its own — see [how to install Claude Code skills](/how-to-install-claude-code-skills/#is-a-skill-checked-for-anything-before-it-runs) for what actually gates a skill versus a plugin. ## Limitations and caveats - Frontmatter fields and version-gated behaviors here (for example, features requiring "Claude Code v2.1.145 or later") are current as of the docs snapshot in August 2026 and will drift as the CLI updates. Check the [official skills docs](https://code.claude.com/docs/en/skills) if you're reading this much later. - We have not run Claude Code or installed any of these skills ourselves. Behavior described here is documented behavior, not something we tested firsthand. - The community-marketplace review pipeline's "automated validation and safety screening" is described only at a high level in the official docs; we have not independently verified how strict it is. ## Sources - [Claude Code — Skills (official docs)](https://code.claude.com/docs/en/skills) - [Claude Code — Plugins](https://code.claude.com/docs/en/plugins) - [Claude Code — Discover and install plugins](https://code.claude.com/docs/en/discover-plugins) - [anthropics/skills (GitHub) — official reference skills repo](https://github.com/anthropics/skills) - [agentskills.io — the open standard Claude Code implements](https://agentskills.io) --- ## How to Install Claude Code Skills ## 1. Install Claude Code first **macOS, Linux, or WSL:** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **Windows PowerShell:** ```powershell irm https://claude.ai/install.ps1 | iex ``` **Windows CMD:** ```batch curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ``` **Homebrew** (two casks — `claude-code` tracks stable, `claude-code@latest` tracks every release): ```bash brew install --cask claude-code ``` **WinGet:** ```powershell winget install Anthropic.ClaudeCode ``` apt, dnf, and apk are also supported on Debian, Fedora, RHEL, and Alpine. Confirm the install: ```bash claude --version ``` Then start a session — you'll be prompted to log in on first use: ```bash claude ``` Native installs auto-update in the background. Homebrew and WinGet installs don't — run `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` yourself periodically. ## 2. The three ways to add a skill Unlike some agent ecosystems, there's no single "install a skill" command. Which path applies depends on what you're adding: | Method | Use when | Shareable? | |---|---|---| | [Write the file by hand](#3-write-a-skill-by-hand) | You're writing your own skill, or copying one from a repo you've already read | Commit it to the repo | | [`npx skills`](#4-install-with-npx-skills) | Pulling a skill from GitHub without cloning it yourself | Per-machine, not versioned with your project | | [Plugin marketplace](#5-install-a-skill-bundled-in-a-plugin) | The skill ships as part of a plugin (bundled with agents, hooks, or MCP servers) | Yes — this is the only path with any review process behind it | ## 3. Write a skill by hand A skill is just a file. For a personal skill available in every project: ```bash mkdir -p ~/.claude/skills/my-skill ``` For a project skill, scoped to one repo: ```bash mkdir -p .claude/skills/my-skill ``` Save `SKILL.md` inside it with at minimum `name` and `description` in the frontmatter (see [the SKILL.md format](/claude-code-skills/#the-skillmd-format-and-what-only-works-in-claude-code) for the full field reference). Claude Code picks up the new file within the current session — no restart needed unless the top-level skills directory itself is brand new. ## 4. Install with npx skills [`npx skills`](https://github.com/vercel-labs/skills) is a third-party, MIT-licensed, cross-agent skill installer maintained by Vercel — not an Anthropic tool, but built specifically to pull `SKILL.md` files from GitHub into whichever agent you're using, Claude Code included. List what a repo offers before installing anything: ```bash npx skills add / --list ``` Install a specific skill into Claude Code: ```bash npx skills add https://github.com/anthropics/skills --skill docx --agent claude-code ``` Add `--yes` for non-interactive installs. The tool defaults to symlinking rather than copying, so updating the source updates every project that references it. ## 5. Install a skill bundled in a plugin Plugins can bundle skills alongside agents, hooks, and MCP servers, distributed through a **marketplace** — a catalog of plugins someone else published. Anthropic runs two: - **`claude-plugins-official`** — curated by Anthropic, added automatically the first time you start Claude Code interactively. If it wasn't added automatically: ```bash /plugin marketplace add anthropics/claude-plugins-official ``` - **`claude-plugins-community`** — third-party plugins that passed automated validation and safety screening, pinned to a commit SHA. Not added automatically: ```bash /plugin marketplace add anthropics/claude-plugins-community ``` Install from either: ```bash /plugin install @claude-plugins-official /plugin install @claude-community ``` Anyone can also host their own marketplace and you add it directly — a GitHub repo (`owner/repo`), any git URL, a local path, or a remote `marketplace.json`: ```bash /plugin marketplace add owner/repo /plugin marketplace add https://gitlab.com/company/plugins.git ``` If the install summary says `Run /reload-plugins to activate.`, run that command — new plugin skills don't apply automatically until you do. Plugin skills are namespaced by plugin name, so a `commit-commands` plugin's commit skill is `/commit-commands:commit`, never a bare `/commit`. ## Managing plugins and marketplaces ```bash /plugin # open the interactive plugin manager /plugin list # list installed plugins /plugin disable @ /plugin enable @ /plugin uninstall @ /plugin marketplace list /plugin marketplace update /plugin marketplace remove /reload-plugins ``` For scripting or CI, use the non-interactive shell commands instead, which target user scope by default: ```bash claude plugin install @ --scope project claude plugin uninstall @ --scope project claude plugin validate ./your-plugin ``` ## Is a skill checked for anything before it runs? Not automatically, and not for every path above. This is the single biggest difference from ecosystems that scan every install: - **Hand-written or `npx skills`-installed skills** pass through nothing before their instructions become active — a skill is just a file Claude reads. Any `allowed-tools` grant in its frontmatter takes effect the moment you invoke it. - **Plugins from the community marketplace** go through Anthropic's automated validation and safety screening before publication, and are pinned to a specific commit — the closest thing to a trust gate in this system, and it only covers that one path. - **The official marketplace** is curated by Anthropic directly, at Anthropic's discretion. Anthropic's own guidance is blunt about the rest: "Anthropic doesn't control what MCP servers, files, or other software are included in plugins and can't verify that they work as intended." Read a skill's `SKILL.md` and any bundled scripts before installing anything outside the two official marketplaces — see [evaluating a skill on GitHub](/claude-code-skills-github/#how-to-evaluate-a-skill-before-installing-it) for what to check. ## Troubleshooting | Symptom | Fix | |---|---| | `/plugin` command not recognized | Update: `brew upgrade claude-code`, `npm install -g @anthropic-ai/claude-code@latest`, or re-run the native installer, then restart your terminal | | Plugin skills don't appear after install | `rm -rf ~/.claude/plugins/cache`, restart Claude Code, reinstall | | Skill doesn't trigger automatically | Check the description includes words you'd naturally use; try `/skill-name` directly if it's user-invocable; run with `--debug` to catch a malformed-YAML parse error | | Skill triggers too often | Make the description more specific, or add `disable-model-invocation: true` for manual-only use | | `Marketplace "..." not found` | Add it first with `/plugin marketplace add /`, then retry the install | ## Sources - [Claude Code — Quickstart (official docs)](https://code.claude.com/docs/en/quickstart) - [Claude Code — Discover and install plugins](https://code.claude.com/docs/en/discover-plugins) - [Claude Code — Skills](https://code.claude.com/docs/en/skills) - [vercel-labs/skills (GitHub) — the `npx skills` tool](https://github.com/vercel-labs/skills) --- ## The Best Codex Skills Nine Codex skills worth knowing: three already ship with Codex, six are one command away in OpenAI's curated catalog. Each was checked by reading its actual `SKILL.md`. We haven't run them — this is sourcing, not a hands-on review — and the criteria are stated below the table. One thing to know before installing anything: **OpenAI's skills catalog repository is deprecated.** Details in [where Codex skills live on GitHub](#where-codex-skills-live-on-github) below; it doesn't stop these working today, but it changes where you should look next. ## The shortlist | Skill | Best for | Provenance | Install | |---|---|---|---| | `skill-creator` | Writing your own skills | Bundled with Codex | Already available | | `skill-installer` | Installing everything else | Bundled with Codex | Already available | | `review-agent` | Reviewing changes | Bundled with Codex | Already available | | `gh-fix-ci` | Debugging failing GitHub Actions checks on a PR | Curated catalog | `$skill-installer gh-fix-ci` | | `gh-address-comments` | Working through PR review comments | Curated catalog | `$skill-installer gh-address-comments` | | `playwright` | Driving a real browser from the terminal | Curated catalog | `$skill-installer playwright` | | `security-threat-model` | Repository-grounded AppSec threat modeling | Curated catalog | `$skill-installer security-threat-model` | | `migrate-to-codex` | Moving skills and config in from another agent | Curated catalog | `$skill-installer migrate-to-codex` | | `pdf` | Reading and generating PDFs where layout matters | Curated catalog | `$skill-installer pdf` | Provenance means something specific here. **Bundled** skills ship inside Codex itself — they're in the `openai/codex` repository, need no install, and are the highest-confidence entries on this list. **Curated** means the skill lives in the `.curated` folder of OpenAI's catalog repo: OpenAI chose to publish it there, which is a real editorial signal, but it is not a performance benchmark and several curated skills are narrow vendor integrations. There's no public install or usage telemetry for any Codex skill, so nobody — us included — can rank these by popularity. ## Why each one **`skill-creator` and `skill-installer` — the two you already have.** Both bundled, so `$skill-creator` and `$skill-installer` work in a fresh Codex install with nothing configured. Worth knowing they exist before you go looking for third-party tooling to do the same jobs. `review-agent` is bundled too, and is the current in-box option for reviewing changes. **`gh-fix-ci` — the strongest single-task pick.** Its description scopes it tightly: use `gh` to inspect failing PR checks, fetch the GitHub Actions logs, summarize the failure, then "propose a fix plan and implement after explicit approval." That approval gate is written into the skill itself, which is the behavior you want from something touching CI. It's also honest about its limits — it explicitly treats non-Actions providers like Buildkite as out of scope and just reports the details URL rather than pretending to handle them. Caveat: it references a `create-plan` skill as an optional collaborator, and `create-plan` lived in the catalog's `.experimental` folder, which no longer exists. **`gh-address-comments` — the companion to it.** Finds the open PR for your current branch and works through its review comments with the `gh` CLI. Its `SKILL.md` front-loads the prerequisite properly: verify `gh auth status` first and prompt you to authenticate rather than failing halfway through. It notes that sandboxing may block `gh auth status` and that the command needs escalated permissions — an unusually practical detail to find in a skill file. **`playwright` — browser automation without the test framework.** Drives a real browser from the terminal for navigation, form filling, screenshots, and data extraction, using a bundled wrapper script so it works even when `playwright-cli` isn't installed globally. Its instructions are explicit that it is CLI-first and will not pivot to writing `@playwright/test` files unless you ask — a useful boundary, since "automate the browser" and "write me a test suite" are different requests. There's also a `playwright-interactive` variant in the catalog. **`security-threat-model` — the best-written description in the catalog.** It produces a repository-grounded threat model — trust boundaries, assets, attacker capabilities, abuse paths, mitigations — written to a Markdown file. What makes it worth studying even if you never install it is the description: roughly half of it is negative triggers, spelling out that it should *not* fire for general architecture summaries, code review, or non-security design work. That's exactly the discipline the [context budget](/codex-skills/#the-context-budget-that-shapes-everything) rewards. OpenAI publishes two adjacent security skills as well, `security-best-practices` and `security-ownership-map`. **`migrate-to-codex` — the switching-cost skill.** Migrates instruction files, skills, agents, and MCP config from another agent into Codex's own files. Its instructions are notably careful about blast radius: it will create and edit Codex artifacts (`AGENTS.md`, `.codex/`, `.agents/`, `~/.codex/`) without asking once you've picked a target, but it explicitly will not touch the source agent's files or unrelated config entries. If you're arriving from Claude Code, this is the intended on-ramp. **`pdf` — the one document skill worth calling out.** Handles reading, creating, and reviewing PDFs where layout actually matters, rendering pages for visual checks rather than only extracting text. Reaches for `reportlab`, `pdfplumber`, and `pypdf` — so expect a Python environment. ## The rest of the catalog The `.curated` folder held 39 skills when we enumerated it on 16 August 2026. Most of the remainder are vendor-specific integrations rather than general-purpose tools, which is why they're not on the shortlist — they're excellent if you use the product and irrelevant otherwise: - **Figma** — the largest group, eight skills covering design generation, implementation, design systems, and Code Connect components - **Notion** — four skills for knowledge capture, meeting intelligence, research documentation, and spec-to-implementation - **Deploy targets** — `vercel-deploy`, `netlify-deploy`, `cloudflare-deploy`, `render-deploy` - **Other integrations** — `linear`, `sentry`, `chatgpt-apps`, `jupyter-notebook` - **Platform and language** — `aspnet-core`, `winui-app`, `cli-creator` - **Media** — `screenshot`, `speech`, `transcribe` - **Workflow** — `define-goal`, `openai-docs`, `yeet`, and `hatch-pet` ## Where Codex skills live on GitHub The short answer, as of 16 August 2026: - **[`openai/codex`](https://github.com/openai/codex)** — the agent itself, Apache-2.0. The bundled skills live here, under `codex-rs/skills/src/assets/samples`. This is the repo to cite for "what ships with Codex." - **[`openai/skills`](https://github.com/openai/skills)** — the curated catalog `$skill-installer` reads by default. **Its README now opens with a deprecation notice** pointing to `openai/plugins`. Last pushed 14 July 2026. There's no repository-level license; each skill carries its own `LICENSE.txt`, so check per skill before redistributing. - **[`openai/plugins`](https://github.com/openai/plugins)** — the stated successor, for skills distributed as plugins. This matters because most current "best Codex skills" articles still present `openai/skills` as the live, canonical source with no mention of the deprecation, and several recommend `create-plan` from the `.experimental` folder — which returns a 404. If you're following a roundup published before mid-2026, verify the repo state before trusting its install commands. For third-party skills, Codex will install from any GitHub repo — see [how to install Codex skills](/how-to-install-codex-skills/#install-from-any-github-repo). Because the format is the shared [Agent Skills standard](https://agentskills.io), many skills written for other agents work in Codex unchanged; the parts that don't travel are Codex's own `agents/openai.yaml` metadata. ## How we chose Weighted roughly in this order. **Provenance** — bundled skills first, then curated, since OpenAI has already made a publishing decision about both; a third-party skill would need to clear a materially higher bar to displace them. **Description quality** — we read every shortlisted skill's frontmatter, and a tightly scoped description with explicit negative triggers is the strongest available signal that a skill was built carefully. **Stated safety behavior** — approval gates, auth prechecks, and declared scope limits. **Breadth** — picks covering genuinely different jobs rather than several variations on one, which is why eight Figma skills produced no shortlist entry. What we deliberately did not do: rank by popularity. At least one competing roundup publishes per-skill "install counts"; there is no public telemetry for Codex skill installs, so those numbers come from some third party's own registry and shouldn't be read as ecosystem-wide fact. Another recommends `obra/superpowers` — a large, genuinely popular framework, but one built around Claude Code, which is worth knowing before you install it into Codex. ## Sources - [`openai/codex` — bundled sample skills](https://github.com/openai/codex/tree/main/codex-rs/skills/src/assets/samples) - [`openai/skills` — the `.curated` catalog](https://github.com/openai/skills) — every shortlisted skill's `SKILL.md` read directly; catalog enumerated via the GitHub API on 16 August 2026 - [`openai/plugins`](https://github.com/openai/plugins) — the stated successor repository - [Codex — Build skills (official docs)](https://developers.openai.com/codex/skills) --- ## Codex Skills vs AGENTS.md Both are markdown files that tell Codex how to work. They load at completely different times, and that's the whole decision. **The rule:** if Codex needs it on every task, it's AGENTS.md. If Codex needs it only when a specific job comes up, it's a skill. ## The short version | | AGENTS.md | Skill | |---|---|---| | Loads | Always, before work starts | Only when invoked or description-matched | | Costs | Full file, every session | A name and description until used | | Size limit | 32 KiB combined, all files | Index capped at 2% of context or 8,000 chars | | Holds | Facts and standing rules | A procedure, plus optional scripts and references | | Invoked | Never — it's just there | `$skill-name`, or automatically on description match | | Lives in | `AGENTS.md` at repo root and below | `.agents/skills//SKILL.md` | | Good for | Build commands, conventions, architecture notes | Release notes, threat models, PR triage, deploys | Worth noting: OpenAI documents both systems thoroughly and **never compares them**. The two docs pages don't reference each other, which is a large part of why this question keeps getting asked. ## Why context cost is the deciding factor AGENTS.md is unconditional. Codex reads the chain of files before it starts and they occupy context whether or not the current task needs them. The combined size is capped at **32 KiB** by default (`project_doc_max_bytes`), and Codex simply stops adding files once it hits that ceiling — so an oversized AGENTS.md doesn't just waste context, it can silently push out other files further down the chain. Skills are the opposite. Codex loads only each skill's name and description up front, then pulls the full body when it decides to use one. That index has its own cap — **2% of the context window or 8,000 characters**, whichever is smaller — but a skill's actual instructions cost nothing until they're needed. So the practical test isn't "is this important?" It's **"does Codex need this on every task, or only on some?"** Something needed every time earns its permanent slot. Something needed occasionally should not be taxing every unrelated request. ## Where each one lives The two systems have separate discovery chains, and mixing them up is a common source of "why isn't Codex reading this." **AGENTS.md** loads from: - `~/.codex/AGENTS.md` (or `AGENTS.override.md`) — global, applies everywhere - Then, from the git root down to your working directory, `AGENTS.override.md` then `AGENTS.md` in each directory Files are concatenated with blank lines between them, and **files closer to your working directory win**, because they land later in the combined prompt. That's what makes per-package overrides work: a rule in `services/payments/AGENTS.override.md` beats the repo-wide default when you're working in that directory. **Skills** load from `.agents/skills/` in every directory between the project root and your working directory, plus `~/.agents/skills` for personal ones — and, still, the deprecated `~/.codex/skills`. The [flagship guide](/codex-skills/#every-location-codex-scans) has the full table. Note the asymmetry in the global slot: AGENTS.md's global location is `~/.codex/AGENTS.md`, while the current global skills location is `~/.agents/skills`. Same tool, two different home directories, for historical reasons. ## Deciding, case by case | You want Codex to… | Put it in | |---|---| | Run `pnpm test` rather than guessing the test command | AGENTS.md | | Know the repo is a monorepo with packages under `apps/` | AGENTS.md | | Never commit directly to `main` | AGENTS.md | | Follow your code review checklist when you ask for a review | Skill | | Produce a threat model on request | Skill | | Draft release notes from merged PRs | Skill | | Use tabs, not spaces | AGENTS.md | | Deploy to staging, with a human approving first | Skill (with `allow_implicit_invocation: false`) | The pattern: AGENTS.md holds **facts and constraints** that are true regardless of the task. Skills hold **procedures** you invoke for a particular kind of work. ## The migration signal The clearest sign you've outgrown AGENTS.md is a section that has stopped being a fact and become a procedure — numbered steps, a checklist, "first do this, then that." That's a skill wearing the wrong clothes, and it's costing you context on every unrelated request. Moving it is straightforward: cut the section into `.agents/skills//SKILL.md`, write a `description` naming the situations it applies to, and leave a one-line pointer in AGENTS.md if the existence of the procedure is itself worth knowing. [How to create a Codex skill](/how-to-create-a-codex-skill/) covers writing the description so Codex triggers it at the right moment. It works the other way too. A skill that turns out to be relevant to *every* task was never really a skill — if Codex should always follow it, the description-matching layer is just overhead, and it belongs in AGENTS.md. ## They're complementary, not competing The two systems are designed to be used together, and the best setups do. AGENTS.md tells Codex what your project *is*: how to build it, what the conventions are, what's off-limits. Skills tell Codex how to perform specific jobs *within* that context. A skill that generates a migration doesn't need to restate your database conventions — AGENTS.md already did, and it's already loaded. One portability note if you work across agents: AGENTS.md is an increasingly cross-agent convention, and `SKILL.md` is a formal [open standard](https://agentskills.io) implemented by Claude Code, Hermes Agent, and others. Both travel reasonably well. Codex-specific pieces — `AGENTS.override.md`, the `agents/openai.yaml` metadata block — do not. ## Caveats - We have not run Codex. Everything here is documented behavior or verified in the `openai/codex` source. - The 32 KiB AGENTS.md cap and the 2%/8,000-character skills index cap are both defaults documented as of August 2026; `project_doc_max_bytes` is configurable. - The comparison itself is our editorial framing. OpenAI documents both systems but does not compare them, so the decision rules above are our reading of how the two behave, not an official recommendation. ## Sources - [Codex — AGENTS.md (official docs)](https://developers.openai.com/codex/guides/agents-md) — paths, override chain, and the 32 KiB limit - [Codex — Build skills (official docs)](https://developers.openai.com/codex/skills) — progressive disclosure and the skills index budget - [`openai/codex` — `codex-rs/ext/skills/src/host_roots.rs`](https://github.com/openai/codex/blob/main/codex-rs/ext/skills/src/host_roots.rs) — the skill discovery chain --- ## Codex Skills: The Practical Guide ## What Codex skills are **Codex** is OpenAI's coding agent — a CLI that also runs as IDE extensions and inside ChatGPT. A **skill** is a directory containing a `SKILL.md` file: YAML frontmatter telling Codex when to use it, plus markdown instructions to follow once it does. Codex implements the [Agent Skills open standard](https://agentskills.io), the same `SKILL.md` format used by Claude Code, Hermes Agent, Cursor and others. A well-formed skill written for one of those often works in Codex unchanged. What differs is everything *around* the file: where it lives, how it's invoked, and what metadata Codex understands. For the format on its own terms, see [SKILL.md](/skill-md/). The minimum viable skill is two frontmatter fields: ```yaml --- name: skill-name description: When this skill should and should not trigger. --- Skill instructions for ChatGPT or Codex to follow. ``` A full skill directory: ```text my-skill/ ├── SKILL.md # required ├── scripts/ # optional: executable code ├── references/ # optional: documentation ├── assets/ # optional: templates, resources └── agents/ └── openai.yaml # optional: Codex/ChatGPT UI + policy metadata ``` ## Where skills live, and why you'll see two different answers This is the part almost every guide to Codex skills gets wrong, so it's worth being precise. The official documentation lists the user-level skills directory as `$HOME/.agents/skills`. Most third-party writeups instead tell you to use `~/.codex/skills`. **Both directories really are scanned** — but they are not equivalent, and the Codex source says so directly. In [`codex-rs/ext/skills/src/host_roots.rs`](https://github.com/openai/codex/blob/main/codex-rs/ext/skills/src/host_roots.rs), the branch that assembles user-scope roots carries this comment: ```rust // Deprecated user skills location (`$CODEX_HOME/skills`), kept for backward // compatibility. ``` `$CODEX_HOME` defaults to `~/.codex` (overridable by the `CODEX_HOME` environment variable — confirmed in `codex-rs/core/src/config/mod.rs`). So `~/.codex/skills` is the **older** location, still scanned so existing setups keep working, while `~/.agents/skills` is the current one. The `.agents/` convention is deliberately cross-agent: Hermes Agent reads the same directory when you add it to its `external_dirs`. The wrinkle: **OpenAI's own bundled `skill-installer` still installs to the deprecated path.** Its `SKILL.md` states it "Installs into `$CODEX_HOME/skills/` (defaults to `~/.codex/skills`)." Nothing breaks — the deprecated root is still scanned — but it does mean an installed skill and a hand-written one can end up in different directories on the same machine. **Practical rule:** put skills you write by hand in `.agents/skills`. Expect `$skill-installer` to use `~/.codex/skills`. Check both when a skill doesn't appear. Both directories matter beyond Codex, and the two agents that care about them chose opposite policies. [Cursor reads `~/.codex/skills` and `.codex/skills` for compatibility](/cursor-skills/#where-cursor-looks-for-skills), so skills sitting in the deprecated location are picked up there anyway. [OpenClaw explicitly excludes it](/openclaw-skills/#codex-directories-are-deliberately-not-roots) and provides `openclaw migrate codex` instead. `.agents/skills` is the one both read natively, which is a further reason to prefer it. ### Every location Codex scans The documentation gives a simplified table. This is the full set, read from `resolve_skill_roots` in the source (results are de-duplicated by path): | Scope | Location | Notes | |---|---|---| | Repo | `/.agents/skills` for every directory from the project root down to your working directory | Not just three fixed levels — Codex probes the whole chain | | Repo | `/skills` | From the project config layer | | User | `$HOME/.agents/skills` | Current user-level location | | User | `$CODEX_HOME/skills` (`~/.codex/skills`) | Deprecated, kept for backward compatibility | | Admin | System config folder + `/skills` | Documented as `/etc/codex/skills` | | System | A cache root under `$CODEX_HOME` | Internal | | Plugin | Skill directories contributed by installed plugins | | Symlinks are followed when scanning, so you can keep a skills repo elsewhere and link it in. Two consequences worth knowing. Project root is determined by configurable *project root markers*, so the repo chain depends on how your project is detected. And when two skills share a name, **both appear in the selector without merging** — Codex has no precedence rule that silently picks a winner, which is a real difference from Claude Code's enterprise-over-personal-over-project chain. ## How Codex decides to use a skill Two paths, and the distinction matters when you're writing one: - **Explicit** — you invoke it. Type `$` in the Codex CLI or IDE to mention a skill, or `$skill-name` directly. In ChatGPT, it's `@` instead. - **Implicit** — Codex picks it. If your task matches the skill's `description`, Codex can load it without being asked. That makes `description` the single most important field in the file. The official guidance is to "explain exactly when this skill should and should not trigger," and the curated skills follow it closely — `security-threat-model`, for instance, spends half its description on *negative* triggers ("Do not trigger for general architecture summaries, code review, or non-security design work"). You can turn implicit invocation off per skill via `agents/openai.yaml`: ```yaml policy: allow_implicit_invocation: false ``` That's the setting to use for anything with side effects — deploys, publishes, anything you want a human to trigger deliberately. ### The context budget that shapes everything Codex loads only each skill's **name and description** up front, then pulls the full `SKILL.md` when it decides to use one. That index is capped: **2% of the context window, or 8,000 characters, whichever is smaller.** This is a real constraint, not trivia. Install enough skills and descriptions start competing for a fixed budget — which is why a vague, sprawling `description` is a functional problem and not just untidy writing. See [how to create a Codex skill](/how-to-create-a-codex-skill/) for how to write against it. ## The optional Codex-specific metadata `agents/openai.yaml` is where Codex and ChatGPT-specific presentation and policy live. It's entirely optional — a skill without it works fine — and it's the piece that doesn't travel to other agents: ```yaml interface: display_name: "User-facing name" short_description: "User-facing description" icon_small: "./assets/small-logo.svg" icon_large: "./assets/large-logo.png" brand_color: "#3B82F6" default_prompt: "Optional surrounding prompt" policy: allow_implicit_invocation: false dependencies: tools: - type: "mcp" value: "openaiDeveloperDocs" ``` That `dependencies.tools` block is how a skill declares it needs an MCP server — which is the cleanest way into the next question. ## Skills vs AGENTS.md vs MCP vs plugins vs prompts Five things that get conflated constantly. In Codex they do genuinely different jobs: | Concept | What it is | When it loads | |---|---|---| | **AGENTS.md** | Persistent project context — setup commands, conventions, standards | Always, before work starts | | **Skill** | A packaged procedure plus optional scripts and references | Only when invoked or description-matched | | **MCP server** | An external protocol connection that gives Codex new tools | Configured separately; a skill can declare one as a dependency | | **Plugin** | A distributable bundle that can carry skills, connectors and config together | When installed and enabled | | **Prompt** | What you type | Immediately, once | The distinction that actually costs people time is the first two. AGENTS.md is always in context and capped at **32 KiB** combined; skills cost only a name and description until they're needed. That asymmetry is the whole decision rule, and it's covered properly in [Codex skills vs AGENTS.md](/codex-skills-vs-agents-md/) — including the fact that OpenAI's own documentation never actually compares them. ## Turning a skill off Skills are enabled by default. To disable one without deleting it, add an entry to `~/.codex/config.toml`: ```toml [[skills.config]] path = "/path/to/skill/SKILL.md" enabled = false ``` Restart Codex after changing it. ## What ships with Codex Codex bundles a set of skills you don't install. As of the current `openai/codex` source, the bundled samples are `imagegen`, `openai-docs`, `plugin-creator`, `review-agent`, `skill-creator`, and `skill-installer`. Two of those are how you get everything else: `$skill-creator` writes new skills, `$skill-installer` fetches existing ones. Note that this list comes from the Codex repository itself, not from the separate catalog repo — which matters, because that catalog has since been deprecated. See [the best Codex skills](/best-codex-skills/) for what's actually in it and what the deprecation means. ## Common questions **Do I need to restart after adding a skill?** Yes, per the official docs ("Restart Codex after changes") and the bundled installer, which tells you an installed skill will be available "on their next turn." Some third-party guides claim restarts are no longer needed; that contradicts both first-party sources as of August 2026, so we're going with the sources. **Why doesn't my skill show up?** Most often it's in the wrong directory — check both `.agents/skills` and `~/.codex/skills`. Beyond that, confirm `SKILL.md` is named exactly that and has valid frontmatter. If neither is the problem, [agent skills not working](/agent-skills-not-working/) works through the rest, including a Codex bug where a symlinked `.agents/skills` silently loads nothing. **Can I keep skills in my repo?** Yes — `.agents/skills` at any level between your project root and working directory. That's the mechanism for committing skills alongside a codebase so the whole team gets them. ## Limitations and caveats - We have not run Codex or installed any skill. Everything here is either documented behavior or verified in the `openai/codex` source, and this page says which throughout. - The deprecation of `$CODEX_HOME/skills` is a comment in the source, not a formal announcement in OpenAI's prose documentation. We're quoting the code and attributing it as such. - Codex is moving fast — the skills documentation itself moved hosts recently (`developers.openai.com/codex/skills` now redirects to `learn.chatgpt.com`). Paths and behavior described here reflect the source and docs as of **August 2026**. ## Sources - [Codex — Build skills (official docs)](https://developers.openai.com/codex/skills) - [Codex — AGENTS.md (official docs)](https://developers.openai.com/codex/guides/agents-md) - [`openai/codex` — `codex-rs/ext/skills/src/host_roots.rs`](https://github.com/openai/codex/blob/main/codex-rs/ext/skills/src/host_roots.rs) — skill-root resolution and the deprecation comment - [`openai/codex` — bundled sample skills](https://github.com/openai/codex/tree/main/codex-rs/skills/src/assets/samples) - [agentskills.io — the open standard Codex implements](https://agentskills.io) --- ## How to Create a Codex Skill ## The smallest skill that works A Codex skill is a directory with a `SKILL.md` in it. Two frontmatter fields are required: ```yaml --- name: release-notes description: Draft release notes from merged PRs since the last tag. Use when the user asks for release notes, a changelog entry, or a summary of what shipped. --- Generate release notes for the current repository: 1. Find the most recent tag with `git describe --tags --abbrev=0`. 2. List merged PRs since that tag. 3. Group them into Added, Fixed, and Changed. 4. Write the result to `CHANGELOG.md` under a new heading. ``` Put it somewhere Codex scans. Personal, available everywhere: ```bash mkdir -p ~/.agents/skills/release-notes ``` Project-scoped, committed so the team gets it: ```bash mkdir -p .agents/skills/release-notes ``` Restart Codex, then invoke it with `$release-notes` — or just ask for release notes and let the description do its job. **Don't use `~/.codex/skills` for skills you write.** Codex still scans it, but its own source marks that path as deprecated and kept only for backward compatibility. Details in [where skills live](/codex-skills/#where-skills-live-and-why-youll-see-two-different-answers). ## Let Codex write it for you Codex bundles a `skill-creator` skill, so there's nothing to install: ```text $skill-creator ``` It asks what the workflow does and whether it needs scripts, then writes the files. In ChatGPT Work the same thing is `@skill-creator`. It's a reasonable way to get the scaffolding right the first time — though the `description` it produces is still worth editing yourself, for the reason below. ## Writing a description Codex actually triggers on This is the part that matters, and it's constrained by something most guides never mention. Codex loads only each skill's **name and description** into context up front, then pulls the full `SKILL.md` when it decides to use one. That index is capped at **2% of the context window or 8,000 characters, whichever is smaller**. Every skill you install competes for that budget. Two consequences: **Be specific about when it should fire.** The official guidance is to "explain exactly when this skill should and should not trigger." A description like `Helps with documentation` gives Codex nothing to match against and will either never fire or fire constantly. **Write the negative triggers too.** The best-written skill in OpenAI's own catalog spends roughly half its description on what should *not* activate it. `security-threat-model` reads: > Trigger only when the user explicitly asks to threat model a codebase or path, enumerate threats/abuse paths, or perform AppSec threat modeling. Do not trigger for general architecture summaries, code review, or non-security design work. That's the model to copy. Name the trigger phrases a user would actually type, then name the adjacent things that should not pull it in. **Beware name collisions.** If two installed skills share a name, Codex shows **both** in the selector without merging or picking a winner. There's no precedence rule to rely on, so give skills distinctive names. ## Adding supporting files `SKILL.md` is the only required file. The rest of the structure is optional and loads only when the instructions point at it: ```text my-skill/ ├── SKILL.md # required ├── scripts/ # executable code the skill can run ├── references/ # documentation loaded on demand ├── assets/ # templates, images, resources └── agents/ └── openai.yaml # optional Codex/ChatGPT metadata ``` Keep `SKILL.md` itself lean and push detail into `references/`. That's the whole point of the format — the body only enters context when the skill is actually used, and bulk that's rarely needed belongs one level down. If your skill ships scripts that reach the network, expect Codex to request escalated sandbox permissions when it runs them. OpenAI's own `skill-installer` documents exactly this behavior. ## Codex-specific metadata `agents/openai.yaml` is optional, Codex- and ChatGPT-specific, and does not travel to other agents: ```yaml interface: display_name: "Release Notes" short_description: "Draft release notes from merged PRs" icon_small: "./assets/small-logo.svg" icon_large: "./assets/large-logo.png" brand_color: "#3B82F6" default_prompt: "Optional surrounding prompt" policy: allow_implicit_invocation: false dependencies: tools: - type: "mcp" value: "openaiDeveloperDocs" ``` Two fields earn their keep: - **`policy.allow_implicit_invocation: false`** stops Codex triggering the skill on its own, leaving `$skill-name` as the only way in. Use it for anything with side effects — deploys, publishes, anything that writes to a system you'd want a human to have chosen deliberately. - **`dependencies.tools`** declares that the skill needs an MCP server, so the dependency is visible rather than surfacing as a confusing failure mid-run. ## Testing it There's no validation command in the docs, so the practical loop is: restart Codex, confirm the skill appears when you type `$`, then test both invocation paths separately. Invoke it explicitly with `$skill-name` to check the instructions work. Then start a fresh session and phrase a request the way a user actually would, without naming the skill, to check the description triggers it. Those are two different failures — instructions that don't work, and a description that doesn't match — and they need fixing in different places. If it doesn't appear at all, the cause is nearly always the directory or the frontmatter. See the [installation troubleshooting table](/how-to-install-codex-skills/#troubleshooting). ## Sharing it **Within a repo**, commit `.agents/skills//` and you're done. Codex scans that directory in every folder between the project root and the working directory, so a skill at the repo root applies throughout, and a package can carry its own. **Beyond a repo**, the picture changed recently. OpenAI's catalog repository, `openai/skills`, now opens its README with a deprecation notice pointing to [`openai/plugins`](https://github.com/openai/plugins), and directs anyone wanting to add skills to Codex toward the Build plugins guide and a **skill-only plugin**. That's the current intended distribution route, so a guide telling you to open a PR against `openai/skills` is out of date. Anyone can also install directly from any GitHub repository without a catalog at all — see [installing from a GitHub repo](/how-to-install-codex-skills/#install-from-any-github-repo). For a skill you want a handful of colleagues to use, publishing the repo and sharing the command is the lowest-friction option. Because the format is the shared [Agent Skills standard](https://agentskills.io), a skill written this way also works in Claude Code, Hermes Agent, and other compatible agents — with the exception of `agents/openai.yaml`, which only Codex and ChatGPT read. ## Caveats - We have not run Codex or created a skill through it. Everything here is documented behavior or verified in the `openai/codex` source, and this page distinguishes the two. - The docs describe no formal validation or linting command for skills as of August 2026; the testing loop above is a practical procedure, not an official one. - Codex is changing quickly and its documentation recently moved hosts. Check the [official skills docs](https://developers.openai.com/codex/skills) if you're reading this much later. ## Sources - [Codex — Build skills (official docs)](https://developers.openai.com/codex/skills) - [`openai/codex` — bundled `skill-creator` and `skill-installer`](https://github.com/openai/codex/tree/main/codex-rs/skills/src/assets/samples) - [`openai/skills` — `security-threat-model` SKILL.md](https://github.com/openai/skills) — quoted description; catalog read 16 August 2026 - [`openai/plugins`](https://github.com/openai/plugins) — the stated distribution route --- ## How to Install Codex Skills Codex has no `codex skills install` subcommand. Installing a skill means one of three things, and they don't all put the file in the same place — which is the single most common reason a freshly installed skill doesn't show up. ## The three ways to add a skill | Route | Use when | Lands in | |---|---|---| | `$skill-installer ` | Pulling from OpenAI's catalog | `~/.codex/skills/` | | `$skill-installer` with a repo path or URL | Pulling from any GitHub repository | `~/.codex/skills/` unless you pass `--dest` | | Writing the file yourself | Your own skills, or committing skills to a repo | Wherever you put it — use `.agents/skills` | All three are covered below. If a skill isn't appearing afterwards, jump to [which directory did it go in](#which-directory-did-it-go-in). ## Install from the curated catalog `skill-installer` is a skill that ships with Codex, so there's nothing to set up. Invoke it with no arguments to see what's available: ```text $skill-installer ``` Or install one directly by name: ```text $skill-installer gh-fix-ci ``` By default it reads OpenAI's curated catalog at `openai/skills`. **That repository is now deprecated** — its README opens by directing people to [`openai/plugins`](https://github.com/openai/plugins) instead. The repo is still public and the installer still points at it (observed 16 August 2026), so this works today; treat it as a path with a stated end-of-life rather than the long-term answer. [The best Codex skills](/best-codex-skills/) covers what's in the catalog and how the migration affects it. One thing to ignore: both the catalog's README and the bundled installer still describe installing from an `.experimental` folder. That folder now returns a 404. Commands referencing it will fail. ## Install from any GitHub repo The installer isn't limited to OpenAI's catalog. Give it a repo and a path, or a GitHub URL: ```text $skill-installer install the mcp-builder skill from ComposioHQ/awesome-codex-skills ``` Under the hood it runs a bundled Python helper you can also reason about directly. From the installer's own `SKILL.md`: ```text scripts/install-skill-from-github.py --repo / --path scripts/install-skill-from-github.py --url https://github.com///tree// ``` The documented options: | Flag | Effect | |---|---| | `--repo` / `--path` | Source repo and skill directory. `--path` is repeatable to install several at once | | `--url` | A GitHub tree URL instead of repo + path | | `--ref ` | Branch or tag. Defaults to `main` | | `--dest ` | Install somewhere other than the default destination | | `--method auto\|download\|git` | Force direct download or git sparse checkout | | `--name` | Override the installed skill's name (defaults to the path basename) | Behavior worth knowing before you run it: it defaults to direct download for public repos and **falls back to git sparse checkout if it hits an auth or permission error**. Private repos work through your existing git credentials, or a `GITHUB_TOKEN` / `GH_TOKEN`. It **aborts if the destination directory already exists** rather than overwriting — so reinstalling means removing the old copy first. Because these scripts reach the network, Codex will ask to escalate sandbox permissions when it runs them. ## Write the file yourself For your own skills, or for skills you want committed alongside a codebase, skip the installer. A skill is just a directory with a `SKILL.md` in it. Personal, available in every project: ```bash mkdir -p ~/.agents/skills/my-skill ``` Project-scoped, committed to the repo so your team gets it: ```bash mkdir -p .agents/skills/my-skill ``` Then write `SKILL.md` with at minimum a `name` and a `description`. [How to create a Codex skill](/how-to-create-a-codex-skill/) covers writing one that actually triggers. Codex scans `.agents/skills` in **every directory** between your project root and your working directory, so a skill committed at the repo root applies throughout the repo, and a package can carry its own. ## Which directory did it go in The two locations behave differently, and this trips people up constantly: - **`~/.agents/skills`** — the current user-level location, and what the official documentation lists. - **`~/.codex/skills`** — where `$skill-installer` writes. The Codex source marks this as the *deprecated* user skills location, "kept for backward compatibility." Both are scanned, so both work. But it means an installed skill and one you wrote by hand can sit in different directories on the same machine, and a guide that mentions only one of them will send you looking in the wrong place. The [flagship guide](/codex-skills/#where-skills-live-and-why-youll-see-two-different-answers) has the full scope table and the source reference. **After installing anything, restart Codex.** The official docs say to restart after changes, and the installer tells you a new skill will be available "on their next turn." Some third-party guides claim restarts are no longer necessary — that contradicts both first-party sources as of August 2026. ## Turning a skill off You don't have to delete a skill to stop it loading. Add an entry to `~/.codex/config.toml`: ```toml [[skills.config]] path = "/path/to/skill/SKILL.md" enabled = false ``` Restart Codex afterwards. ## Troubleshooting | Symptom | Likely cause | |---|---| | Installed skill doesn't appear | You didn't restart Codex, or you're looking in `.agents/skills` for something the installer put in `~/.codex/skills` | | Hand-written skill doesn't appear | Wrong filename (must be exactly `SKILL.md`), invalid YAML frontmatter, or a directory outside the scanned chain | | Install aborts immediately | The destination directory already exists — remove it or pass `--dest` | | Install fails on a private repo | Authenticate git, or set `GITHUB_TOKEN` / `GH_TOKEN` | | A command referencing `.experimental` fails | That folder was removed from the catalog repo; the docs referencing it are stale | | Skill loads but never triggers on its own | The `description` doesn't match how you phrase the task — see [creating a skill](/how-to-create-a-codex-skill/) | ## Sources - [Codex — Build skills (official docs)](https://developers.openai.com/codex/skills) - [`openai/codex` — bundled `skill-installer` SKILL.md](https://github.com/openai/codex/tree/main/codex-rs/skills/src/assets/samples) — destination, flags, and fallback behavior - [`openai/codex` — `codex-rs/ext/skills/src/host_roots.rs`](https://github.com/openai/codex/blob/main/codex-rs/ext/skills/src/host_roots.rs) — which directories are scanned - [`openai/skills`](https://github.com/openai/skills) — the catalog, and its deprecation notice --- ## The Best Cursor Skills Start with what you already have: **19 skills ship with Cursor**, and two of them (`/create-skill`, `/migrate-to-skills`) are how you get most of the rest. After that there are three real sources, in descending order of how much vetting stands behind them — Cursor's reviewed marketplace, well-known organisations publishing their own skills, and community collections. We haven't run Cursor or installed any of these. Every claim below is read from official documentation, from the repositories themselves, or from the GitHub API, and is dated where it will drift. ## The test to apply first Cursor skills split into two kinds, and mixing them up is the single most common failure in existing roundups. **Cursor-native skills** depend on things only Cursor has: parallel subagents, the built-in browser, worktree orchestration, Cursor's hooks, the `.cursor/rules/` format. `parallel-code-review`, which fans four read-only subagents across security, performance, correctness, and readability, is a genuinely excellent skill — and it does nothing useful in an agent without subagents. **Portable skills** are plain `SKILL.md` procedures that assume nothing beyond a competent agent with a shell. These work in Cursor, Claude Code, Codex, OpenClaw, and anything else implementing the standard. Before installing anything, read its `SKILL.md` and ask which kind it is. A roundup that recommends a large Claude-Code-oriented framework for Cursor without mentioning the provenance mismatch hasn't done that check for you. ## Source 1: the 19 already installed `/automate`, `/babysit`, `/canvas`, `/create-hook`, `/create-rule`, `/create-skill`, `/create-subagent`, `/cursor-blame`, `/loop`, `/migrate-to-skills`, `/review`, `/review-bugbot`, `/review-security`, `/sdk`, `/shell`, `/split-to-prs`, `/statusline`, `/update-cli-config`, `/update-cursor-settings`. Three worth knowing about specifically: - **`/create-skill`** — writes a new skill for you. The right starting point rather than hand-authoring frontmatter. - **`/migrate-to-skills`** — converts eligible rules and slash commands. If you've used Cursor for a while, this is likely the highest-value thing on the list, because it turns configuration you already wrote into skills without you deciding anything. See [Cursor skills vs rules](/cursor-skills-vs-rules/). - **`/review-security`** and **`/review-bugbot`** — review skills that ship in the box, which is worth knowing before you install a third-party code-review skill for the same job. Every listicle we found omits the built-ins entirely and recommends installing things that overlap with them. ## Source 2: the Cursor Marketplace [`cursor/plugins`](https://github.com/cursor/plugins) is the public repository behind [cursor.com/marketplace](https://cursor.com/marketplace) — MIT-licensed, 3,021 stars, last pushed 13 August 2026. Cursor states that all marketplace plugins undergo manual review before listing, which is a materially stronger provenance signal than anything else on this page. Two things to understand before browsing it. **Not every plugin contains skills.** Reading the manifests directly, the third-party integrations — Gmail, Google Drive, Google Calendar, Salesforce, HubSpot, Intercom, Docusign, X, Navan, Apollo.io, Ashby, Gong, Circleback, Profound — are predominantly MCP-only: a `plugin.json` and an `mcp.json`, no `skills/` directory at all. Gmail, which we read in full, is exactly that. Those are useful, but they're tool connections, not skills. **The first-party plugins are where the skills are.** From the repository's own plugin table, published by Cursor: | Plugin | What it's for | |---|---| | `cursor-team-kit` | Team workflows for CI, code review, shipping, local automation, verification | | `thermos` | Deep security and correctness branch audits with parallel subagents | | `agent-compatibility` | Repo compatibility scans; audits startup, validation, and docs against reality | | `create-plugin` | Scaffold and validate new agent plugins | | `cli-for-agent` | Patterns for designing CLIs that coding agents can run reliably | | `orchestrate` | Fan large tasks across parallel cloud agents with planners, workers, verifiers | | `continual-learning` | Incremental transcript-driven memory updates for `AGENTS.md` | | `pr-review-canvas`, `docs-canvas` | Render diffs and documentation as navigable canvases | | `cursor-sdk` | Building on the Cursor TypeScript SDK | Descriptions above are Cursor's own marketplace copy, quoted rather than assessed — we have not used these. `pstack` is the one community-authored plugin in that table (author listed as Lauren Tan); the rest are Cursor's. Several of these are firmly in the Cursor-native category: `thermos` and `orchestrate` are built around parallel subagents, and `continual-learning` is built around `AGENTS.md`. ## Source 3: organisations publishing their own skills Cross-agent repositories from named organisations, all readable and verifiable. Metadata below via the GitHub API on **16 August 2026**: | Repository | Focus | Stars | Licence | Last push | |---|---|---|---|---| | [`anthropics/skills`](https://github.com/anthropics/skills) | The reference skill set — document generation, skill authoring, design | 169,642 | See per-skill `LICENSE.txt` | 2026-08-13 | | [`trailofbits/skills`](https://github.com/trailofbits/skills) | Security research, vulnerability detection, audits | 6,612 | CC-BY-SA-4.0 | 2026-08-14 | | [`NVIDIA/skills`](https://github.com/NVIDIA/skills) | Physical AI, robotics, CUDA, RAG workflows | 2,967 | Apache-2.0 | 2026-08-14 | | [`awslabs/agent-plugins`](https://github.com/awslabs/agent-plugins) | Architecting, deploying, and operating on AWS | 862 | Apache-2.0 | 2026-08-14 | These are portable rather than Cursor-native, which is the point — they were written to the open standard and work here because of it. The star counts are observable GitHub signals, not usage data; there is no install telemetry for Cursor skills, so nobody can honestly rank these by adoption. ## Source 4: community collections [`spencerpauly/awesome-cursor-skills`](https://github.com/spencerpauly/awesome-cursor-skills) — CC0-1.0, 694 stars, last pushed 2 August 2026 — is the most substantial Cursor-specific collection we found, and unusually for an "awesome" list it organises by whether a skill is Cursor-native. Its Cursor-Native section is the interesting part, covering things that genuinely only work here: - `parallel-code-review` — four read-only subagents across security, performance, correctness, readability, merged into one report - `parallel-test-fixing` — one subagent per failing test, fixed independently - `best-of-n-solving` — several approaches attempted in parallel in isolated git worktrees - `visual-qa-testing`, `responsive-testing`, `dark-mode-testing`, `accessibility-auditing` — all built on Cursor's built-in browser and its accessibility tree - `suggesting-cursor-rules` and `suggesting-cursor-hooks` — notice a repeated correction, propose a `.cursor/rules/` file or a `.cursor/hooks.json` entry to encode it Descriptions are the repository's own. We have not run these skills, and a CC0 community list carries no review process — read the `SKILL.md` before installing, particularly anything that ships scripts. ## How to judge one yourself Cursor has no install-time security scanning. A skill dropped into `.cursor/skills/` is a file whose instructions the agent will follow, and any bundled script is code that may end up running. Outside the manually reviewed marketplace, the review is yours. Worth checking, in roughly this order: 1. **Does the `SKILL.md` say when *not* to trigger?** A description that only lists positive triggers will fire on adjacent tasks. 2. **Is it Cursor-native or portable?** Look for references to subagents, the browser, worktrees, hooks, `.cursor/` paths. 3. **Read `scripts/` in full.** This is the only part that executes. 4. **Does it declare what it needs?** Environment variables, CLIs, network access, named honestly. 5. **When was it last touched?** A skill referencing a fast-moving CLI and untouched for a year is a liability, not a bargain. 6. **Who published it, and under what licence?** A named organisation with a real licence file is a different proposition from an anonymous mega-registry claiming hundreds of skills. The same checklist, worked through in more detail for two other ecosystems, is on the [Claude Code](/claude-code-skills-github/) and [Hermes](/hermes-agent-skills-github/) pages — the reasoning transfers directly, because the risk model is the same wherever a skill is just a file the agent trusts. ## What we deliberately didn't do We didn't rank these. There is no install or usage telemetry for Cursor skills, star counts measure repository popularity rather than skill quality, and we haven't run any of them — so a numbered list would be presentation, not measurement. What's above is organised by provenance, which is the one thing that is actually observable and does actually predict how much scrutiny you still owe a skill before you install it. ## Caveats - We have not run Cursor or installed any skill listed here. Plugin and skill descriptions are quoted from their publishers. - Star counts, licences, and push dates are GitHub API snapshots from **16 August 2026** and will drift. - "Manually reviewed" is Cursor's own description of its marketplace process; the criteria are not published in detail and we have not audited it. - The built-in skill list is taken from Cursor's documentation as of August 2026 and may change between releases. ## Sources - [Cursor — Agent Skills (official docs)](https://cursor.com/docs/context/skills) — the built-in skill list - [Cursor — Plugins (official docs)](https://cursor.com/docs/plugins) — marketplace review - [`cursor/plugins` (GitHub)](https://github.com/cursor/plugins) — plugin table and manifests read directly - [`spencerpauly/awesome-cursor-skills` (GitHub)](https://github.com/spencerpauly/awesome-cursor-skills) — community collection, README read directly - Repository metadata (stars, licence, last push) pulled via the GitHub API, 16 August 2026 --- ## Cursor Skills vs Rules Cursor ships a built-in skill called `/migrate-to-skills`. To do its job it has to decide, mechanically, which of your existing rules are really skills in disguise. Those criteria are the best available answer to this question, and they're published. **The short version:** a rule that always applies, or that applies to specific file globs, stays a rule. A rule that the agent decides to apply based on its description was always a skill. A slash command becomes a skill that only you can invoke. ## What `/migrate-to-skills` actually converts Verbatim from Cursor's documentation: > **Dynamic rules**: Rules that use the "Apply Intelligently" configuration—rules with `alwaysApply: false` (or undefined) and no `globs` patterns defined. These are converted to standard skills. > **Slash commands**: Both user-level and workspace-level commands are converted to skills with `disable-model-invocation: true` Read as a decision table, that gives you this: | Your rule | Frontmatter | Converter's verdict | |---|---|---| | Always Apply | `alwaysApply: true` | Stays a rule | | Apply to Specific Files | `globs` set | Stays a rule | | Apply Intelligently | `alwaysApply: false`/unset, no `globs` | **Becomes a skill** | | Apply Manually | `@`-mentioned only | Stays a rule | | Slash command | — | **Becomes a skill**, model invocation off | The logic underneath is consistent: if something has a deterministic trigger — always, or these files, or you asked for it by name — a rule expresses it fine. The moment the trigger becomes *a judgement call about relevance*, you're describing a skill, and the skills system is built for that decision in a way the rules system isn't. That's the converter's behavior. The reading of it in that last paragraph is ours. ## The two systems, side by side | | Rule | Skill | |---|---|---| | Lives in | `.cursor/rules/*.mdc`, `AGENTS.md` | `.cursor/skills//SKILL.md` and [seven other directories](/cursor-skills/#where-cursor-looks-for-skills) | | Format | `.mdc` with frontmatter. "A plain `.md` file in `.cursor/rules` is ignored by the rules system because it has no frontmatter" | Markdown with YAML frontmatter | | Triggers | `alwaysApply: true`, `globs` match, description match, or `@`-mention | Description match, `paths` match, or `/` invocation | | Can bundle files | No | Yes — `scripts/`, `references/`, `assets/` | | Typical size | Cursor describes rules as "short coding guidelines and constraints" | Longer, procedural; the standard recommends keeping `SKILL.md` under 500 lines | | Precedence | Documented: Team Rules → Project Rules → User Rules | No skill precedence documented | | Portable to other agents | No | Yes — `SKILL.md` is [an open standard](https://agentskills.io) | Cursor's own summary is worth quoting because it's compact and correct: use rules for "short coding guidelines and constraints"; use skills for a "detailed, repeatable process." ## What Cursor does not document Two gaps matter, and both are being filled with guesswork elsewhere. **There is no documented precedence between a rule and a skill.** Cursor documents a precedence chain for rules against other rules — Team → Project → User. It documents nothing about what happens when an always-on rule and an active skill give contradictory instructions. A widely-shared blog post reports that rules won three times out of three in the author's own informal testing. That may well be what happens; it is one person's unreplicated result, not documented behavior, and we're not going to launder it into a fact by repeating it. If a conflict would be expensive for you, don't write one and hope. **There is no documented context budget for skills.** Cursor says only that "Skills load resources on demand, keeping context usage efficient." Codex and OpenClaw both publish numbers you can write against; Cursor doesn't. So the usual argument for moving things out of always-on rules — that you're reclaiming a measurable amount of context — is directionally sound here but unquantified. ## Where commands fit now Cursor's help documentation treats this as a three-way split: rules, skills, and commands. That's still how it reads in the UI, but the boundary has moved. `/migrate-to-skills` converts commands *into* skills with `disable-model-invocation: true`, which produces exactly what a command was: something only you can invoke, never the model. So the third category is now better understood as a **setting on a skill** than a separate system: ```yaml --- name: deploy-production description: Deploys the current branch to production. disable-model-invocation: true --- ``` That's a command. It appears under `/`, and the agent will never decide to run it on its own. Which is the behavior you want for anything with consequences. This is not a Cursor quirk, incidentally. Claude Code's documentation states that custom commands "have been merged into skills," and OpenClaw's Claude migration converts `.claude/commands/` files into skills with the same `disable-model-invocation: true` flag. Three ecosystems, independently, landed on the same answer: a command is a skill that doesn't invoke itself. ## Deciding, case by case | You want Cursor to… | Use | |---|---| | Always use tabs, never spaces | Rule (`alwaysApply: true`) | | Follow React conventions when editing `.tsx` files | Rule with `globs` | | Know the repo is a monorepo with packages under `apps/` | Rule, or `AGENTS.md` | | Run your release checklist when you ask for a release | Skill | | Review database migrations whenever it touches `db/migrations/**` | Skill with `paths` | | Produce a security threat model on request | Skill | | Deploy to production, only when you say so | Skill with `disable-model-invocation: true` | | Reuse the same procedure in Claude Code and Codex too | Skill — it's the only portable one | The pattern: rules carry **facts and constraints** that hold regardless of the task. Skills carry **procedures** invoked for a particular kind of work. Where the trigger is a file rather than a phrasing, `paths` on a skill and `globs` on a rule are both defensible — pick the rule if it's a short standing constraint, the skill if it's a procedure with steps. ## `paths` and `globs` are not the same mechanism Both take glob patterns and both scope by file. They do different jobs: - A rule's `globs` **injects the rule** when matching files are in play. The rule's content is short and lands directly in context. - A skill's `paths` **surfaces the skill for consideration** when the agent is reading or editing matching files. The skill's body still loads only if the agent decides to use it, and it can pull in bundled scripts and references afterwards. So `globs` is about inclusion; `paths` is about eligibility. If what you have is three lines of standing guidance, `globs` on a rule is simpler. If what you have is a procedure with steps and supporting files, `paths` on a skill is the one that scales. ## The migration, in practice If you have accumulated rules over a year of using Cursor, the quickest useful thing is to run `/migrate-to-skills` and read what it proposes rather than deciding from first principles. Its criteria are mechanical and its output is reviewable. The one judgement it can't make for you: a rule set to "Apply Intelligently" that turns out to be relevant to *everything* was never really a dynamic rule — it's an always-on constraint that was mislabelled, and it belongs in `alwaysApply: true` or `AGENTS.md`. Migration will convert it to a skill because that's what the frontmatter says. Reading the results is still your job. ## Caveats - We have not run Cursor, `/migrate-to-skills`, or any conflict test. The conversion criteria are quoted from Cursor's documentation; the reasoning built on top of them is our editorial interpretation and is marked as such. - The claim that rules override skills in conflicts is not documented by Cursor and is not repeated here as fact. - Rule types, frontmatter fields, and the Team → Project → User chain are documented behavior as of **August 2026**. ## Sources - [Cursor — Agent Skills (official docs)](https://cursor.com/docs/context/skills) — `/migrate-to-skills` conversion criteria, `paths`, `disable-model-invocation` - [Cursor — Rules (official docs)](https://cursor.com/docs/context/rules) — rule types, `.mdc` requirement, precedence chain - [Cursor — Skills (help centre)](https://cursor.com/help/customization/skills) — Cursor's own rules/skills/commands framing - [Cursor 2.4 changelog](https://cursor.com/changelog/2-4) — the release that introduced skills - [Claude Code — Skills (official docs)](https://code.claude.com/docs/en/skills) — the parallel commands-merged-into-skills change --- ## Cursor Skills: The Practical Guide ## What Cursor skills are **Cursor** is an AI code editor and coding agent. A **skill** is a directory containing a `SKILL.md` file: YAML frontmatter that tells Cursor when the skill is relevant, followed by markdown instructions to follow once it is. Cursor implements the [Agent Skills open standard](https://agentskills.io), the same `SKILL.md` format used by Claude Code, Codex, Hermes Agent, and OpenClaw. Support arrived in **Cursor 2.4, released 22 January 2026** — "Cursor now supports Agent Skills in the editor and CLI," per the release notes. The format itself is covered in [SKILL.md](/skill-md/). The minimum skill is two fields: ```yaml --- name: deploy-staging description: Deploys the app to the staging environment. Use when asked to ship, deploy, or push to staging. --- Step-by-step instructions for the agent to follow. ``` A full skill directory: ```text .cursor/skills/deploy-staging/ ├── SKILL.md # required ├── scripts/ # optional: executable code ├── references/ # optional: docs loaded on demand └── assets/ # optional: templates, images, data ``` ## Where Cursor looks for skills This is the part worth reading even if you know the rest. Cursor scans **eight** directories, and half of them are not Cursor's. | Scope | Directory | Notes | |---|---|---| | Project | `.agents/skills/` | Cross-agent convention, shared with Codex and OpenClaw | | Project | `.cursor/skills/` | Cursor's own project directory | | Personal | `~/.agents/skills/` | Cross-agent, user level | | Personal | `~/.cursor/skills/` | Cursor's own user directory | | Project | `.claude/skills/` | Compatibility — Claude Code's project directory | | Project | `.codex/skills/` | Compatibility — a Codex directory | | Personal | `~/.claude/skills/` | Compatibility — Claude Code's personal directory | | Personal | `~/.codex/skills/` | Compatibility — a Codex directory | The documentation is explicit about the second group: "For compatibility, Cursor also loads skills from Claude and Codex directories." The practical consequence is larger than it sounds. **If you already have skills in `~/.claude/skills/`, they are available in Cursor with no copying, no symlinks, and no conversion.** Every install guide for Cursor skills we found teaches `.cursor/skills/` and stops there, which means a lot of people are hand-copying files they never needed to move. See [how to install Cursor skills](/how-to-install-cursor-skills/) for what this does and doesn't cover, and [agent skills compatibility](/agent-skills-compatibility/) for how the other runtimes compare — Cursor is the most permissive of them by some distance. One wrinkle worth knowing if you also run Codex: the directory Cursor reads for compatibility is `~/.codex/skills`, which [Codex's own source marks as deprecated](/codex-skills/#where-skills-live-and-why-youll-see-two-different-answers) in favour of `~/.agents/skills`. Both are covered here, but by different routes — `~/.codex/skills` as a compatibility path, `~/.agents/skills` as one of Cursor's four native ones. ### Nested directories in a monorepo Skills don't have to sit at the repository root. From the docs: "A `.cursor/skills/` (or `.agents/skills/`) folder anywhere inside your repository is picked up, so monorepos can colocate skills with the package they apply to." So `apps/web/.cursor/skills/deploy/SKILL.md` works, and lives next to the code it describes. ## The frontmatter, including two fields that are Cursor's alone | Field | Required | What it does | |---|---|---| | `name` | Yes | "Lowercase letters, numbers, and hyphens only. Must match the parent folder name." | | `description` | Yes | "Describes what the skill does and when to use it. Used by the agent to determine relevance." | | `paths` | No | Glob patterns that scope the skill to matching files | | `disable-model-invocation` | No | When true, the skill is "only included when explicitly invoked via `/skill-name`" | | `metadata` | No | "Arbitrary key-value mapping for additional metadata" | | `globs` | No | Legacy. "Still accepted as a fallback for older skills, but new skills should use `paths`" | `name`, `description`, and `metadata` come straight from the portable [Agent Skills specification](https://agentskills.io/specification). `paths` and `disable-model-invocation` are Cursor's own additions, and they don't travel to other agents. ### `paths` is not the same thing as a rule's `globs` `paths` is the more interesting of the two, and the one most often confused with something else. From the docs: "Use the `paths` field to limit a skill to files that match one or more glob patterns. The skill is then only surfaced to the agent when it is reading or editing matching files." ```yaml --- name: migration-review description: Reviews database migrations for destructive operations and missing rollbacks. paths: "db/migrations/**/*.sql, prisma/migrations/**" --- ``` Every other skills system covered on this site matches a skill to the *phrasing of a request*. `paths` matches it to the *files being touched*. Those are genuinely different triggers, and for anything file-shaped — migrations, generated code, a config format with sharp edges — the second is far more reliable than hoping the description catches the right wording. Cursor rules have a `globs` field that looks superficially similar. It isn't the same mechanism on the same object — see [Cursor skills vs rules](/cursor-skills-vs-rules/). ## How Cursor decides to use a skill Two paths: - **Automatic.** "The agent is presented with available skills and decides when they are relevant based on context." This is why `description` carries most of the weight — it is the only thing the agent sees before deciding. - **Explicit.** Type `/` in Agent chat and search by name. Setting `disable-model-invocation: true` removes the automatic path and keeps the explicit one. That's the setting for anything with side effects you want triggered deliberately rather than inferred. ### On context cost Cursor says only that "Skills load resources on demand, keeping context usage efficient," and publishes no number. That is worth stating plainly, because two of the neighbouring ecosystems do publish one: Codex caps its skill index at [2% of the context window or 8,000 characters](/codex-skills/#the-context-budget-that-shapes-everything), whichever is smaller, and OpenClaw documents [roughly 97 characters per skill](/openclaw-skills/#what-skills-actually-cost) plus field lengths, with a configurable ceiling. Cursor gives you no equivalent budget to write against. We haven't measured one ourselves and won't invent one — but the general advice that follows from the other two systems still applies: a sprawling `description` is a functional cost, not just untidy writing. ## The 19 skills Cursor already ships Skills you don't install, available in every session: `/automate`, `/babysit`, `/canvas`, `/create-hook`, `/create-rule`, `/create-skill`, `/create-subagent`, `/cursor-blame`, `/loop`, `/migrate-to-skills`, `/review`, `/review-bugbot`, `/review-security`, `/sdk`, `/shell`, `/split-to-prs`, `/statusline`, `/update-cli-config`, `/update-cursor-settings`. Two of those are the ones to reach for first. `/create-skill` writes a new skill for you. `/migrate-to-skills` converts existing rules and slash commands — and its conversion criteria are the most precise answer anyone has published to "which of my rules should have been skills," which is why [the comparison page](/cursor-skills-vs-rules/) is built around them rather than around opinion. ## Skills, rules, commands, plugins, and MCP Five things Cursor supports that get conflated constantly: | Concept | What it is | When it loads | |---|---|---| | **Rule** | Short standing guidance in `.cursor/rules/*.mdc` or `AGENTS.md` | Always, on globs, on description match, or on `@`-mention — depending on rule type | | **Skill** | A packaged procedure plus optional scripts and references | On description match, on `paths` match, or on explicit `/` invocation | | **Command** | A user-defined slash command | When you type it. Now converted into skills by `/migrate-to-skills` | | **Plugin** | A distributable bundle that can carry rules, skills, agents, commands, hooks, and MCP servers | When installed and enabled | | **MCP server** | An external process or endpoint that gives Cursor new tools | Configured separately; a plugin can ship one alongside skills | The distinction that costs people the most time is the first two, covered in full [here](/cursor-skills-vs-rules/). The one people get wrong in a more interesting way is the last two: a plugin isn't an alternative to a skill, it's an envelope that skills and MCP servers travel in together. That packaging layer is now a published standard of its own — see [Agent Skills vs MCP](/agent-skills-vs-mcp/). ## Plugins: how skills get distributed A Cursor Plugin is a directory with a `.cursor-plugin/plugin.json` manifest: ```text my-plugin/ ├── .cursor-plugin/ │ └── plugin.json # only `name` is required ├── rules/ │ └── coding-standards.mdc ├── skills/ │ └── code-reviewer/ │ └── SKILL.md └── mcp.json ``` Skills inside a plugin follow the same `skills//SKILL.md` convention as everywhere else. Install from **Customize** in the sidebar, choosing project or user scope. Cursor also accepts the vendor-neutral form: per the docs, "Agent Plugins use a root `plugin.json` manifest and load in Cursor without modification." That's the [Agent Plugins](https://agent-plugins.org) standard, whose 1.0.0 specification lists Core Maintainers from Amazon, Cursor, Microsoft, OpenAI, and Vercel on its initial technical steering committee. Worth noting for anyone browsing the [official marketplace repository](https://github.com/cursor/plugins): plugins are not all skill packages. Reading the manifests directly, the third-party integrations there are predominantly MCP-only — the Gmail plugin is a `plugin.json` and an `mcp.json` with no `skills/` directory at all — while Cursor's own first-party plugins are the ones carrying skills. "Plugin" tells you how something is packaged, not what's inside it. ## Common questions **Do I need to restart Cursor after adding a skill?** The documentation doesn't state a reload requirement, and we haven't tested it. If a new skill doesn't appear, check the directory and the frontmatter first — `name` must match the parent folder name exactly, and the filename must be `SKILL.md` in that exact case. [Agent skills not working](/agent-skills-not-working/) covers the rest. **Which directory should I use?** `.cursor/skills/` for anything project-specific you want committed, `~/.cursor/skills/` for personal ones. Use `.agents/skills/` instead if you want the same file picked up by Codex or OpenClaw as well. **What happens if the same skill name exists in two directories?** Not documented, and we haven't tested it. Codex is explicit that duplicates both appear without merging, and Claude Code documents a precedence chain; Cursor says neither. Avoid the collision rather than relying on a guess. ## Limitations and caveats - We have not run Cursor or installed any skill. Everything here is either documented behavior or read directly from the `cursor/plugins` repository and the Agent Plugins specification, and this page says which throughout. - Cursor publishes no context budget for skills, no rules-vs-skills precedence, and no duplicate-name resolution rule. Where the docs are silent, this page says so rather than filling the gap. - Cursor's own documentation describes skills slightly differently in two places — the Agent Skills page describes automatic relevance-based selection plus explicit `/` invocation, while the customization help page frames skills as invoked on demand. The full picture needs both, plus `disable-model-invocation` and `paths`, which is how it's presented above. - Repository details (star counts, licences, push dates) are snapshots taken **16 August 2026** and will drift. ## Sources - [Cursor — Agent Skills (official docs)](https://cursor.com/docs/context/skills) — directories, frontmatter, built-in skills, migration criteria - [Cursor — Rules (official docs)](https://cursor.com/docs/context/rules) — rule types, `.mdc` frontmatter, precedence - [Cursor — Plugins (official docs)](https://cursor.com/docs/plugins) — plugin structure and the Agent Plugins pointer - [Cursor 2.4 changelog](https://cursor.com/changelog/2-4) — release date and editor/CLI support - [`cursor/plugins` (GitHub)](https://github.com/cursor/plugins) — manifests and schemas read directly - [Agent Plugins Specification](https://agent-plugins.org) — the portable plugin format - [agentskills.io — the open standard Cursor implements](https://agentskills.io) --- ## How to Install Cursor Skills Cursor doesn't have an install command the way Hermes Agent or OpenClaw do. Installing a skill means getting a `SKILL.md` file into one of the [eight directories Cursor scans](/cursor-skills/#where-cursor-looks-for-skills) — and there are five real ways to do that. ## The fastest one: you may already be done If you already use Claude Code or Codex and have skills in `~/.claude/skills/`, `.claude/skills/`, `~/.codex/skills/`, or `.codex/skills/`, **Cursor reads those directories directly.** Nothing to copy, no conversion, no extra step. Open Cursor and they're already there. This only works one direction automatically — Claude Code and Codex don't read Cursor's directories back. If you want a skill to go the other way, write it into `.agents/skills/` instead, which all three read natively (Cursor as one of its four native roots, Codex and OpenClaw as their current user/repo convention). ## 1. Write the file by hand For anything project-specific: ```bash mkdir -p .cursor/skills/deploy-staging ``` ```yaml # .cursor/skills/deploy-staging/SKILL.md --- name: deploy-staging description: Deploys the current branch to the staging environment. --- 1. Run the test suite. 2. Build the staging bundle. 3. Push to the staging deploy target. ``` For something personal, across every project: ```bash mkdir -p ~/.cursor/skills/deploy-staging ``` Use `.agents/skills/` or `~/.agents/skills/` instead of the `.cursor/` variants if you want Codex or OpenClaw to pick up the same file without a second copy. `name` must match the parent folder name exactly — that's a hard requirement, not a convention. ## 2. Import from GitHub Cursor can pull a skill straight from a repository. The flow is nested inside the Rules UI, which is easy to miss if you're specifically looking for a "skills" menu: 1. Open **Customize** in the sidebar 2. Go to **Rules** and click **Add Rule** 3. Select **Remote Rule (Github)** 4. Enter the GitHub repository URL This is the route for pulling in a single skill from a community repository without cloning it yourself. ## 3. `npx skills` — the cross-agent installer [`vercel-labs/skills`](https://github.com/vercel-labs/skills) (MIT, third-party — not a Cursor product) is a CLI for installing `SKILL.md` files across agents, Cursor included: ```bash npx skills add -a cursor ``` Useful specifically when you're pulling a skill from a repository that isn't organised the way Cursor expects, or when you want to install the same skill into several agents in one command by repeating `-a`. ## 4. The plugin marketplace Skills can also arrive bundled inside a **Cursor Plugin** — a package that can carry rules, skills, MCP servers, and more together. 1. Browse [cursor.com/marketplace](https://cursor.com/marketplace) or open **Customize** in the sidebar 2. Find the plugin you want 3. Select **Install**, and choose a project or user scope Marketplace plugins go through Cursor's own manual review before listing. That's meaningfully different from a raw GitHub import — see [the best Cursor skills](/best-cursor-skills/) for what that review does and doesn't tell you, and note that plenty of marketplace plugins ship MCP servers with no skills in them at all, so "it's in the marketplace" doesn't by itself mean "it's a skill." ## 5. Convert what you already have If the "skill" you want already exists as a Cursor rule or slash command, don't write it from scratch — run `/migrate-to-skills` and let Cursor convert it. See [Cursor skills vs rules](/cursor-skills-vs-rules/) for exactly which of your rules qualify. ## Which route for which situation | Situation | Use | |---|---| | A quick project-specific procedure | Hand-written file in `.cursor/skills/` | | Something personal, used everywhere | Hand-written file in `~/.cursor/skills/` | | Want it shared with Codex or OpenClaw too | `.agents/skills/` or `~/.agents/skills/` | | You already run Claude Code or Codex with skills | Nothing — check `~/.claude/skills/` and `~/.codex/skills/` first | | Pulling one skill from a GitHub repo | Remote Rule (GitHub) import | | Installing across several agents at once | `npx skills add -a cursor` | | Want the skill vetted before it lands | Cursor Marketplace | | An existing rule or command should have been a skill | `/migrate-to-skills` | ## Verifying it worked Type `/` in Agent chat and search for the skill's name. If it doesn't appear, check, in order: the directory is one of the eight Cursor actually scans, `name` in the frontmatter matches the folder name exactly, and the YAML frontmatter parses (a missing closing `---` is the most common failure). Cursor's documentation doesn't state whether a restart or reload is required after adding a file by hand, and we haven't tested it ourselves. ## Caveats - We have not run Cursor or performed any of these installs ourselves. Steps are taken directly from Cursor's documentation and, for `npx skills`, from the tool's own repository. - `npx skills` is a third-party tool (Vercel Labs, MIT-licensed), not a Cursor product — presented as such, not implied to be official. - Marketplace review criteria are not published in detail; "manually reviewed" is Cursor's own description of the process, not independently audited by us. ## Sources - [Cursor — Agent Skills (official docs)](https://cursor.com/docs/context/skills) — directories and the Remote Rule import flow - [Cursor — Plugins (official docs)](https://cursor.com/docs/plugins) — marketplace install flow and review - [`vercel-labs/skills` (GitHub)](https://github.com/vercel-labs/skills) — `npx skills` usage --- ## The Best Hermes Agent Skills Eight Hermes Agent skills are worth installing right now — what each one does well, and what to watch for before you add it. We haven't run these ourselves; every pick is verified against the actual `SKILL.md` files and repository history, not copied from another site's list. Full criteria are below the table, if you want them. ## The shortlist Eight skills survived verification well enough to recommend by name. Where a skill is already bundled or in the official-optional set, there's nothing to compare it against for that job — it's the default-trusted option. Where we recommend an external repository, we say exactly how confident that recommendation is and why. | Skill | Best for | Trust context | Install | |---|---|---|---| | `test-driven-development`, `systematic-debugging`, `plan` | Structured development discipline | Bundled (`builtin`) — installed by default | Already installed | | `subagent-driven-development` | Delegating implementation work to fresh subagents with two-stage review | Official-optional (`official`) | `hermes skills install official/software-development/subagent-driven-development` | | `obsidian` | Reading/writing an Obsidian vault | Bundled (`builtin`) — installed by default | Already installed | | `1password` | Managing secrets via the `op` CLI | Official-optional (`official`) | `hermes skills install official/security/1password` | | `duckduckgo-search` | Free web search with no API key | Official-optional (`official`) | `hermes skills install official/research/duckduckgo-search` | | `docker-management` | Docker containers, images, volumes, Compose | Official-optional (`official`) | `hermes skills install official/devops/docker-management` | | `composio-mcp` | Connecting to a broad range of external SaaS apps through one integration | External, vendor-authored (`community` by Hermes's install-time tier) | `hermes skills install ComposioHQ/composio-mcp-plugin/skills/composio-mcp` | | `manim-composer` (from `manim_skill`) | 3Blue1Brown-style math/technical animation | External, community (`community`) | `hermes skills install adithya-s-k/manim_skill/skills/manim-composer` | | `github-code-review` + `github-pr-workflow` | End-to-end GitHub PR workflow (branch → review → merge) | Bundled (`builtin`) — installed by default | Already installed | A note on that trust column: `official` here means it lives in the `optional-skills/` folder of the main [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) repo, which is a different claim from "written by Nous Research." Several of these (`1password`, `duckduckgo-search`, `docker-management`) are community-authored files that Nous Research folded into the official-trust tier — the `SKILL.md` frontmatter credits `arceus77-7`, `gamedevCloudy`, and `sprmn24` respectively as authors. That's still meaningfully more vetted than a random GitHub repo — Nous Research chose to ship it as part of the project — but it's not the same as an in-house build. We're distinguishing the two explicitly rather than letting "official" imply more than it does. ## Why each one, with the caveat that matters **Structured development discipline — `test-driven-development`, `systematic-debugging`, `plan`.** These three bundled skills (plus the official-optional `subagent-driven-development`) are Hermes's own adaptations of [obra/superpowers](https://github.com/obra/superpowers), a large, independently popular open-source agent-skills framework (MIT-licensed, actively pushed to as of this writing). The `SKILL.md` `author` fields say so directly: `"Hermes Agent (adapted from obra/superpowers)"`. That lineage is a genuinely useful signal — you're getting a widely-used external methodology that Nous Research thought was good enough to adapt and ship by default, at zero install cost. Caveat: like any process/discipline skill, its value depends on whether you actually follow the RED-GREEN-REFACTOR and root-cause-first workflow it enforces; it can't make you use it. **`subagent-driven-development` — best for delegating implementation.** Official-optional rather than bundled, so it needs an explicit install. It dispatches a fresh subagent per task with a two-stage (spec, then quality) review pass — useful once a plan from the `plan` skill is ready to execute. Same obra/superpowers lineage as above. **`obsidian` — best for vault-based note-taking.** Bundled, and its `SKILL.md` credits "Teknium (teknium1), Hermes Agent" as author — a name closely associated with Nous Research's Hermes model work, for what that provenance is worth; we're reporting the credit as written, not independently confirming his role. It handles reading, searching, creating, and appending to vault notes directly on the filesystem. Caveat: it's filesystem-first — it expects a resolvable vault path, not a synced/cloud-only vault. **`1password` — best official secrets integration.** Sets up the `op` CLI, signs in, and reads or injects secrets, gated behind a declared `OP_SERVICE_ACCOUNT_TOKEN` environment variable with a documented setup URL. This is the same skill the official docs themselves use as their canonical example of an official-tier install (`official/security/1password`), so it's about as well-attested as a recommendation on this page can get. **`duckduckgo-search` — best free fallback search.** No API key required. Its frontmatter literally sets `fallback_for_toolsets: [web]`, meaning it's designed to stay out of the way when a paid web-search toolset (Firecrawl) is configured, and step in automatically when it isn't — a concrete, verifiable instance of the conditional-activation mechanism described on [the flagship page](/hermes-agent-skills/#conditional-activation). Best pick if you don't want to configure a paid search provider at all. **`docker-management` — best for container workflows.** Manages containers, images, volumes, networks, and Compose stacks with the standard Docker CLI — no extra dependencies beyond Docker itself, and it declares `requires_toolsets: [terminal]` so it won't surface in an environment without one. **`composio-mcp` — best broad SaaS/app integration.** This is the one external, non-Hermes-specific pick on this list, so treat the confidence level differently from the rest. It's authored and maintained by ComposioHQ (Composio's own GitHub organization) in the [`composio-mcp-plugin`](https://github.com/ComposioHQ/composio-mcp-plugin) repository, MIT-licensed, and its `SKILL.md` describes routing to "1000+ apps" through Composio's own MCP server rather than a per-service skill for each integration. Read that app count as Composio's own description of their product, not something we verified independently. Real caveats: the repository has very few stars (single digits) and hadn't been pushed to in several weeks as of this writing — low visibility for a first-party integration, so watch it for staleness before depending on it, and it's a generic MCP-plugin skill rather than something built for Hermes specifically (it works because Hermes implements the same agentskills.io format, not because Composio targeted Hermes). **`manim-composer` (from `adithya-s-k/manim_skill`) — best for technical animation.** A dedicated, single-purpose repository (not a mega-registry) with genuine standalone traction — over a thousand GitHub stars, MIT-licensed. Same caveat as above: it's a generic skill package, not Hermes-specific, and it hadn't been pushed to in roughly seven months as of this writing, which is a real gap for anything depending on compatibility with a fast-moving Manim release. We're recommending it because it's the clearest standout we could independently verify for this specific, recurring need (3Blue1Brown-style math animation), not because it's actively maintained. **`github-code-review` + `github-pr-workflow` — best for GitHub PR workflow.** Both bundled, both `builtin` trust, and designed to work together (each lists the other under `related_skills`, alongside a shared `github-auth` skill). Covers diff review with inline comments through `gh` or the REST API, and the branch → commit → PR → CI → merge lifecycle. If your work lives on GitHub, this pairing is already installed and ready. ## What we deliberately left off We looked hard at a general-purpose PowerPoint/`.pptx` skill and at several "awesome-hermes-skills"-style registries, because they show up repeatedly in searches. We didn't shortlist a specific `.pptx` skill: the candidates we found were scattered across dozens of unrelated multi-skill registry repos with no single standout maintainer or traction, and we're not going to name one as "best" just to fill out a category. If you need `.pptx` generation, search GitHub directly and vet what you find with the [repository evaluation checklist](/hermes-agent-skills-github/#how-to-evaluate-a-skill-before-installing-it) — the demand for this capability is real, but the evidence doesn't support singling one repo out yet. ## How we decided what belongs here Five factors, applied roughly in this order of weight: **provenance** (bundled and official-optional skills get priority, since Nous Research has already chosen to ship them — external picks needed to clear a materially higher bar); **documentation quality** (does the `SKILL.md` actually explain what it does, needs, and how to invoke it — every skill above does); **maintenance signal** (commit/push recency and, where available, the skill's own `version` field — the only real observable signals; there's no download or usage telemetry for any of this); **install friction** (bundled and official-optional skills need zero or one command; the external picks need a full `owner/repo/path` install); and **breadth vs. specificity** (we tried to cover genuinely different jobs rather than eight overlapping options for the same task). For the long tail beyond this list — narrow, single-integration community skills for a specific niche SaaS product or personal workflow — there are real, actively-committed repositories, but no basis for calling any particular one "best" over another with similar scope: star counts are low and close together, READMEs vary widely, and there's no independent usage signal. If you're in that position, evaluate the specific candidates yourself against the [repository checklist](/hermes-agent-skills-github/#how-to-evaluate-a-skill-before-installing-it) rather than trust a ranked list — ours or anyone else's — that would be guessing at that scale. ## Sources - [NousResearch/hermes-agent — `optional-skills/` and `skills/` folders](https://github.com/NousResearch/hermes-agent) — direct inspection of the `SKILL.md` files cited above (`security/1password`, `research/duckduckgo-search`, `devops/docker-management`, `software-development/subagent-driven-development`, `note-taking/obsidian`, `software-development/test-driven-development`, `software-development/systematic-debugging`, `software-development/plan`, `github/github-code-review`, `github/github-pr-workflow`) - [obra/superpowers](https://github.com/obra/superpowers) — upstream framework credited in several bundled skills' `author` fields - [ComposioHQ/composio-mcp-plugin](https://github.com/ComposioHQ/composio-mcp-plugin) — `skills/composio-mcp/SKILL.md` - [adithya-s-k/manim_skill](https://github.com/adithya-s-k/manim_skill) — `skills/manim-composer/SKILL.md` - [Hermes Agent — Skills System (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - Repository metadata (stars, license, last-push date) pulled directly via the GitHub API, August 2026 --- ## Hermes Agent Skills on GitHub ## Start with the official repository The canonical source is [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) itself — MIT licensed. Bundled skills and the optional-but-official skill set both live inside this repo, under `optional-skills/` and `skills/`. These carry `builtin` or `official` trust automatically; nothing else on GitHub does. ## Real Hermes skill repositories on GitHub Here's what's actually out there for Hermes skills right now, described plainly rather than promotionally: | Repository | What it actually is | |---|---| | [`ChuckSRQ/awesome-hermes-skills`](https://github.com/ChuckSRQ/awesome-hermes-skills) | A curated collection spanning brainstorming, PRD workflows, debugging, Apple integrations, MLOps, and document processing. Positioned as curated rather than exhaustive. | | [`codesstar/hermes-skill-atlas`](https://github.com/codesstar/hermes-skill-atlas) | Describes itself as an "interactive map" claiming 70+ curated, verified skills. The "verified" claim is the repo's own, not an independent audit. | | [`itgoyo/hermes-skills`](https://github.com/itgoyo/hermes-skills) | Claims 310+ skills across many domains. At that scale, breadth is very likely coming at the cost of per-skill curation — treat this as a wide net to search, not a pre-vetted shortlist. | | [`aibuild-lab/skills-guard`](https://github.com/aibuild-lab/skills-guard) | Not a skill catalog — an MIT-licensed port of Hermes's own `skills_guard.py` scanner, useful as a standalone security/trust-matrix tool if you want to scan a skill outside of `hermes skills install`. | | [`cosmicstack-labs/mercury-agent-skills`](https://github.com/cosmicstack-labs/mercury-agent-skills) | A registry positioned as cross-compatible across Mercury Agent, OpenClaw, and Hermes — useful if you want a skill that works outside Hermes too, but cross-compatibility claims are worth checking against the actual `SKILL.md` files, not just the registry's README. | Beyond these, there's a long tail of narrow, single-purpose repositories — integrations for specific note-taking apps, self-hosted services, social platforms, and niche personal workflows. They're real and often well-built, but there are too many, too undifferentiated, and too fast-changing for any static list (including this one) to stay accurate. Search GitHub directly for `hermes agent skill ` and evaluate what comes back using the checklist below. GitHub is one distribution surface among several — [where to find agent skills](/where-to-find-agent-skills/) sets it alongside registries, marketplaces and vendor packs. ## How to evaluate a skill before installing it None of this replaces Hermes's own security scan on hub installs — it's what to check *in addition*, especially for anything at `community` trust tier (see [trust tiers](/hermes-agent-skills/#trust-tiers)). **1. Does `SKILL.md` match the actual spec?** It needs `name` and `description` at minimum. If the repo is missing a `SKILL.md` entirely, or has one that doesn't follow the [format Hermes expects](/hermes-agent-skills/#the-skillmd-format), it's not going to progressive-disclose correctly — at best it won't load, at worst it'll load as an oversized blob every time. **2. Is the `description` honest and specific?** An overly broad description is a real functional problem, not just bad style — it means the skill will get matched to tasks it shouldn't, competing with more relevant skills. Vague, marketing-style descriptions ("does everything you need!") are a signal of a low-quality skill even before you read the instructions. **3. What does it declare it needs?** Check `required_environment_variables` in the frontmatter and any setup instructions in the README. A skill that silently expects an API key without declaring it, or that expects tools/toolsets it doesn't list under `requires_tools`, will fail unpredictably instead of failing clearly. **4. What do the bundled scripts actually do?** If the skill ships a `scripts/` folder, read it — especially anything that shells out, writes files outside the skill directory, or reaches the network. This is exactly what Hermes's own scanner checks for (data exfiltration, prompt injection, destructive commands), but a scanner is a floor, not a substitute for reading code you're about to let an agent execute with your credentials. **5. How recently was it actually touched?** Last commit date and commit frequency are the only real proxies available for "is this maintained." Star count tells you about visibility, not upkeep — a skill with many stars and no commits in months is a different risk profile from one with fewer stars and active maintenance. **6. Does it match its own claims?** If a repo claims a specific skill count ("70+", "310+"), spot-check a handful rather than trusting the number — repo-level claims about a skill collection are the repo's own marketing, not a verified fact, and we're treating them the same way in this guide: attributed, not restated as fact. **7. License.** Check it has one, and that it's compatible with how you intend to use the skill (personal use vs. redistributing inside a team fork, for instance). ## Installing what you find Once you've picked a repo, install directly by path: ```bash hermes skills install // ``` or subscribe to it as an ongoing source: ```bash hermes skills tap add / ``` Full command reference: [how to install Hermes Agent skills](/how-to-install-hermes-agent-skills/). ## Sources - [NousResearch/hermes-agent (GitHub)](https://github.com/NousResearch/hermes-agent) - [Hermes Agent — Skills System (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - Live GitHub repository search conducted August 2026 for Hermes-skill-related repositories --- ## Hermes Agent Skills: The Practical Guide ## What Hermes Agent skills are **Hermes Agent** is an open-source, model-agnostic personal AI agent built by [Nous Research](https://github.com/NousResearch/hermes-agent). It runs as a CLI, a desktop app, a messaging gateway (Telegram, Discord, Slack, WhatsApp), and an IDE integration. A **skill** is a folder containing a `SKILL.md` file plus optional supporting files (scripts, references, templates, examples, assets). `SKILL.md` tells the agent what a capability does, when to use it, and how — in effect, an on-demand instruction document the agent loads only when it's relevant, rather than stuffing every capability into the system prompt. Hermes implements this using the **[agentskills.io](https://agentskills.io) open standard**, which originated at Anthropic and is now used by a long list of agent products (Claude Code, Cursor, VS Code, Gemini CLI, OpenClaw, and others). That matters practically: a well-formed skill written for one compatible agent is often usable, with little or no change, in another — see [SKILL.md, the format itself](/skill-md/) for the portable field set. ## Where skills live All skills resolve from `~/.hermes/skills/`, organized by category: ```text ~/.hermes/skills/ ├── category/ │ ├── skill-name/ │ │ ├── SKILL.md # required │ │ ├── references/ │ │ ├── templates/ │ │ ├── scripts/ │ │ ├── examples/ │ │ └── assets/ └── .hub/ ``` You can add additional search locations — useful for a team-shared skills repo, or a project-local set of skills checked out alongside a codebase — via `external_dirs` in `config.yaml`: ```yaml skills: external_dirs: - ~/.agents/skills - ${SKILLS_REPO}/skills ``` ## The SKILL.md format The required frontmatter, per the official docs: ```yaml --- name: my-skill description: Brief description (≤60 chars) version: 1.0.0 platforms: [macos, linux] # optional metadata: hermes: tags: [python, automation] category: devops fallback_for_toolsets: [web] # optional requires_toolsets: [terminal] # optional config: - key: my.setting description: "What this controls" default: "value" --- ``` The `name` and `description` fields are the only ones required by the base agentskills.io spec; everything under `metadata.hermes` is Hermes-specific extension data used for conditional loading and configuration (covered below). ## How skills are discovered and loaded Hermes scans its skill directories at startup and loads every valid `SKILL.md` it finds — but it doesn't load full skill *content* up front. It uses **progressive disclosure**, in three levels, to keep token usage low even with a large skill library installed: | Level | Call | What loads | Approximate cost | |---|---|---|---| | 0 | `skills_list()` | Name + description metadata for every skill | ~3k tokens for the full library | | 1 | `skill_view(name)` | The full `SKILL.md` body for one skill | Only when the task matches | | 2 | `skill_view(name, path)` | A specific reference/template/script file inside the skill | Only when the instructions point there | This is the general agentskills.io model (discovery → activation → execution), and it's why a Hermes install with hundreds of skills doesn't meaningfully bloat every conversation — most of that library sits at level 0 until it's actually relevant. ## Installing skills: the eight hub sources Hermes doesn't have one skill registry — it federates across **eight source types**, all reachable through `hermes skills browse` / `hermes skills search` / `hermes skills install`: | Source | What it is | Example | |---|---|---| | `official` | Bundled-optional skills shipped in the Hermes repo | `official/security/1password` | | `skills-sh` | Vercel's public skills directory | — | | `well-known` | Any site publishing a `/.well-known/skills/index.json` endpoint | — | | `github` | Direct install from a GitHub repo path | `openai/skills/k8s` | | `clawhub` | Third-party skill marketplace | — | | `lobehub` | Skills converted from the LobeHub agent catalog | — | | `browse-sh` | Browserbase's site-automation skill set | — | | `url` | A direct HTTPS link to a `SKILL.md` file | — | For the full command reference and copy-pasteable examples, see [how to install Hermes Agent skills](/how-to-install-hermes-agent-skills/). ## Trust tiers Every skill Hermes can install carries a trust level, and hub installs are scanned before they land on disk: | Tier | Meaning | |---|---| | `builtin` | Ships with Hermes itself — always trusted | | `official` | Lives in the `optional-skills/` folder of the main repo — built-in trust | | `trusted` | From a known registry (OpenAI, Anthropic, Hugging Face, NVIDIA, etc.) | | `community` | Everything else. Findings that aren't flagged as dangerous can be overridden with `--force`; dangerous findings cannot. | All hub installs are scanned for data exfiltration, prompt injection, and destructive commands before install completes. This scanning and trust-tier logic is documented behavior from the official docs — we haven't independently audited the scanner's detection accuracy, and you shouldn't treat "scanned" as a substitute for reading a `community`-tier skill's `SKILL.md` and scripts yourself before installing. See [evaluating skills on GitHub](/hermes-agent-skills-github/) for what to actually check. ## What kinds of skills exist Skills aren't one thing — they differ by where they come from and what they do: - **Bundled skills** — ship with Hermes by default (`builtin` trust), covering common tasks out of the box. - **Optional official skills** — maintained in the `optional-skills/` folder of the main repo but not installed by default; add them with `hermes skills install official/...`. - **Hub/community skills** — installed from any of the eight sources above, spanning everything from document generation (PowerPoint, presentation creation) to SaaS integrations (Composio's connector skill for Gmail, Sheets, Slack, CRMs) to development workflow discipline (structured brainstorming, TDD, systematic debugging). - **Knowledge-base skills** — created via `/learn` from a large source (a book, a docs site, a whole SDK). These get a lean `SKILL.md` carrying the core mental model, with the bulk of the material indexed under `references/` and loaded chapter-by-chapter via level-2 `skill_view` calls, so token cost stays proportional to what's actually asked. - **Agent-authored skills** — created or edited by Hermes itself through its learning loop (next section), not installed from anywhere. ## Skills vs. tools vs. plugins vs. MCP, in Hermes specifically These four terms get conflated constantly in third-party writeups. In Hermes they're distinct: | Concept | What it is | How it's invoked | |---|---|---| | **Tool** | A built-in capability (terminal, browser, `execute_code`, etc.) exposed to the model directly | Called by the model as part of normal reasoning | | **Skill** | A `SKILL.md` document plus optional bundled files that teaches the agent *how* to do something, often by directing it to use existing tools in a specific way | Loaded via progressive disclosure, invoked explicitly with `/skill-name` or matched automatically to a task | | **Plugin** | A packaged extension that can add new tools, commands, or integrations to Hermes itself | Installed and configured separately from the skills system | | **MCP (Model Context Protocol)** | An external protocol for connecting an agent to third-party tool servers | Skills can *use* MCP-provided tools, but a skill and an MCP server are different layers — the skill is the instructions, the MCP server is the capability being called | The practical distinction: a skill rarely adds new low-level capability by itself. It packages judgment and process — when to use which tool, in what order, with what caveats — around capabilities the agent (via tools, plugins, or MCP) already has. ## Conditional activation Skills can hide or surface themselves depending on what's available in the current environment: ```yaml metadata: hermes: requires_toolsets: [terminal] # only show when terminal is available fallback_for_toolsets: [web] # only show when web toolset is unavailable requires_tools: [terminal] # check for a specific tool fallback_for_tools: [web_search] ``` The documented example: a DuckDuckGo search skill stays hidden while Firecrawl's web toolset is active, and only surfaces as a fallback if that toolset isn't available. This keeps overlapping skills from competing for the same job — the agent only sees the one relevant option for the current setup. ## Skill bundles: stacking multiple skills under one command A **bundle** groups several skills under a single slash command, stored as YAML at `~/.hermes/skill-bundles/.yaml`: ```yaml name: backend-dev description: Backend feature work skills: - github-code-review - test-driven-development - github-pr-workflow instruction: | Always start by writing failing tests first. ``` Invoke it with `/backend-dev refactor the auth middleware`, and all three skills load together with the extra instruction applied. You can also stack skills ad hoc without a bundle file, up to five at once: `/skill1 /skill2 /skill3 instruction`. `/bundles` lists what's available. ## The learning loop: skills that write themselves This is the feature that most distinguishes Hermes from a typical skills-compatible agent, and it's the part most third-party "best skills" roundups skip entirely. **Creating skills from experience.** `/learn ` turns a local source or a documentation URL into a new skill. Re-running `/learn` against updated material folds the new content into the existing skill instead of duplicating it. **Self-editing via `skill_manage`.** Hermes has a dedicated tool for modifying its own skill library: | Action | Purpose | |---|---| | `create` | New skill from scratch | | `patch` | Targeted fix (preferred — smaller diff, cheaper) | | `edit` | Larger rewrite | | `delete` | Remove a skill entirely | | `write_file` / `remove_file` | Manage a skill's supporting files | **Approval gating.** By default this can happen autonomously; you can require a human check first: ```yaml skills: write_approval: true ``` With that set, proposed changes land as staged writes under `~/.hermes/pending/skills/` instead of applying immediately: ```bash /skills pending # list staged writes /skills diff # view the full diff /skills approve # apply it /skills reject # drop it ``` Hermes isn't alone in this. OpenClaw solves the same problem with [Skill Workshop](/openclaw-skills/#skill-workshop-agent-drafted-skills-reviewed-first), a proposal queue the agent writes into instead of writing to `SKILL.md` directly — the same instinct, arrived at independently, and the only two review gates of this kind among the ecosystems covered here. **Editorial note:** we have not run Hermes ourselves and can't independently characterize how reliable agent-authored skills are in practice, or how often `write_approval: true` catches something worth catching. This section describes documented mechanics, not tested outcomes. If you're running Hermes on anything you care about, turning on `write_approval` before you trust it with unattended self-editing seems like the obviously conservative default — but that's our inference, not a benchmark result. ## Bundled-skill update protection On install, Hermes records a content hash for every bundled skill at `~/.hermes/skills/.bundled_manifest`. On update: - If you haven't touched a bundled skill, upstream changes apply cleanly. - If you *have* modified it, your version is preserved permanently and skipped in future syncs — no silent overwrite of local edits. You can also opt a fresh install out of bundled-skill seeding entirely: ```bash hermes skills opt-out # stop future seeding, keep what's installed hermes skills opt-out --remove # also delete unmodified bundled skills hermes skills opt-in --sync # re-enable and re-seed ``` ## Common setup questions **Do I need to restart Hermes after adding a skill manually?** Skills are scanned at startup; a skill dropped into `~/.hermes/skills/` needs a restart (or the equivalent reload path in your interface) to be picked up as far as the documented behavior goes — we did not verify whether the CLI hot-reloads mid-session. **Can two skills fight over the same task?** This is what `requires_toolsets` / `fallback_for_toolsets` exist to prevent — see [Conditional activation](#conditional-activation) above. Beyond that, the docs don't specify explicit conflict-resolution rules between two unrelated skills with overlapping descriptions, so overly broad `description` fields are worth avoiding when writing your own. **Where should I start looking for skills?** See [the best Hermes Agent skills](/best-hermes-agent-skills/) for a short list of the ones actually worth installing, and [Hermes Agent skills on GitHub](/hermes-agent-skills-github/) for how to evaluate a repository yourself. [Where to find agent skills](/where-to-find-agent-skills/) covers the wider set of registries and packs, and what their download counts actually measure. ## Limitations and caveats - Skill "popularity" has no public telemetry attached to it — the only observable signals for a community skill are GitHub stars, forks, and commit recency. Any ranking based on more than that is guessing. - Security scanning on hub installs is Hermes's own automated check, not a manual audit. Treat `community`-tier skills as unaudited by default. - The exact override semantics of `--force` on scan findings, and the full behavior of `write_approval`, are documented in one place (the official docs) and we have not cross-verified them against a second independent source or our own testing. - This page describes the system as documented at the official docs site and corroborated against source files in the `NousResearch/hermes-agent` GitHub repository as of August 2026. Hermes is under active development; check the [official skills docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) if you're reading this much later. ## Sources - [Hermes Agent — Skills System (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [NousResearch/hermes-agent (GitHub)](https://github.com/NousResearch/hermes-agent) - [agentskills.io — the open standard Hermes implements](https://agentskills.io) --- ## How to Install Hermes Agent Skills ## 1. Install Hermes Agent first Skills require Hermes Agent to be installed — there's no standalone skills installer. Pick your platform: **Linux, macOS, WSL2, or Android (Termux):** ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` **Native Windows (PowerShell):** ```powershell iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` **macOS/Windows desktop app:** download the installer from [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com/) and run it directly. ### Prerequisites - **Git** is required on every platform. - **Linux** also needs `curl` and `xz-utils` (the installer fetches Node.js as a `.tar.xz` archive). - The **desktop app** additionally needs a C++ toolchain (`g++` / `build-essential` on Debian-based distros). You do not need to install Python, Node.js, `uv`, `ripgrep`, or `ffmpeg` yourself — the installer detects what's missing and installs it. ### After installing ```bash source ~/.bashrc # or ~/.zshrc — reload your shell so `hermes` is on PATH hermes doctor # verify the install ``` Then configure the basics: ```bash hermes model # pick an LLM provider hermes tools # enable/disable tools hermes gateway setup # wire up Telegram/Discord/Slack/WhatsApp, if wanted hermes setup --portal # quick setup via the Nous Portal (recommended default path) ``` ### Where things land | | Per-user install | Root-mode install | |---|---|---| | Code | `~/.hermes/hermes-agent/` | `/usr/local/lib/hermes-agent/` | | Binary | `~/.local/bin/hermes` | `/usr/local/bin/hermes` | | Config | `~/.hermes/` | `/root/.hermes/` or `$HERMES_HOME` | ## 2. Browse and search for skills Once Hermes is running, skills come from eight federated sources (official bundle, Vercel's skills-sh directory, `.well-known` endpoints, direct GitHub paths, ClawHub, LobeHub, Browserbase's browse-sh, and direct URLs — see [the skills guide](/hermes-agent-skills/#installing-skills-the-eight-hub-sources) for what each one is). ```bash hermes skills browse # browse what's available across sources hermes skills search kubernetes # search all sources for a keyword ``` ## 3. Install a skill ```bash hermes skills install openai/skills/k8s ``` This runs a security scan (checking for data exfiltration, prompt injection, and destructive commands) before the skill lands on disk. If the scan flags something non-dangerous on a `community`-tier skill, you can override it: ```bash hermes skills install some-org/some-skill --force ``` Dangerous findings cannot be forced through. We have not independently tested what the scanner catches or misses — treat this as a floor, not a substitute for reading the skill's `SKILL.md` and any bundled scripts yourself, especially for `community`-tier installs. See [evaluating skill repositories](/hermes-agent-skills-github/) for what to check by hand. ### Subscribing to a custom source If your team or a project maintains its own skills repo, register it as a "tap" so its skills show up in browse/search/install: ```bash hermes skills tap add myorg/skills-repo ``` ## 4. List and manage what's installed ```bash hermes skills list --source hub # list installed hub skills hermes skills check # check for upstream updates hermes skills update # reinstall skills that have updates ``` ### Resetting a skill ```bash hermes skills reset google-workspace # clear the manifest entry hermes skills reset google-workspace --restore # restore the bundled version ``` ## 5. Using external and project-local skill directories To load skills from somewhere other than `~/.hermes/skills/` — a shared team repo, or a skills folder checked into a project — add it under `external_dirs` in `config.yaml`: ```yaml skills: external_dirs: - ~/.agents/skills - ${SKILLS_REPO}/skills ``` ## 6. Bundled skills: keeping local edits safe across updates Hermes hashes every bundled skill on install (`~/.hermes/skills/.bundled_manifest`). If you've edited a bundled skill yourself, it's preserved permanently and skipped during future syncs rather than silently overwritten. If you'd rather not have Hermes seed its default skill set at all: ```bash hermes skills opt-out # stop future seeding, keep current installs hermes skills opt-out --remove # also remove unmodified bundled skills hermes skills opt-in --sync # turn seeding back on and re-sync ``` ## 7. Requiring approval before Hermes edits its own skills Hermes can create and modify skills autonomously through its learning loop (see [the flagship guide](/hermes-agent-skills/#the-learning-loop-skills-that-write-themselves)). To require a manual check first: ```yaml skills: write_approval: true ``` With that set, proposed changes queue under `~/.hermes/pending/skills/`: ```bash /skills pending # list staged writes /skills diff # view the diff /skills approve # apply it /skills reject # discard it ``` ## Troubleshooting | Symptom | Fix | |---|---| | `hermes: command not found` after install | Reload your shell (`source ~/.bashrc` / `~/.zshrc`), or confirm `~/.local/bin` is on `PATH` | | API key / provider error | Run `hermes model` again, or set the key directly with `hermes config set` | | Config seems broken after an update | `hermes config check`, then `hermes config migrate` | | A skill install is silently blocked | It likely tripped the security scanner on a dangerous finding — those can't be forced through with `--force`; read the skill source before trying an alternative | ## Sources - [Hermes Agent — Installation (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/installation) - [Hermes Agent — Skills System (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [`hermes_cli/skills_hub.py` and `website/docs/reference/cli-commands.md`, NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) — used to confirm the CLI subcommands above exist in the actual source, not just marketing copy --- ## The Best OpenClaw Skills The best OpenClaw skills are, for most people, the ones already on disk. **51 skill directories ship in the OpenClaw repository**, covering notes, media, dev tooling, home automation, messaging, and MCP — and unlike anything on ClawHub, they need no vetting decision from you. We haven't run OpenClaw or installed any skill. The list below is read directly from the `openclaw/openclaw` repository on **16 August 2026**; everything else on this page is documented behavior, quoted where the wording matters. ## What ships in the box From the repository's `skills/` directory: | Category | Skills | |---|---| | **Notes & tasks** | `apple-notes`, `apple-reminders`, `bear-notes`, `notion`, `obsidian`, `things-mac`, `taskflow`, `taskflow-inbox-triage`, `trello` | | **Development** | `coding-agent`, `github`, `gh-issues`, `node-inspect-debugger`, `python-debugpy`, `tmux`, `session-logs`, `spike` | | **Skills & registry** | `skill-creator`, `clawhub` | | **MCP** | `mcporter` | | **Media & images** | `camsnap`, `gifgrep`, `meme-maker`, `diagram-maker`, `nano-pdf`, `video-frames`, `songsee` | | **Audio & speech** | `openai-whisper`, `openai-whisper-api`, `sherpa-onnx-tts`, `spotify-player`, `sonoscli` | | **Security & secrets** | `1password` | | **Home & devices** | `openhue`, `blucli`, `peekaboo`, `node-connect` | | **Web & search** | `gemini`, `oracle`, `sag`, `xurl`, `blogwatcher`, `summarize`, `goplaces`, `weather` | | **Mail & ops** | `himalaya`, `healthcheck`, `model-usage`, `eightctl`, `gog`, `ordercli` | Four worth knowing about by name: - **`skill-creator`** — authors and reviews `SKILL.md` files. Its own description reads "Author or review AgentSkills: create, repair, validate, or restructure SKILL.md files and bundled resources," and it's the right starting point for [writing your own](/how-to-create-an-openclaw-skill/) rather than hand-rolling frontmatter. - **`clawhub`** — searching, installing, verifying, updating, and publishing skills from inside a conversation. Its `SKILL.md` instructs the agent to "Search before claiming that a requested capability is unavailable" and to verify and get user approval before installing anything. - **`mcporter`** — "List, configure, authenticate, call, and inspect MCP servers/tools with mcporter over HTTP or stdio." A skill whose whole job is driving MCP servers; see [Agent Skills vs MCP](/agent-skills-vs-mcp/). - **`coding-agent`** — the one bundled skill that's opt-in. It needs `skills.entries.coding-agent.enabled: true` plus one of `claude`, `codex`, `opencode`, or another supported CLI installed and authenticated. ### Most of them are gated, which is why you may not see them Bundled skills declare their dependencies and disappear when those aren't met. `peekaboo` sets `os: ["darwin"]` and `requires.bins: ["peekaboo"]`, so it doesn't exist on a Linux gateway. `1password` gates on `op`. `gemini` gates on `gemini`. If a skill in the table above isn't showing up in `openclaw skills list`, the likely reason is that it's working exactly as designed — see [gating](/openclaw-skills/#gating-skills-that-hide-when-you-cant-run-them). Several also ship installer specs, so the macOS Skills UI can offer to install the missing binary for you. ## Why there's no ranked list of ClawHub skills here ClawHub is the largest skill registry of any agent covered on this site. It also has a download counter, which makes it look like the one ecosystem where a popularity ranking would be honest. It isn't, and the reason is in ClawHub's own documentation. Install counts come from telemetry on the standalone CLI: "When you run `clawhub install` while logged in, the CLI may send a best-effort install event so ClawHub can compute aggregate install counts." Users can turn it off with `CLAWHUB_DISABLE_TELEMETRY=1`. So the counter is best-effort, tied to being logged in, opt-out, and attached to the standalone `clawhub install` — [which is not the command most people use](/how-to-install-openclaw-skills/#the-two-commands-that-look-alike). Read it as a floor, never as usage share, and certainly not as quality. Meanwhile, the skill totals circulating in roundups — "over 13,000 community skills," "over 5,700 skills" — don't agree with each other, and ClawHub publishes no headline figure of its own. We're not going to pick one. That leaves us without any defensible basis for naming the ten best community skills, so we haven't. What follows is more useful. ## What to actually check on a ClawHub listing ClawHub surfaces real signals before you install, and they're more informative than a download count. Its documentation asks you to review, in this order: "the overall audit status, the risk level, any listed findings, required credentials, permissions, or environment variables, owner, source, version, changelog, downloads, stars, and other trust signals." Two of those are frequently misread as the same thing. From the docs: > Risk level asks: "How much power is here?" Audit status asks: "What should I do with this result?" | Audit status | What it means | |---|---| | `Pass` | No visible issue above low risk was found | | `Review` | Read the findings before installing. The release may still be legitimate | | `Warn` | Extra caution — a high-impact concern or warning signal | | `Malicious` | Do not install | | `Pending` / `Error` | Audits unfinished or failed | A publishing skill showing `Review` at `Medium` risk isn't a red flag; it means the skill appears purpose-aligned but can act with meaningful account authority. A `Pass` on a skill that runs shell commands still deserves your attention — the documentation says so itself: "A `Pass` is reassuring, but it does not replace your own judgment." Full treatment of what the audits check, what they miss, and what independent researchers found when they scanned the registry is on [the security page](/openclaw-skills-security/). Beyond the registry's own signals, the checklist that transfers from every other ecosystem still applies: read the `SKILL.md`, read anything in `scripts/`, check whether the description says when *not* to trigger, and check whether declared credentials match what the skill plausibly needs. The [Claude Code](/claude-code-skills-github/) and [Hermes](/hermes-agent-skills-github/) pages work through that reasoning in more detail. ## Where else to look - **ClawHub itself** — [clawhub.ai](https://clawhub.ai), filterable by Trending, Featured, Official, and New. The Official filter is the closest thing to a curated tier. - **`~/.agents/skills`** — the cross-agent directory OpenClaw reads at priority 3. Skills published for [Codex](/best-codex-skills/), [Claude Code](/best-claude-code-skills/), or [Cursor](/best-cursor-skills/) work here unchanged if they don't depend on that agent's specific tooling, so the organisation-published repositories listed on those pages are all candidates. - **Plugins** — plugins can ship skills by listing `skills` directories in `openclaw.plugin.json`, loading at the lowest precedence tier. ## Caveats - We have not installed or run OpenClaw, or used any skill named here. The bundled list is the repository's `skills/` directory tree, read via the GitHub API on 16 August 2026 — the docs describe bundled skills as "shipped with the install," and we did not install OpenClaw to confirm the shipped set matches the tree exactly. - Skill descriptions quoted above are taken from the skills' own `SKILL.md` frontmatter. - ClawHub's audit statuses and telemetry behavior are documented behavior, not independently verified by us. - OpenClaw is under very active development; the repository was pushed to the same day this page was researched. ## Sources - [`openclaw/openclaw` (GitHub)](https://github.com/openclaw/openclaw) — the `skills/` directory tree and individual `SKILL.md` files, read directly - [OpenClaw — ClawHub (official docs)](https://docs.openclaw.ai/clawhub) — registry surfaces and install telemetry - [ClawHub — Security Audits (official docs)](https://docs.openclaw.ai/clawhub/security-audits) — audit status, risk level, what to check before installing - [OpenClaw — Skills (official docs)](https://docs.openclaw.ai/tools/skills) — gating, plugin skills, config overrides --- ## How to Create an OpenClaw Skill The minimum viable skill is a directory, a file, and two frontmatter fields: ```bash mkdir -p ~/.openclaw/workspace/skills/hello-world ``` ````markdown # ~/.openclaw/workspace/skills/hello-world/SKILL.md --- name: hello-world description: A simple skill that prints a greeting. --- # Hello World When the user asks for a greeting, use the `exec` tool to run: ```bash echo "Hello from your custom skill!" ``` ```` ```bash openclaw skills list ``` That works. The rest of this page is the difference between a skill that loads and a skill that actually gets used. ## Let the bundled skill-creator do the first draft OpenClaw ships `skill-creator`, whose own description reads: "Author or review AgentSkills: create, repair, validate, or restructure SKILL.md files and bundled resources." It's worth using rather than hand-rolling frontmatter, because its workflow makes you answer the questions that decide whether the skill works — establish the contract, choose the invocation mode, then structure the body. Its second step in particular is the one people skip: - Model-discoverable: write a model-facing `description`, omit `disable-model-invocation`. - Manual-only: set `disable-model-invocation: true`, write a human-facing summary. - Direct tool command: add `command-dispatch: tool`, `command-tool`, and `command-arg-mode` only when the command bypasses the model. Decide that before writing the body, because it changes who the `description` is written for. ## Write the description for the budget, not for the reader This is the single highest-leverage constraint in OpenClaw, and it comes from arithmetic rather than style. Every eligible skill is compiled into a compact XML block in the system prompt at a cost of "~97 characters + your `name`, `description`, and `location` field lengths" — roughly 24 tokens per skill before your fields. That cost recurs in every session, for every eligible skill, whether or not it's used. Hence OpenClaw's own authoring rule: keep `description` "one line and under 160 characters." For comparison, the portable [Agent Skills spec](https://agentskills.io/specification) permits up to 1,024 characters. OpenClaw asks for roughly a sixth of that. If you're porting a skill from Claude Code or Codex, the description is the field most likely to need trimming. What has to survive the trim is the trigger. The description is the only thing the model sees when deciding whether to load your skill, so it needs to say *when to use this*, not *what this is*: ```yaml # Weak — describes the artifact description: A skill for working with our deployment system. # Better — describes the trigger description: Deploy or roll back a service to staging or production. Use when asked to ship, deploy, release, or revert. ``` If the block exceeds `skills.limits.maxSkillsPromptChars`, OpenClaw degrades in a documented order: keep skill identities first, then shortened descriptions, then drop descriptions entirely — and it tells you by pointing at `openclaw skills check`. A long description doesn't just cost tokens; past the ceiling it can be the thing that gets truncated. ## Naming rules - `name`: lowercase letters, digits, and hyphens. - Keep the directory name and frontmatter `name` aligned. - The slash command comes from `name`, not the folder path — so you can group skills in subfolders for organisation without changing how they're invoked: ```bash ~/.openclaw/workspace/skills/personal/hello-world/SKILL.md # still /hello-world ``` OpenClaw discovers `SKILL.md` up to six levels deep under any configured root. ## Reference bundled files with `{baseDir}` Don't hardcode absolute paths. `{baseDir}` resolves to the skill's own directory: ```markdown Run the helper script at `{baseDir}/scripts/run.sh`. ``` Conventional subdirectories are `scripts/`, `references/`, and `assets/`, matching the portable spec. ## Gating: make the skill disappear when it can't run This is OpenClaw's most useful authoring feature and the one most worth writing into a skill from the start. A `metadata.openclaw` block filters the skill out at load time when its requirements aren't met — so it costs nothing in the prompt and can't be selected on a machine where it would fail. ```yaml --- name: gemini-search description: Search the web using the Gemini CLI. Use when asked to look something up online. metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } } --- ``` | Key | Behavior | |---|---| | `requires.bins` | All listed binaries must exist on `PATH` | | `requires.anyBins` | At least one must exist on `PATH` | | `requires.env` | Each env var must exist in the process or config | | `requires.config` | Each `openclaw.json` path must be truthy | | `os` | Platform filter: `["darwin"]`, `["linux"]`, `["win32"]` | | `always` | Include on a compatible OS even when `requires.*` checks fail | A skill with no `metadata.openclaw` block is always eligible. Note that `always` does not override `os` — the platform filter is hard. Two things to know when writing these. Frontmatter is parsed as YAML first, and nested `metadata` blocks are flattened and re-parsed as JSON5 — which is why the JSON-style brace syntax above works inside YAML frontmatter. And `requires.bins` is checked on the **host** at load time; if your agent runs sandboxed, the binary needs to exist inside the container too. ### Declaring how to install the dependency If your skill gates on a binary, you can tell OpenClaw how to get it. The macOS Skills UI uses these specs to offer an install: ```yaml metadata: { "openclaw": { "emoji": "♊️", "requires": { "bins": ["gemini"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "gemini-cli", "bins": ["gemini"], "label": "Install Gemini CLI (brew)", }, ], }, } ``` Supported kinds are brew, node, go, uv, and download. With several listed, the gateway picks one — brew when available, otherwise node — following an overall preference order of Homebrew → uv → configured node manager → go → download. Specs can carry their own `os` filter. Worth knowing if you target Linux: brew-only installers are hidden in containers without `brew`, so add a second spec if Linux users matter to you. ### Wiring an API key For a skill that needs a credential, declare `primaryEnv` and let the user wire it in config rather than putting it in the file: ```json5 { skills: { entries: { "gemini-search": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, }, }, }, } ``` The key is injected into the host process for that agent turn only, and does not reach the sandbox. ## Choosing how the skill is invoked Three frontmatter fields shape this, and picking the wrong one is a common cause of "my skill never fires" or, worse, "my skill fired when I didn't want it to." ```yaml user-invocable: true # default — exposed as a slash command disable-model-invocation: false # default — model may select it command-dispatch: tool # slash command bypasses the model entirely command-tool: command-arg-mode: raw # forwards the raw args string ``` For anything with side effects — deploys, publishes, anything that spends money or changes production — set `disable-model-invocation: true`. The skill stays reachable as a slash command and via an explicit `$skill-name` reference, but the model can't decide to run it on its own. `command-dispatch: tool` is the unusual one: the slash command dispatches straight to a registered tool without the model in the loop at all. Reach for it only when you genuinely want an alias rather than a skill. ## Testing it ```bash openclaw skills list openclaw agent --message "give me a greeting" ``` Or invoke it explicitly in chat with `/skill hello-world`. If it doesn't appear, work through these in order: 1. **Session snapshot.** OpenClaw snapshots eligible skills when a session starts. Start a new one with `/new`, or `openclaw gateway restart`. The watcher does pick up `SKILL.md` changes by default, but a new session removes the doubt. 2. **Directory.** It must be under one of [the six documented roots](/openclaw-skills/#where-openclaw-loads-skills-from). 3. **Gating.** A `requires` or `os` clause you can't satisfy will filter the skill out silently. That's the feature working. 4. **Frontmatter.** A missing closing `---` is the usual culprit. OpenClaw's own advice is worth keeping: be concise, instruct the model on *what* to do rather than how to be an AI, and "if your skill uses `exec`, ensure prompts do not allow arbitrary command injection from untrusted input." ## Skill Workshop: proposals instead of direct writes If you want the agent to help build skills but not to write to your skill files directly, Skill Workshop is a proposal queue: "When the agent spots reusable work, it drafts a proposal instead of writing directly to `SKILL.md`. You review and approve before anything changes." ```bash openclaw skills workshop propose-create \ --name "hello-world" \ --description "A simple skill that prints a greeting." \ --proposal ./PROPOSAL.md openclaw skills workshop propose-update hello-world \ --proposal ./PROPOSAL.md \ --description "Updated greeting skill" openclaw skills workshop list openclaw skills workshop inspect openclaw skills workshop evaluate openclaw skills workshop apply ``` Use `--proposal-dir ./my-proposal/` when the proposal ships support files; the directory must contain `PROPOSAL.md` at its root, with extras under `assets/`, `examples/`, `references/`, `scripts/`, or `templates/`. The closest equivalent elsewhere is [Hermes Agent's staged-write approval queue](/hermes-agent-skills/#the-learning-loop-skills-that-write-themselves). Both exist for the same reason: an agent that can edit its own skills is useful, and an agent that can edit its own skills unsupervised is a different proposition. ## Publishing to ClawHub ```bash npm i -g clawhub clawhub login clawhub skill publish ./path/to/hello-world ``` Publish options: `--slug` (the published URL name), `--name` (display name), `--version` (semver), `--changelog`, and `--tags` (comma-separated, defaulting to `latest`). `--owner` publishes under a specific owner. Before publishing, two things are worth doing for the people who'll install it: **Fill in the metadata properly.** `name`, `description`, any `metadata.openclaw` gating, and a `homepage` if you have one. Gating in particular is a courtesy — it's what stops your macOS-only skill from appearing broken on someone's Linux gateway. **Expect to be audited.** ClawHub runs automated checks on every published skill, and the result is public on your listing before anyone installs. Its risk analysis looks for coherence — "do the name, summary, metadata, requested authority, and actual content line up with what users would reasonably expect?" A skill that requests credentials it doesn't visibly need will read badly, even with honest intent. If something is flagged wrongly, `clawhub skill rescan @owner/` requests a re-scan. See [the security page](/openclaw-skills-security/) for what the audit checks. Publishing requires a GitHub account old enough to pass ClawHub's upload gate. ## Making it portable If you'd like the skill to work in other agents, keep the portable core clean: - `name` and `description` are the portable spec; `scripts/`, `references/`, and `assets/` are the conventional directories everywhere. - OpenClaw-specific fields — `metadata.openclaw`, `user-invocable`, `command-dispatch`, `command-tool`, `command-arg-mode`, `{baseDir}` — do not travel. - The description length rule cuts both ways: a description written for OpenClaw's budget is comfortably inside every other agent's limit. A skill kept in `~/.agents/skills` is read natively by OpenClaw, [Codex](/codex-skills/#every-location-codex-scans), and [Cursor](/cursor-skills/#where-cursor-looks-for-skills), so cross-agent sharing needs no export step at all. ## Caveats - We have not installed or run OpenClaw, created a skill in it, or published to ClawHub. Every command, field, and constraint here is taken from the official documentation, and quoted where the wording matters. - The `skills.limits.maxSkillsPromptChars` default is not stated in the skills documentation; the degradation behavior is documented, the number isn't, and none is invented here. - The per-skill cost figure (~97 characters, ≈24 tokens) is OpenClaw's own published estimate. - Documented as of **August 2026**. OpenClaw is under very active development. ## Sources - [OpenClaw — Creating skills (official docs)](https://docs.openclaw.ai/tools/creating-skills) — the authoring workflow, naming rules, `{baseDir}`, gating, publishing steps, best practices - [OpenClaw — Skills (official docs)](https://docs.openclaw.ai/tools/skills) — frontmatter reference, gating keys, installer specs, token impact, snapshots - [OpenClaw — ClawHub (official docs)](https://docs.openclaw.ai/clawhub) — publish commands and options - [ClawHub — Security Audits (official docs)](https://docs.openclaw.ai/clawhub/security-audits) — what publishing is audited against - [`openclaw/openclaw` (GitHub)](https://github.com/openclaw/openclaw) — `skills/skill-creator/SKILL.md` and `skills/gemini/SKILL.md`, read directly - [agentskills.io — the portable specification](https://agentskills.io/specification) --- ## How to Install OpenClaw Skills The command you want, almost always: ```bash openclaw skills install @owner/skill-name ``` That installs from [ClawHub](https://clawhub.ai) into the active workspace's `skills/` directory. Everything below is the detail that decides where a skill actually lands, whether you can update it later, and what to check before you run it at all. ## Verify before you install ClawHub's registry is open — anyone with a GitHub account past the upload gate can publish. Before installing something you haven't read: ```bash openclaw skills verify @owner/skill-name openclaw skills verify @owner/skill-name --card ``` `verify` asks ClawHub for the skill's `clawhub.skill.verify.v1` trust envelope, and "exits non-zero when ClawHub marks verification as failed." `--card` prints the generated Skill Card. That's a signal, not a guarantee — OpenClaw's own documentation is blunt about it: "Treat third-party skills as **untrusted code**. Read them before enabling." What the audits do and don't catch is covered on [the security page](/openclaw-skills-security/). ## Finding a skill ```bash openclaw skills search "postgres backups" openclaw skills search "calendar" ``` Or browse [clawhub.ai](https://clawhub.ai) directly, which shows the current audit state on each listing before you install. ## Every install form All documented, with the destination each one writes to: | What you want | Command | Lands in | |---|---|---| | A ClawHub skill, this workspace | `openclaw skills install @owner/` | `/skills` | | A ClawHub skill, all local agents | `openclaw skills install @owner/ --global` | `~/.openclaw/skills` | | A specific version | `openclaw skills install --version 1.2.3` | as above | | A skills.sh reference | `openclaw skills install skills-sh:owner/repo/slug` | `/skills` | | Straight from a Git repo | `openclaw skills install git:owner/repo@ref` | `/skills` | | A local directory | `openclaw skills install ./path/to/skill --as my-tool` | `/skills` | `--global` is the flag that matters most in a multi-agent setup: it installs "into the shared `~/.openclaw/skills` directory, visible to all local agents unless agent allowlists narrow it." Two details for Git and local installs: `SKILL.md` must be at the source root, and the slug comes from the frontmatter `name` when valid, falling back to the directory or repository name. `--as ` overrides it. ## The two commands that look alike This is the trap worth knowing about, and it isn't mentioned in any install guide we found. OpenClaw ships `openclaw skills install`. ClawHub also ships a standalone CLI with its own `clawhub install`. They are not the same command with a different prefix: | | `openclaw skills install` | `clawhub install` | |---|---|---| | Installs into | The active workspace `skills/` directory, or `~/.openclaw/skills` with `--global` | `./skills` under the current working directory | | Records versions in | `.clawhub/origin.json` | `.clawhub/lock.json` | | Intended for | Installing skills for your agent | Registry-authenticated workflows, CI, publishing | If you run `clawhub install` from your home directory expecting your agent to pick the skill up, you'll get `~/skills` — which is not one of [the six directories OpenClaw scans](/openclaw-skills/#where-openclaw-loads-skills-from). Install the standalone CLI only when you need registry auth, publishing, or delete/undelete: ```bash npm i -g clawhub clawhub login ``` ## Updating ```bash openclaw skills update --all # every workspace skill openclaw skills update @owner/ --global openclaw skills update --all --global ``` One documented limitation that decides how you should install things in the first place: `openclaw skills update` "tracks ClawHub installs only — reinstall Git or local sources to refresh them." So a skill installed from `git:owner/repo@ref` is frozen until you reinstall it by hand. If you expect to keep something current and it exists on ClawHub, install it from ClawHub. ## Checking what loaded ```bash openclaw skills list openclaw skills check ``` `openclaw skills check` is also what OpenClaw points you at when the skills block has been compacted to fit the prompt budget — see [what skills cost](/openclaw-skills/#what-skills-actually-cost). If a skill you just installed isn't showing up, the usual cause isn't the install. OpenClaw "snapshots eligible skills when a session starts," so start a new session: ```bash /new # from chat openclaw gateway restart # or restart the gateway ``` The other common cause is gating: a skill declaring `requires.bins` or an `os` filter it can't satisfy on your machine is loaded and then filtered out deliberately. That's the system working — install the missing binary, or check the skill's `metadata.openclaw` block. ## Bringing skills from another agent **From Claude Code**, there's a migration path: ```bash openclaw migrate claude --dry-run openclaw migrate apply claude --yes ``` Skills with a `SKILL.md` are copied over structurally unchanged; `.claude/commands/` files are converted into skills with `disable-model-invocation: true`. Details of what does and doesn't transfer are on [the overview page](/openclaw-skills/#coming-from-claude-code). **From Codex**, there's a separate one, because Codex's directory is explicitly not an OpenClaw root: ```bash openclaw migrate plan codex openclaw migrate codex ``` **Without migrating at all:** `~/.agents/skills` is one of OpenClaw's six roots and also a native location for [Codex](/codex-skills/#every-location-codex-scans) and [Cursor](/cursor-skills/#where-cursor-looks-for-skills). A skill kept there is shared across all three with no copying. ## Private and non-ClawHub delivery For teams that need to distribute skills without publishing them, Gateway clients can stage a zip archive (`skills.upload.begin`, `skills.upload.chunk`, `skills.upload.commit`) then install with `skills.install({ source: "upload", ... })`. This is off by default and requires `skills.install.allowUploadedArchives: true` in `openclaw.json`. Normal ClawHub installs never need that setting — if a guide tells you to enable it for a routine install, something is wrong. ## Caveats - We have not installed or run OpenClaw. Every command and destination here is taken from the official documentation, and quoted where the precise wording matters. - Install destinations, update tracking, and the `clawhub` CLI's separate behavior are documented as of **August 2026**. OpenClaw is under very active development. - `openclaw skills verify` reflects ClawHub's audit state at the time you run it. It is not an audit performed by us. ## Sources - [OpenClaw — Skills (official docs)](https://docs.openclaw.ai/tools/skills) — install forms, destinations, update tracking, verification, private archives - [OpenClaw — ClawHub (official docs)](https://docs.openclaw.ai/clawhub) — the `clawhub` CLI and its separate install destination - [OpenClaw — Creating skills (official docs)](https://docs.openclaw.ai/tools/creating-skills) — session refresh behavior - [OpenClaw — Migrating from Claude (official docs)](https://docs.openclaw.ai/install/migrating-claude) — migration commands --- ## Are OpenClaw Skills Safe? Short answer: **the bundled skills are as trustworthy as OpenClaw itself; ClawHub skills come with a real automated audit whose result you can read before installing; and neither of those replaces reading the file.** OpenClaw's own documentation is unusually direct about the last point: > Treat third-party skills as **untrusted code**. Read them before enabling. Prefer sandboxed runs for untrusted inputs and risky tools. What makes this worth a page rather than a paragraph is that OpenClaw has more moving parts here than any other agent covered on this site — a registry with a published audit stack, path containment rules, an operator install policy, and one control that looks like a security boundary and explicitly isn't. ## Why a skill is a security question at all A skill is a document the agent reads and then acts on, plus optional files that may be executed. There's no sandbox between "the agent read this instruction" and "the agent did what it said." That makes the risk surface instruction-shaped rather than code-shaped: prompt injection, over-broad triggers, credentials requested for reasons that don't match the skill's job, a `scripts/` directory doing something the `SKILL.md` never mentions. ClawHub frames its own risk analysis around exactly this, using the [OWASP Agentic Skills Top 10](https://owasp.org/www-project-agentic-skills-top-10/) as a lens for "prompt injection, tool misuse, credential exposure, unsafe execution, memory or context poisoning, and excessive agency." That list is a reasonable summary of what can go wrong. ## What ClawHub checks before you install ClawHub is open by default — "anyone can upload, but publishing requires a GitHub account old enough to pass the upload gate." That's a spam gate, not a review. The real screening is automated and its results are public on each listing, at `//skills//security-audit`. The audit combines three things: **SkillSpector**, **VirusTotal**, and **risk analysis**. ### Audit status and risk level are different questions The distinction the documentation draws is the useful part, and it's routinely collapsed elsewhere: > Risk level asks: "How much power is here?" Audit status asks: "What should I do with this result?" | Audit status | Meaning | |---|---| | `Pass` | "No visible issue above low risk was found" | | `Review` | "Read the findings before installing. The release may still be legitimate" | | `Warn` | "Use extra caution. ClawHub found a high-impact concern or warning signal" | | `Malicious` | "Do not install" | | `Pending` | Audits have not finished yet | | `Error` | The audit could not be completed | | Risk level | Meaning | |---|---| | `Low` | "Little sensitive authority or user impact was found" | | `Medium` | "The release has meaningful authority, such as account access or data changes" | | `High` | "High-impact authority, severe findings, or malicious signals" | So a skill that publishes content on your behalf can legitimately sit at `Review` / `Medium` — the documentation gives exactly that example. It isn't a warning that something is wrong; it's a statement that the skill can act with real authority and you should decide whether you want that. Findings are labelled `Info` through `Critical`. Low-confidence findings are hidden from the public rollup, which keeps the page readable and also means you're seeing a filtered view. ### What the audit is actually looking at Per the docs, ClawHub audits "skill instructions or plugin metadata, declared environment variables and permissions, install instructions and package metadata, included files and file manifests, compatibility and capability metadata." The organising question is coherence — "do the name, summary, metadata, requested authority, and actual content line up with what users would reasonably expect?" And the framing is deliberately not capability-phobic: "Powerful behavior is not automatically bad… The audit checks whether that power is expected, disclosed, and proportionate." ### VirusTotal is telemetry, not a verdict ClawHub summarises vendor engine counts in plain language — "62/62 vendors flagged this skill as clean" — and is explicit about the limits: "VirusTotal remains telemetry. It does not replace ClawHub's own artifact-aware risk analysis." That's the right framing to carry into your own reading. Antivirus engines are good at known-malicious binaries. A malicious skill is frequently just prose — a paragraph telling an agent to read a credential file and post it somewhere — and there is no engine signature for a convincing sentence. ### Verifying from the command line ```bash openclaw skills verify @owner/skill-name openclaw skills verify @owner/skill-name --card ``` `verify` requests the skill's `clawhub.skill.verify.v1` trust envelope and "exits non-zero when ClawHub marks verification as failed," which makes it usable in a script. Installed ClawHub skills verify against the version and registry recorded in `.clawhub/origin.json`. Publishers can request a re-scan after a false positive with `clawhub skill rescan @owner/`. ### The honest limit, stated by ClawHub itself > Audits are strong safety signals, but they are not a guarantee that a release is risk-free. Always use judgment before granting sensitive access. ## What independent research found In February 2026, Snyk published **ToxicSkills**, an audit of the agent-skills ecosystem. The figures are worth stating precisely, because the version circulating in secondary coverage is wrong in both halves. The study scanned **3,984 skills from ClawHub *and* skills.sh**, as of **5 February 2026**, using the mcp-scan engine with eight custom security policies plus human review. | Finding | Figure | |---|---| | Skills with a flaw at any severity | 1,467 (36.82%) | | Skills with at least one critical-level issue | 534 (13.4%) | | Confirmed malicious payloads after human review | 76 | | Malicious skills still publicly available at publication | 8 | | Prompt injection among *confirmed malicious* skills | 91% | | Prompt injection prevalence across ClawHub overall | 2.6% | Secondary write-ups have compressed this into "prompt injection in 36%, 1,467 malicious payloads." Both numbers are misapplied: 36.82% is any-severity flaws, not prompt injection; 1,467 is that same any-severity count, not payloads. Confirmed malicious payloads numbered 76. Read carefully, the study says something more useful than either version: the large number is a code-hygiene problem, the small number is the adversarial one, and prompt injection is overwhelmingly concentrated in the deliberately malicious tail rather than spread across the registry. Other third-party reports exist with different populations, methods, and headline numbers. We're citing one study we could read in full rather than blending several into a single figure that belongs to none of them. ## The controls OpenClaw gives you ### Path containment Workspace, project-agent, and extra-dir discovery "only accepts skill roots whose resolved realpath stays inside the configured root, unless `skills.load.allowSymlinkTargets` explicitly trusts a target root." Managed and personal roots may contain symlinked skill folders, but "every `SKILL.md` realpath must still stay inside its resolved skill directory." In short: a skill can't escape its root via a symlink unless you've said it may. If you do use `allowSymlinkTargets`, note that Skill Workshop only writes through those trusted targets when `skills.workshop.allowSymlinkTargetWrites` is also enabled — two separate opt-ins. ### Operator install policy `security.installPolicy` runs "a trusted local policy command before skill installs continue." It applies across ClawHub, uploaded, Git, local, update, and dependency-installer paths, and "fails closed when the command cannot return a valid decision." This is the control to reach for in a team or managed environment: a hook that can allow, warn, or block before anything lands on disk, and that errs toward blocking when it can't decide. ### Secret injection is host-only `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets "into the **host** process for that agent turn only — not into the sandbox," and the original environment is restored after the run. Two consequences. Blast radius is bounded to a single agent turn rather than the process lifetime. And if you run agents sandboxed expecting the sandbox to receive those secrets, it won't — that's a functional gotcha as much as a security one. ### Skill Workshop, for agent-authored skills OpenClaw's agent can propose skills rather than write them. Skill Workshop is "a proposal queue between the agent and your active skill files" — proposals are drafted, then inspected, evaluated, and applied by you. If you're letting an agent evolve its own skill library, this is the gate that keeps a review step in the loop. See [how to create an OpenClaw skill](/how-to-create-an-openclaw-skill/#skill-workshop-proposals-instead-of-direct-writes). ### The control that is explicitly not a boundary Agent allowlists (`agents.defaults.skills`, `agents.entries.*.skills`) restrict which skills an agent can see. It's tempting to read that as sandboxing. The documentation says otherwise, in terms worth quoting rather than summarising: > This is not a host shell authorization boundary. If the same agent can use `exec`, constrain that shell separately with sandboxing, OS-user isolation, exec deny/allowlists, and per-resource credentials. An allowlist manages what the agent knows about. It does not manage what the agent can do. An agent with `skills: []` and an unrestricted `exec` tool can still run anything a skill would have told it to run. For actual containment, OpenClaw's broader security guidance points at sandbox modes and workspace access levels under `agents.*.sandbox`, tool deny lists, and `openclaw security audit --deep` to find agents whose tool policies are more permissive than intended. One further detail that trips people up: `requires.bins` gating is checked on the **host** at load time. A sandboxed agent needs the binary inside the container too, or the skill will appear eligible and then fail. ## A workable default Nothing here is a recommendation we've tested; it's the conservative reading of the documented controls. 1. Prefer bundled skills, then ClawHub skills marked Official, then anything else. 2. Run `openclaw skills verify` before installing something you haven't read, and read the audit findings rather than just the status. 3. Read the `SKILL.md` in full, and every file in `scripts/`. This is the only step that catches a well-written malicious instruction. 4. Check that declared credentials and `requires.env` match what the skill plausibly needs to do its job. 5. Install into the workspace rather than `--global` until you trust it — narrower blast radius. 6. For anything untrusted, or anything processing untrusted input, run the agent sandboxed with a tool deny list. The allowlist is not that. 7. In a team, set `security.installPolicy` so the decision isn't made per-person. ## Caveats - We have not installed or run OpenClaw, submitted anything to ClawHub, or audited any skill. Everything about OpenClaw and ClawHub behavior here is documented behavior, quoted where precision matters. - We have not evaluated SkillSpector, ClawScan, or the audit pipeline's accuracy. "Automated audit" is ClawHub's description of its own process. - Snyk's figures describe a **5 February 2026** snapshot of ClawHub *and* skills.sh combined, using their methodology. They are not our findings and do not describe ClawHub alone. - The OWASP Agentic Skills Top 10 is cited because ClawHub says it uses it as a lens; we have not reviewed the project's contents. - Controls, config keys, and audit statuses are documented as of **August 2026**, and OpenClaw is under very active development. ## Sources - [ClawHub — Security Audits (official docs)](https://docs.openclaw.ai/clawhub/security-audits) — audit status, risk level, findings, VirusTotal framing, ClawScan - [OpenClaw — Skills, Security section (official docs)](https://docs.openclaw.ai/tools/skills) — untrusted-code warning, path containment, install policy, secret injection scope, the allowlist caveat - [OpenClaw — ClawHub (official docs)](https://docs.openclaw.ai/clawhub) — publishing gate, moderation, scan holds - [ClawHub — Security (official docs)](https://docs.openclaw.ai/clawhub/security) — disclosure policy, and where to report third-party skill issues - [Snyk — ToxicSkills](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/) — independent scan of 3,984 skills, February 2026 - [OWASP Agentic Skills Top 10](https://owasp.org/www-project-agentic-skills-top-10/) — the risk taxonomy ClawHub's risk analysis uses --- ## OpenClaw Skills: The Practical Guide ## What OpenClaw skills are **OpenClaw** is an open-source personal AI assistant that runs locally and connects to the messaging platforms and tools you already use. A **skill** is a directory containing a `SKILL.md` file — YAML frontmatter plus markdown instructions. OpenClaw's own documentation puts the purpose crisply: skills "teach the agent how and when to use tools." OpenClaw follows the [Agent Skills open standard](https://agentskills.io), which its docs state directly. The same `SKILL.md` works in Claude Code, Codex, Cursor, and Hermes Agent — what differs is everything around it, and OpenClaw has more of that machinery than any other agent covered on this site. See [SKILL.md](/skill-md/) for the portable format. The minimum skill is two fields: ```yaml --- name: image-lab description: Generate or edit images via a provider-backed image workflow --- When the user asks to generate an image, use the `image_generate` tool... ``` ## Where OpenClaw loads skills from Six sources, in a documented precedence order. "When the same skill name appears in multiple places, the highest source wins." | Priority | Source | Path | |---|---|---| | 1 — highest | Workspace skills | `/skills` | | 2 | Project agent skills | `/.agents/skills` | | 3 | Personal agent skills | `~/.agents/skills` (default state only) | | 4 | Managed / local skills | `/skills` | | 5 | Bundled skills | shipped with the install | | 6 — lowest | Extra directories | `skills.load.extraDirs` + plugin skills | `` defaults to `~/.openclaw`, so priority 4 is normally `~/.openclaw/skills` — that's the directory `--global` installs write to. **A correction worth making explicitly**, because it affects whether your skill loads at all: several widely-linked guides teach `.openclaw/skills/` as the project skills directory. That path is not in the load order. Project-level skills go in `/skills` or `/.agents/skills`. Discovery is recursive — OpenClaw finds a skill "whenever `SKILL.md` appears anywhere under a configured root (up to 6 levels deep)". The folder path is organisational only: ```text /skills/research/SKILL.md → skill "research" /skills/personal/research/SKILL.md → also skill "research" ``` The name comes from the frontmatter `name` field, falling back to the directory name. Agent allowlists match on that name too. ### Codex directories are deliberately not roots Worth knowing if you run both, because OpenClaw and Cursor made opposite decisions here. From the docs: > Codex CLI's native `$CODEX_HOME/skills` directory is **not** an OpenClaw skill root. Use `openclaw migrate plan codex` to inventory those skills, then `openclaw migrate codex` to copy them into your OpenClaw workspace. [Cursor reads `~/.codex/skills` for compatibility](/cursor-skills/#where-cursor-looks-for-skills). OpenClaw refuses to and gives you a migration command instead. Note that `~/.agents/skills` *is* an OpenClaw root, so a skill kept in the cross-agent location is shared without any migration at all. ### Coming from Claude Code `openclaw migrate claude` copies Claude skills with a `SKILL.md` into the OpenClaw workspace skills directory, structurally unchanged. Two details from the migration docs are more interesting than the copy itself: - Claude command files under `.claude/commands/` "are converted into OpenClaw skills with `disable-model-invocation: true`" — the same conversion [Cursor's `/migrate-to-skills` performs](/cursor-skills-vs-rules/#where-commands-fit-now) on its own commands. - `CLAUDE.md` content is copied or appended into the OpenClaw workspace `AGENTS.md`. Hooks, permission allowlists, `CLAUDE.local.md`, `.claude/rules/`, and Claude subagents do not transfer; the docs describe them as archive-only for manual review. ```bash openclaw migrate claude --dry-run openclaw migrate apply claude --yes ``` ## The frontmatter Required: `name` and `description`. The optional fields are where OpenClaw diverges most from the portable spec: | Field | Default | What it does | |---|---|---| | `homepage` | — | URL shown as "Website" in the macOS Skills UI | | `user-invocable` | `true` | Expose the skill as a user slash command | | `disable-model-invocation` | `false` | "keeps the skill's instructions out of the agent's normal prompt". Still reachable as a slash command when `user-invocable` is true | | `command-dispatch` | — | Set to `tool` and the slash command bypasses the model entirely | | `command-tool` | — | Which tool to invoke under tool dispatch | | `command-arg-mode` | `raw` | Forwards the raw args string; the tool receives `{ command, commandName, skillName }` | `command-dispatch: tool` is unusual enough to call out: it produces a skill the model never sees or reasons about. You type the command, OpenClaw hands the raw arguments straight to a registered tool. No other ecosystem covered here has an equivalent — it's closer to an alias than to a skill in the usual sense. One parsing quirk to be aware of when writing frontmatter: it's "parsed as YAML first; if that fails, it falls back to a single-line-only parser," and nested `metadata` blocks are flattened to JSON and re-parsed as JSON5. That's why the gating examples below use JSON-style braces inside YAML frontmatter and still work. In the body, `{baseDir}` resolves to the skill's own directory — use it for referencing bundled scripts rather than hardcoding a path. ## Gating: skills that hide when you can't run them This is OpenClaw's most distinctive mechanism and it's almost entirely absent from third-party coverage. Skills are filtered **at load time** using a `metadata.openclaw` block. A skill with no such block "is always eligible unless explicitly disabled." | Key | Behavior | |---|---| | `requires.bins` | Every listed binary must exist on `PATH` | | `requires.anyBins` | At least one listed binary must exist on `PATH` | | `requires.env` | Each env var must exist in the process or be provided via config | | `requires.config` | Each `openclaw.json` path must be truthy | | `os` | Hard platform filter: `["darwin"]`, `["linux"]`, `["win32"]` | | `always` | Include whenever `os` is compatible, bypassing all `requires.*` checks | | `primaryEnv` | Env var wired to `skills.entries..apiKey` | | `install` | Installer specs used by the macOS Skills UI | The bundled skills use this in practice. Reading them directly from the repository: ```yaml # skills/peekaboo/SKILL.md metadata: { "openclaw": { "emoji": "👀", "os": ["darwin"], "requires": { "bins": ["peekaboo"] }, ... }, } ``` So the macOS UI-automation skill simply doesn't exist as far as a Linux agent is concerned. `1password` gates on the `op` binary, `mcporter` on `mcporter`, `gemini` on `gemini`. The effect is that a large bundled library doesn't clutter the prompt with capabilities the machine can't actually perform. Note the `os` filter is described as hard: `always` does not override it. ### Skills that know how to install their own dependency The `install` key is a real mechanism, not documentation. A skill can declare how to obtain the binary it's gated on: ```yaml # skills/1password/SKILL.md metadata: { "openclaw": { "requires": { "bins": ["op"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "1password-cli", "bins": ["op"], "label": "Install 1Password CLI (brew)", }, ], }, } ``` Documented selection behavior: with multiple installers listed the gateway picks one — brew when available, otherwise node — and the overall preference order is Homebrew → uv → configured node manager → go → download. Node installs honour `skills.install.nodeManager` (npm by default; pnpm, yarn, and bun are options). One gotcha the docs are explicit about: "`requires.bins` is checked on the **host** at skill load time. If an agent runs in a sandbox, the binary must also exist **inside the container**." ## Invoking a skill Three forms, and the first is easy to miss because it isn't a slash: - **`$name` in the composer.** Type `$` in the Control UI to search available skills; selecting one inserts a stable reference without replacing the rest of your message. You can reference several in one prompt: ```text Use $github and $release_notes to summarize this change for the release. ``` A single message may reference **up to eight** distinct skills — beyond that OpenClaw "returns a visible error instead of ignoring extra references." - **`/name ...`** is the standalone command form, and it's the one that can use direct tool dispatch. - **`/skill `** invokes explicitly by name. A neat detail: uppercase shell-style variables like `$HOME`, `$PATH`, and `$EDITOR` stay literal text, while lowercase `$home`, `$path`, `$editor` reference skills with those names. Escape a reference as `\$name` when you want it left alone. Skills with `disable-model-invocation: true` stay out of the `$` picker and out of the model's prompt — but an authorized explicit `$skill-name` reference still invokes them. The flag hides a skill from model-initiated selection; it doesn't disable it. ## What skills actually cost OpenClaw publishes more precise numbers here than any other agent covered on this site, and they're worth knowing because they explain the authoring advice. Eligible skills are compiled into a compact XML block injected into the system prompt. Per the docs: - **Per skill:** "~97 characters + your `name`, `description`, and `location` field lengths." - "At ~4 chars/token, 97 chars ≈ 24 tokens per skill before field lengths." - XML escaping expands `& < > " '` into entities, adding a few characters each. - Base overhead applies only when at least one skill is eligible. When the rendered block would exceed `skills.limits.maxSkillsPromptChars`, OpenClaw degrades in a documented order rather than truncating arbitrarily: preserve as many skill identities as the compact format allows, spend any remaining budget on shortened descriptions, omit descriptions entirely if nothing is left — and note `openclaw skills check` in the prompt so you know it happened. That's why OpenClaw's own authoring guide asks for a `description` that's "one line and under 160 characters," far tighter than the 1,024-character ceiling the portable spec permits. The description is a recurring cost in every session, not a one-off. For comparison, all documented rather than measured by us: [Codex](/codex-skills/#the-context-budget-that-shapes-everything) caps its index at 2% of context or 8,000 characters; Claude Code's equivalent default is around 1%; [Cursor](/cursor-skills/#on-context-cost) publishes no figure at all. ## Snapshots: why your new skill didn't appear OpenClaw "snapshots eligible skills **when a session starts** and reuses that list for all subsequent turns in the session." So a skill added mid-conversation generally isn't visible until the next session. Two exceptions refresh it mid-session, picked up on the next agent turn: the skills watcher detecting a `SKILL.md` change (on by default, 250 ms debounce, configurable at `skills.load.watch`), and a newly connected eligible remote node. If in doubt, start a new session with `/new` or restart the gateway. ## Allowlists: separating where a skill lives from who can use it Precedence decides which copy of a skill wins. Allowlists decide which agent can see it at all — a separate control, configured under `agents`: ```json5 { agents: { defaults: { skills: ["github", "weather"] }, entries: { writer: { default: true }, // inherits the defaults docs: { skills: ["docs-search"] }, // replaces them entirely "locked-down": { skills: [] }, // no skills }, }, } ``` A non-empty entry list "is the **final** set — it does not merge with defaults." The allowlist applies "across prompt building, slash-command discovery, sandbox sync, and skill snapshots." The docs attach a caveat that deserves repeating rather than paraphrasing: > This is not a host shell authorization boundary. If the same agent can use `exec`, constrain that shell separately with sandboxing, OS-user isolation, exec deny/allowlists, and per-resource credentials. In other words, restricting an agent's skills is context management, not a security control. What that means in practice is on [the security page](/openclaw-skills-security/). ## Turning a skill on or off Bundled and managed skills are configured under `skills.entries` in `~/.openclaw/openclaw.json`: ```json5 { skills: { entries: { peekaboo: { enabled: true }, sag: { enabled: false }, "image-lab": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, }, }, }, } ``` Keys match the skill name unless the skill sets `metadata.openclaw.skillKey`. `allowBundled` is a bundled-only allowlist that leaves managed and workspace skills untouched. The bundled `coding-agent` skill is opt-in — it needs `enabled: true` plus one of `claude`, `codex`, `opencode`, or another supported CLI installed and authenticated. Environment variables and API keys from `skills.entries` are injected into `process.env` for the duration of the run and restored afterwards — and, importantly, "scoped to the **host** agent run, not the sandbox." ## Skill Workshop: agent-drafted skills, reviewed first OpenClaw's agent can propose skills rather than write them. Skill Workshop is "a proposal queue between the agent and your active skill files. When the agent spots reusable work, it drafts a proposal instead of writing directly to `SKILL.md`. You review and approve before anything changes." ```bash openclaw skills workshop list openclaw skills workshop inspect openclaw skills workshop evaluate openclaw skills workshop apply ``` The closest analogue elsewhere is [Hermes Agent's staged-write approval queue](/hermes-agent-skills/#the-learning-loop-skills-that-write-themselves), which gates its self-editing behind `/skills pending|diff|approve|reject`. Both are review gates on agent-authored skills, and no other ecosystem covered here has one. Authoring detail is on [how to create an OpenClaw skill](/how-to-create-an-openclaw-skill/). ## An implementation detail worth knowing if you also run Claude Code From the docs, describing what happens with the bundled `claude-cli` backend: > OpenClaw also materializes the same eligible skill snapshot as a temporary Claude Code plugin and passes it via `--plugin-dir`. Other CLI backends use the prompt catalog only. So when OpenClaw drives Claude Code, your OpenClaw skills reach it through [Claude Code's plugin system](/claude-code-skills/) rather than through its skills directories. A concrete instance of the two ecosystems interoperating at a level neither one advertises. ## Skills vs plugins vs MCP, in OpenClaw | Concept | What it is | How it reaches the agent | |---|---|---| | **Skill** | `SKILL.md` plus optional bundled files, teaching how and when to use tools | Compiled into the system prompt as an XML block; invoked via `$`, `/`, or model selection | | **Plugin** | A packaged extension that can add tools and ship its own skills | Skills contributed at the lowest precedence tier | | **MCP server** | An external protocol connection exposing tools | Configured separately. The bundled `mcporter` skill exists precisely to teach the agent to drive them | That last row is the clearest illustration of the layer distinction anywhere in this ecosystem: `mcporter` is a skill whose entire job is listing, configuring, authenticating against, and calling MCP servers. The skill is the knowledge; MCP is the access. See [Agent Skills vs MCP](/agent-skills-vs-mcp/). ## Limitations and caveats - We have not installed or run OpenClaw. Everything here is documented behavior or read directly from the `openclaw/openclaw` repository, and this page says which. - `skills.limits.maxSkillsPromptChars` has a configurable default that the skills documentation doesn't state. The degradation behavior is documented; the number isn't, so none is given here. - The per-skill token figure (~97 characters, ≈24 tokens) is OpenClaw's own published estimate, not our measurement. - OpenClaw is under very active development — the repository was pushed to the same day this page was researched, **16 August 2026**. Check the official docs if you're reading this much later. ## Sources - [OpenClaw — Skills (official docs)](https://docs.openclaw.ai/tools/skills) — load order, frontmatter, gating, invocation, token impact, snapshots, allowlists - [OpenClaw — Creating skills (official docs)](https://docs.openclaw.ai/tools/creating-skills) — authoring rules and the description length guidance - [OpenClaw — Migrating from Claude (official docs)](https://docs.openclaw.ai/install/migrating-claude) — what transfers and what doesn't - [`openclaw/openclaw` (GitHub)](https://github.com/openclaw/openclaw) — bundled `SKILL.md` files read directly (`1password`, `peekaboo`, `mcporter`, `gemini`, `skill-creator`, `clawhub`) - [agentskills.io — the open standard OpenClaw implements](https://agentskills.io) --- ## Agent Skills Compatibility: Which Agents Support SKILL.md The short answer: **a `SKILL.md` using only the portable core runs across a wide range of agents unchanged.** The portable core is `name`, `description`, the markdown body, and the `scripts/` / `references/` / `assets/` convention. Everything past that is where compatibility becomes a real question — and where a list of product names stops helping. ## What "support" is being claimed The [Agent Skills client showcase](https://agentskills.io/clients) listed **46 products** as of 16 August 2026. That is a showcase, not a conformance suite: it records that a vendor says it supports the format. It does not test behaviour, and neither have we. So every claim on this page carries one of four levels: | Level | Meaning | |---|---| | **Verified** | We read the runtime's own documentation or source and can cite specifics | | **Documented** | The vendor documents skill support; we have not examined it in depth | | **Listed** | Appears on the showcase; behaviour unexamined by us | | **Not established** | No claim made | We hold **Verified** evidence for five runtimes. For the other forty-one we will not invent behaviour, and you should be sceptical of anyone who does. ## The five we can speak to in detail All rows below are **Verified** — read from each runtime's documentation or source, with the full working in each cluster. | | Claude Code | Codex | Cursor | OpenClaw | Hermes Agent | |---|---|---|---|---|---| | **Personal root** | `~/.claude/skills/` | `$HOME/.agents/skills` | `~/.cursor/skills/`, `~/.agents/skills/` | `~/.agents/skills`, `/skills` | `~/.hermes/skills/` | | **Project root** | `.claude/skills/` | `.agents/skills` up the project chain | `.cursor/skills/`, `.agents/skills/` | `/skills`, `/.agents/skills` | via `external_dirs` | | **Reads other runtimes' roots** | No | No | **Yes** — `.claude/skills/`, `.codex/skills/` and home equivalents | No, by explicit decision | Only if you configure it | | **Explicit invocation** | `/skill-name` | `$skill-name`; `@` in ChatGPT | `/skill-name` | `$name` in a message, `/name` as a command | `/skill-name` | | **Turn off automatic use** | `disable-model-invocation` | `allow_implicit_invocation: false` | `disable-model-invocation` | `disable-model-invocation` | — | | **Index budget** | ~1% of context | 2% or 8,000 chars | Not published | ~97 chars/skill, configurable ceiling | Not published | | **Name collisions** | Precedence chain | **Both appear, unmerged** | Not documented | Highest-priority root wins | Not documented | | **Import from another agent** | — | — | `/migrate-to-skills` (rules and commands) | `openclaw migrate claude`, `openclaw migrate codex` | — | | **Runtime-only frontmatter** | `context: fork` | `agents/openai.yaml` | `paths` | `metadata.openclaw.*`, `command-dispatch` | `metadata.hermes.*` | Detail per runtime: [Claude Code](/claude-code-skills/) · [Codex](/codex-skills/) · [Cursor](/cursor-skills/) · [OpenClaw](/openclaw-skills/) · [Hermes Agent](/hermes-agent-skills/) ## The rest of the ecosystem The showcase spans far more than coding agents — IDEs and editors (VS Code, GitHub Copilot, JetBrains' Junie, Kiro, Roo Code, TRAE), terminal agents (Gemini CLI, OpenCode, Goose, Amp, Factory, Mistral's Vibe), data platforms (Databricks Genie Code, Snowflake Cortex Code), frameworks (Spring AI, Laravel Boost, fast-agent), and vertical products in healthcare and infrastructure. For all of these our level is **Listed**, or at best **Documented** where the vendor publishes a skills page. We have not examined their roots, invocation, budgets or collision behaviour, and this page will not guess at them. If you need certainty for one of these, the vendor's own skills documentation — linked from the showcase — is the place to go. That gap is honest rather than lazy: verifying a runtime properly means reading its documentation and often its source, which is what produced the five columns above. ## Where portability actually breaks This is the part a name list can't give you. ### One field breaks a skill outright Cursor's `paths` field scopes a skill to matching files. Add it to a skill running in Claude Code and the skill becomes **completely undiscoverable** — missing from autocomplete, unlisted, and returning `Unknown skill` on direct invocation. Removing the single line restores it. This is a public issue read to its resolution, covered in full in [agent skills not working](/agent-skills-not-working/#paths-breaks-discovery-in-claude-code). It is the clearest demonstration on this site of why "both support Agent Skills" is not the same as "this skill works in both." ### Runtime-only fields don't travel Most degrade quietly — an unrecognised field is ignored, and the skill runs with less nuance than intended: | Field | Home runtime | Elsewhere | |---|---|---| | `metadata.openclaw.requires` | OpenClaw | Ignored — the skill loses its dependency gating and appears even where it can't run | | `agents/openai.yaml` | Codex | Ignored — invocation policy and MCP dependencies are lost | | `context: fork` | Claude Code | Ignored — the skill runs inline rather than as a subagent | | `metadata.hermes.requires_toolsets` | Hermes Agent | Ignored — conditional activation is lost | | `paths` | Cursor | **Breaks discovery in Claude Code**; ignored elsewhere | ### `allowed-tools` is in the spec and still unreliable The specification marks it **experimental**, with support that "may vary between agent implementations." It's the field people reach for to constrain a skill, which makes its unevenness the most consequential caveat in the format. Don't build a trust model on it. ### Description length advice contradicts itself across runtimes The specification permits 1,024 characters. OpenClaw's own authoring guidance asks for one line under 160. Practical reports from Claude Code users running many skills suggest keeping under 200. All three are right for their runtime, because each has a different index budget — and a description written for the tightest constraint is safe everywhere. ### Hosted runtimes have no filesystem at all Not every runtime answers "where do skills live" with a path. Hosted products scope skills to a workspace with upload and export instead of directories, which changes installation, sharing and versioning entirely. Portability there means exporting an archive, not copying a folder. ## The one location that travels The bottom-up convention worth knowing: **`.agents/skills`** is read natively by Codex, Cursor and OpenClaw. A skill kept there is available in all three with no copying, no symlink, and no migration. Cursor goes further and reads Claude Code's and Codex's directories too, which means a skill written for Claude Code is already available in Cursor with nothing to do. That is the single most useful compatibility fact in the ecosystem and it appears in almost no third-party coverage. Two caveats. Symlinking `.agents/skills` to a shared library [breaks discovery in Codex and Claude Code](/agent-skills-not-working/#a-path-the-runtime-wont-follow) — copy instead. And OpenClaw deliberately does *not* read Codex's `~/.codex/skills`, offering `openclaw migrate codex` instead. ## Writing for portability If you want one file to work in as many places as possible: 1. **Use only `name`, `description`, and the body.** Everything else is a compatibility question. 2. **Write the description for the tightest budget** — one line, under about 160 characters, trigger-focused. 3. **Keep `SKILL.md` short** and push detail into `references/`. The 500-line guidance is a portability rule as much as a context one. 4. **Put runtime-specific behaviour in `metadata`**, namespaced, where it will be ignored rather than misread. 5. **Never add `paths` to a skill you intend to share.** 6. **Treat `allowed-tools` as advisory**, not as a control. 7. **Store it in `.agents/skills`** if you use more than one of Codex, Cursor or OpenClaw. [SKILL.md, the format](/skill-md/) covers the field set in full; [where to find agent skills](/where-to-find-agent-skills/) covers distributing it once it's written. ## Caveats - **Nothing here is a conformance test.** We have not run any runtime, installed any skill, or reproduced any behaviour. Every Verified row is read from documentation or source; every other row says so. - The 46-client figure is the showcase's listing count on **16 August 2026**, not a count of implementations we checked. - Budgets, roots and field sets are the fastest-moving facts on this site. Where a runtime publishes no figure, this page says so rather than estimating. - Absence from the Verified set means we haven't examined a runtime — not that it works badly. ## Sources - [Agent Skills — client showcase](https://agentskills.io/clients) and [specification](https://agentskills.io/specification) - Runtime documentation: [Claude Code](https://code.claude.com/docs/en/skills), [Codex](https://developers.openai.com/codex/skills), [Cursor](https://cursor.com/docs/context/skills), [OpenClaw](https://docs.openclaw.ai/tools/skills), [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [`anthropics/claude-code` #49835](https://github.com/anthropics/claude-code/issues/49835) — the `paths` discovery failure - [`openai/codex` #11314](https://github.com/openai/codex/issues/11314) — symlinked skill roots --- ## Agent Skills Not Working: A Diagnostic Reference Start here, because two questions separate almost every case: 1. **Does the agent list the skill at all?** If it doesn't, it's a **discovery** problem — wrong directory, wrong filename, broken frontmatter, or a path the runtime refuses to follow. 2. **If it lists the skill, does invoking it explicitly work?** Type `/skill-name` (or `$skill-name` in OpenClaw's composer). If explicit invocation works but the agent never reaches for it on its own, it's a **triggering** problem, and the description is almost always the cause. Those are different failures with different fixes, and most guides run them together. ## How claims on this page are labelled Skills problems attract a lot of confident, wrong advice — including in Google's own AI summary of this topic, as documented [below](#a-correction-worth-making). So every cause here is marked: - **Documented** — stated in the runtime's own documentation or the [Agent Skills specification](https://agentskills.io/specification). - **Verified issue** — a public bug report read through to its resolution, cited by number, with its state and version where the reporter gave one. - **Diagnosis** — our inference from mechanics we hold. Labelled wherever it appears. We have not run these agents or reproduced these failures. Nothing here is presented as our own testing. --- ## Class 1: the skill is never discovered ### Filename case `SKILL.md` is case-sensitive. A file named `skill.md` is not found. This is worth putting first because it is the resolution of one of the most-cited bug reports in this space. In [`anthropics/claude-code` #17417](https://github.com/anthropics/claude-code/issues/17417) a user reported skills in `.claude/skills/` never appearing, and posted a detailed root-cause analysis blaming `/tmp/claude/` directory permissions. The issue was later closed with the reporter's own correction: > The problem was caused by incorrect case of files. skill.md instead of SKILL.md **Verified issue** (#17417, closed January 2026). The spec also requires that `name` in the frontmatter match the parent directory name. Both are silent failures. ### A path the runtime won't follow Symlinked skill directories break discovery in more than one runtime, independently: | Runtime | Behaviour | Evidence | |---|---|---| | **Codex** | Skills under a symlinked `.agents/skills` are not discovered. A real directory works | [`openai/codex` #11314](https://github.com/openai/codex/issues/11314) — closed February 2026, reported on CLI v0.98.0. Workaround: copy rather than symlink | | **Claude Code** | User-level skills not loaded when `~/.claude/skills` is a symlink, reported as a regression since ~v2.1.69 | [`anthropics/claude-code` #38051](https://github.com/anthropics/claude-code/issues/38051) — closed | | **OpenClaw** | Symlinks are *permitted* but contained: discovery only accepts roots whose resolved realpath stays inside the configured root, unless `skills.load.allowSymlinkTargets` trusts it explicitly | Documented | | **Cursor** | Not documented | — | If you keep a skills library in one place and link it into projects, this is the first thing to rule out. **Diagnosis:** replace the symlink with a real directory as a test; if the skill appears, you've found it. ### Other discovery failures reported in Claude Code All **verified issues**. Each is a single vendor and, in several cases, a single reporter — check whether your version and platform match before assuming it applies. | Symptom | Issue | State | |---|---|---| | Skills and agents skipped with "same inode already loaded" despite unique inodes — one reporter saw 7 of 14 skills and 5 of 9 agents fail | [#17078](https://github.com/anthropics/claude-code/issues/17078) | Closed; comments report it persisting on the native install | | Project skills not loaded when `.claude/` sits in a subdirectory | [#42573](https://github.com/anthropics/claude-code/issues/42573) | Closed | | Skills not loaded from `CLAUDE_CONFIG_DIR` — path hardcoded to `~/.claude/skills/` | [#31649](https://github.com/anthropics/claude-code/issues/31649) | Closed | | Skills load from `--add-dir` but not from `additionalDirectories` | [#37553](https://github.com/anthropics/claude-code/issues/37553) | Closed | ### You're looking in a directory the runtime doesn't scan The most common version of this is simply not knowing the full list. Every runtime scans more than one location, and two of them scan each other's: | Runtime | Where skills are found | Full detail | |---|---|---| | **Claude Code** | `~/.claude/skills/`, `.claude/skills/`, plugin skills, enterprise managed settings — with a precedence chain | [Claude Code skills](/claude-code-skills/#where-skills-live) | | **Codex** | `$HOME/.agents/skills`, `.agents/skills` up the project chain, plus the deprecated `~/.codex/skills` that the installer still writes to | [Codex skills](/codex-skills/#every-location-codex-scans) | | **Cursor** | Eight roots — its own four, **plus** `.claude/skills/`, `.codex/skills/` and their home equivalents | [Cursor skills](/cursor-skills/#where-cursor-looks-for-skills) | | **OpenClaw** | Six roots in a documented precedence order; `.openclaw/skills` is **not** one of them | [OpenClaw skills](/openclaw-skills/#where-openclaw-loads-skills-from) | | **Hermes Agent** | `~/.hermes/skills/`, plus `external_dirs` in `config.yaml` | [Hermes Agent skills](/hermes-agent-skills/#where-skills-live) | ### Frontmatter that looks fine but isn't YAML is unforgiving in ways that don't show up visually. In [#9716](https://github.com/anthropics/claude-code/issues/9716) a reporter described frontmatter copied straight from the documentation being rejected; asking Claude to compare it against the spec produced a rewrite that was, in the reporter's words, "identical to my eyes" — after which the skill worked consistently. **Verified issue** (open since October 2025). The two required fields are `name` and `description`. If in doubt, retype the frontmatter block by hand rather than copying it, and validate with `skills-ref validate ./my-skill` from the standard's reference library. --- ## Class 2: the skill loads but never fires If `/skill-name` works and automatic invocation doesn't, the problem is upstream of the runtime — the agent is deciding your skill isn't relevant. ### The description is doing all the work At startup an agent loads only each skill's `name` and `description`. Everything else stays on disk. The specification is explicit that this is the whole basis for the decision, and the standard's own guidance puts it plainly: the description "carries the entire burden of triggering." Three things follow, all **documented**: **Write it as an instruction, not a summary.** "Use this skill when…" rather than "This skill does…". The agent is deciding whether to act. **Describe the user's intent, not your implementation.** The match is against what the user asked for, not against how the skill works internally. **Name the situations explicitly, including indirect ones.** The standard suggests being deliberately pushy — listing contexts where the skill applies "even if they don't explicitly mention" the domain by name. ```yaml # Weak — describes the artifact description: A skill for working with our deployment system. # Better — describes the trigger description: Deploy or roll back a service to staging or production. Use when asked to ship, deploy, release, revert, or roll back, even if the environment isn't named. ``` ### The task may be too small to warrant a skill A subtlety worth knowing before you rewrite a description that isn't broken. Per the standard, agents typically consult skills only for tasks needing capability beyond what they can already do — so a simple, one-step request may not trigger a skill even when the description matches perfectly. **Documented.** If your skill covers something the agent can handle unaided, low trigger rates may be correct behaviour rather than a bug. ### Something else in context outranks it The most under-reported cause we found. In [#9716](https://github.com/anthropics/claude-code/issues/9716), a reporter found that an instruction in `CLAUDE.md` covering the same task was treated as "having higher salience than the skills trigger" — the always-on instruction won, and the skill never loaded. **Verified issue.** This is the practical edge of a distinction the rest of this site covers at length: persistent instruction files and skills are different mechanisms, and when both describe the same job they compete. If you have a `CLAUDE.md`, `AGENTS.md`, or a Cursor rule covering the same ground as a skill, that overlap is a live suspect. See [Codex skills vs AGENTS.md](/codex-skills-vs-agents-md/) and [Cursor skills vs rules](/cursor-skills-vs-rules/). ### Testing triggering instead of guessing Model behaviour is non-deterministic, so a single test proves little. The standard documents a real method: build roughly 20 realistic prompts labelled for whether they *should* trigger the skill, run each several times, and compute a **trigger rate**. The valuable half is the negatives. Weak negatives ("write a fibonacci function") test nothing. Strong ones are near-misses that share vocabulary but need something different — for a CSV-analysis skill, "update the formulas in my Excel budget" shares the spreadsheet concept but isn't the job. **Documented method, not our measurement.** We have not run these evals, and we publish no trigger rates of our own. ### Invocation is switched off Check whether the skill has opted out of automatic selection. `disable-model-invocation: true` keeps a skill reachable by command while removing it from model-initiated selection — supported in Cursor, OpenClaw and Claude Code. In OpenClaw it also hides the skill from the `$` picker. Codex has the equivalent in `agents/openai.yaml` as `policy.allow_implicit_invocation: false`. Migration tools set this for you: Cursor's `/migrate-to-skills` converts slash commands into skills with `disable-model-invocation: true`, and OpenClaw's Claude import does the same for `.claude/commands/` files. If a skill arrived via migration and never fires on its own, this is why. **Documented.** --- ## Class 3: it worked, then stopped ### The catalogue was dropped from context If a skill worked earlier in a long session and then stopped, suspect compaction rather than configuration. [`anthropics/claude-code` #74990](https://github.com/anthropics/claude-code/issues/74990) reports that both `/compact` and auto-compaction remove the entire Available skills block from context — not some skills, the whole catalogue. Running `/reload-skills` afterwards prints `33 skills available (no changes)`, confirming the registry on disk is intact while the model still can't see it. **Verified issue** (open, July 2026). **Diagnosis:** if a skill stops working mid-session and nothing on disk changed, start a new session before changing anything. ### Too many skills for the budget Skill descriptions share a fixed budget, and past it, skills are silently excluded. | Runtime | Documented budget | |---|---| | **Codex** | 2% of the context window or 8,000 characters, whichever is smaller | | **OpenClaw** | ~97 characters per skill plus field lengths, against a configurable `skills.limits.maxSkillsPromptChars`; degrades by shortening then dropping descriptions | | **Claude Code** | Approximately 1% of context for the index | | **Cursor** | No figure published | [#40774](https://github.com/anthropics/claude-code/issues/40774) is the practical illustration: a reporter with nine plugin skills saw about two reach chat, attributed it to a ~1% / ~8,000-character budget, and found the workaround was keeping descriptions under 200 characters with key terms front-loaded. **The budget attribution there is the reporter's, not vendor documentation** — but it points the same way as the two runtimes that publish figures. So a long description costs twice: it consumes budget in every session, and past the ceiling it can be the thing that gets cut. ### The runtime hasn't reloaded | Runtime | Refresh model | |---|---| | **OpenClaw** | Snapshots eligible skills at session start; a `SKILL.md` watcher can refresh mid-session, picked up on the next turn | | **Claude Code** | Watches skill directories within a session; a brand-new top-level skills directory needs a restart | | **Codex** | Documentation says to restart after changes | | **Cursor** | Not documented | **Diagnosis:** when a skill doesn't appear after an edit, a new session is the cheapest way to eliminate this whole class. --- ## Class 4: the file is fine, but not here Some skills are portable and some aren't, and the failure is silent either way. ### `paths` breaks discovery in Claude Code The sharpest example we found, and a genuine trap for anyone writing skills for more than one agent. `paths` is a **Cursor** frontmatter field that scopes a skill to files matching glob patterns. Add it to a skill in Claude Code and, per [#49835](https://github.com/anthropics/claude-code/issues/49835), the skill becomes *entirely undiscoverable* — absent from `/` autocomplete, unlisted as available, and returning `Unknown skill` on direct invocation. Removing the single line restores it. **Verified issue** (open, April 2026). Nothing in either vendor's documentation tells you this, because it's only visible from both sides at once. ### Runtime-only fields in general These do not travel. A skill using them still works in its home runtime and may silently underperform or fail elsewhere: | Field | Belongs to | |---|---| | `paths` | Cursor | | `metadata.openclaw.*`, `command-dispatch`, `user-invocable` | OpenClaw | | `agents/openai.yaml` | Codex | | `context: fork`, `background` | Claude Code | | `metadata.hermes.*` | Hermes Agent | | `allowed-tools` | In the spec, but marked **experimental**, with support that "may vary between agent implementations" | The portable core is `name`, `description`, the markdown body, and the `scripts/`, `references/`, `assets/` convention. [Agent Skills compatibility](/agent-skills-compatibility/) covers what travels in detail. ### You're on a different surface than you think Within a single product family, skills don't always follow you. In the Claude Code family there are reports of skills enabled on claude.ai not loading in web sessions ([#75261](https://github.com/anthropics/claude-code/issues/75261), open), the VS Code extension checking only filesystem paths and so missing organisation-level skills ([#65021](https://github.com/anthropics/claude-code/issues/65021), closed), and Cowork resolving skills from a deployment mount rather than local `~/.claude/skills` ([#76724](https://github.com/anthropics/claude-code/issues/76724), open). **Verified issues.** If a skill works in the CLI and not in the IDE or the web app, that's the class to look at. --- ## A correction worth making Search results for this problem currently propagate a wrong root cause. Issue #17417's *body* contains a detailed analysis blaming `/tmp/claude/` permissions — root-owned directory, `EACCES` on `mkdir`, "fails silently when it cannot create the necessary directories." That analysis is quoted in third-party troubleshooting articles and, at the time of writing, was reflected in Google's AI summary for this topic. The issue's *resolution*, posted by the same reporter, was filename case: `skill.md` instead of `SKILL.md`. Both facts are in the same issue. Only one of them is the answer. It's worth checking bug reports to the end before treating a preliminary hypothesis as a documented cause — including the ones on this page. ## Caveats - We have not run any of these agents, installed any skill, or reproduced any failure. Every cause is documented behaviour, a public issue read to resolution, or labelled diagnosis. - GitHub issues carry state and version where the reporter supplied one. A closed issue may still describe behaviour you hit on an older version; an open one may be narrow. Several are single-reporter. - Runtime behaviour here reflects documentation and issues as of **16 August 2026**. These products ship weekly. ## Sources - [Agent Skills — Specification](https://agentskills.io/specification) and [Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) - [`anthropics/claude-code` issues](https://github.com/anthropics/claude-code/issues) — #9716, #17078, #17417, #31649, #37553, #38051, #40774, #42573, #49835, #65021, #74990, #75261, #76724 - [`openai/codex` issue #11314](https://github.com/openai/codex/issues/11314) - Runtime documentation for [Claude Code](https://code.claude.com/docs/en/skills), [Codex](https://developers.openai.com/codex/skills), [Cursor](https://cursor.com/docs/context/skills), [OpenClaw](https://docs.openclaw.ai/tools/skills), and [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) --- ## Agent Skills vs MCP **Skills and MCP are two layers of the same stack, not two options.** MCP gives an agent access to a system. A skill gives it the judgement to use that access well. You will normally want both, and the interesting question isn't "which one" — it's how they compose. That framing is not new, and the pages already ranking for this question mostly get it right. What's missing from them is evidence. This page argues it from artifacts you can open yourself, and covers the part almost nobody has picked up: as of 2026, there is a published standard whose entire job is packaging skills and MCP servers into one distributable unit. **Scope:** this page is about the relationship between the two layers. It is not an MCP tutorial, and it is not a list of MCP servers worth installing — that's a different site's job. ## The structural difference, stated once | | Agent Skill | MCP server | |---|---|---| | What it is | A folder with a `SKILL.md` file, plus optional scripts, references, and assets | A process or remote endpoint speaking the Model Context Protocol | | What it provides | Instructions: procedure, judgement, constraints, worked examples | Tools: typed, schema-validated operations | | Where it runs | Inside the agent's own environment | Its own process or a remote service | | How the agent uses it | Reads it, then acts | Calls it | | Cost when unused | Name and description only | Configuration and, usually, a connection | | Portability | The same file works across [many agents](https://agentskills.io) | The protocol is shared; per-client configuration is not | | How you review it | Read the text and any bundled scripts | Decide what you're willing to connect it to | The last row is the one that gets least attention and matters most in practice. Reviewing a skill is a reading exercise. Reviewing an MCP server is an authorisation decision. Those are different jobs with different failure modes, which is a large part of why treating them as alternatives goes wrong. ## Four artifacts that show the layering None of this is analogy. These are files in public repositories and fields in published documentation. ### A Codex skill declaring an MCP server as a dependency Codex skills can carry an optional `agents/openai.yaml`. Among its blocks: ```yaml dependencies: tools: - type: "mcp" value: "openaiDeveloperDocs" ``` The skill declares that it needs an MCP server present. It doesn't contain the server, replace it, or wrap it — it depends on it. See [Codex skills](/codex-skills/#the-optional-codex-specific-metadata). ### An OpenClaw skill whose entire job is driving MCP servers OpenClaw ships a bundled skill called `mcporter`. Its frontmatter, read from the repository: ```yaml --- name: mcporter description: "List, configure, authenticate, call, and inspect MCP servers/tools with mcporter over HTTP or stdio." homepage: http://mcporter.dev metadata: { "openclaw": { "requires": { "bins": ["mcporter"] } } } --- ``` This is the relationship in its most literal form: a skill that exists to teach the agent how to work with MCP. Note also the gating — the skill only appears when the `mcporter` binary is present, which is the skills layer managing its own relevance rather than the MCP layer doing anything. See [OpenClaw skills](/openclaw-skills/#skills-vs-plugins-vs-mcp-in-openclaw). ### n8n hooks that fire skill guidance immediately before MCP tool calls The most precise demonstration we found. n8n publishes an official skills pack for coding agents, and its `hooks/hooks.json` registers PreToolUse hooks matched against MCP tool names: ```json { "PreToolUse": [ { "matcher": "^mcp__.*__validate_workflow$", "hooks": [ ... ] }, { "matcher": "^mcp__.*__create_workflow_from_code$", "hooks": [ ... ] }, { "matcher": "^mcp__.*__update_workflow$", "hooks": [ ... ] }, { "matcher": "^mcp__.*__get_node_types$", "hooks": [ ... ] } ] } ``` The pattern is unambiguous: MCP exposes the capability, and the skills layer injects the relevant guidance *at the moment the agent is about to use it*. The pack's own router skill states the reasoning plainly — n8n evolves faster than any model's training cutoff, so the agent should trust the skills and the live MCP tools over recollection. Access and judgement, wired together, in a shipping repository. ### A Cursor plugin that is MCP and nothing else Cursor's official marketplace repository contains this, in full, as the Gmail plugin's `mcp.json`: ```json { "mcpServers": { "gmail": { "type": "http", "url": "https://gmailmcp.googleapis.com/mcp/v1" } } } ``` No `skills/` directory. Meanwhile Cursor's first-party plugins — `thermos`, `cursor-team-kit`, `agent-compatibility` — carry `skills/` and no MCP server. One packaging format, two independent payloads, and plenty of plugins carrying only one of them. ## The part that's missing everywhere: Agent Plugins If skills and MCP servers are complementary layers, something has to ship them together. As of 2026 that something is a published standard. **Agent Plugins** ([agent-plugins.org](https://agent-plugins.org)) describes itself as "an open, vendor-neutral standard for packaging reusable components that extend AI agents into distributable plugins. It defines a portable package format for Agent Skills and MCP servers." Specification **1.0.0** is the current published release, and the initial technical steering committee lists core maintainers from Amazon, Cursor, Microsoft, OpenAI, and Vercel. The portable layout: ```text my-plugin/ ├── plugin.json # identifies the plugin and the spec version it targets ├── skills/ │ └── greet/ │ └── SKILL.md # Agent Skills format ├── mcp.json # stdio, Streamable HTTP, or legacy HTTP+SSE servers └── com.example.client/ # reverse-domain namespaces for client-specific extras ``` Two details make the design argument for you. **Both component types are optional.** The specification's own quick-start example is a `plugin.json` and a single skill, with no `mcp.json` at all. A plugin can be all skills, all MCP, or both. That is what a genuine layering looks like in a format — independent, composable pieces, not one wrapped in the other. **Client-specific behavior is quarantined.** Reverse-domain namespaces let a client add its own extensions "without changing the portable core," which is the same instinct that keeps `SKILL.md` portable while [Cursor adds `paths`](/cursor-skills/#the-frontmatter-including-two-fields-that-are-cursors-alone) and [OpenClaw adds `command-dispatch`](/openclaw-skills/#the-frontmatter). Adoption is real but worth stating precisely: Cursor's documentation confirms that "Agent Plugins use a root `plugin.json` manifest and load in Cursor without modification." We have not verified conformant support in other clients, and TSC membership is not the same as shipped support — so treat this as a standard with one confirmed loader we checked, not a universal one. The related pattern is visible elsewhere too. Claude Code documents that a skill folder with a `.claude-plugin/plugin.json` "loads as a plugin … so it can bundle agents, hooks, and MCP servers." Same idea, house format. ## So when do you reach for which? Given the above, "skills or MCP" is usually the wrong question. The useful ones: **Does the agent need to *do* something it currently can't reach?** That's MCP. Query a database, call an API, read a SaaS system, act on live state with real auth. No amount of instruction gets an agent into a system it has no connection to. **Does the agent already have the access but keeps doing the job badly?** That's a skill. It calls the right tool with the wrong parameters, skips validation, doesn't know your conventions, or reinvents a decision it should have inherited. That is a knowledge problem, and connecting another server won't fix it. **Both, usually.** The n8n pack is the clean illustration: an MCP server exposing workflow operations, and a skills pack that makes an agent use them competently. Either half alone underperforms. Two follow-on consequences worth planning around: - **Portability.** A `SKILL.md` written to the [portable spec](https://agentskills.io/specification) — `name`, `description`, optionally `license`, `compatibility`, `metadata` — runs across a long list of agents unchanged. [Cursor even reads Claude Code's and Codex's skill directories directly](/cursor-skills/#where-cursor-looks-for-skills). There is no equivalent for MCP server configuration, and a skill that assumes a particular server is present is only as portable as that server. - **Review burden.** A skill is text you can read in ten minutes; that's also its weakness, since a convincing paragraph is exactly what prompt injection looks like and no scanner catches prose reliably. ClawHub's audit framing names the whole class — "prompt injection, tool misuse, credential exposure, unsafe execution, memory or context poisoning, and excessive agency" — using the [OWASP Agentic Skills Top 10](https://owasp.org/www-project-agentic-skills-top-10/) as its lens. An MCP server is the opposite: less prose to read, but a credential and a network boundary to decide about. See [are OpenClaw skills safe?](/openclaw-skills-security/) for how one registry handles the first half. ## The one-line version MCP decides what an agent *can* do. Skills decide what it *should* do, and how. Agent Plugins is how you hand someone both at once. ## Caveats - We have not run any MCP server, installed any plugin, or used any of the skills referenced here. Every claim is documented behavior or read directly from a public repository, and the source is named in each case. - Agent Plugins 1.0.0 support is confirmed for Cursor from Cursor's own documentation. We did not verify conformant support in other clients, despite the breadth of the steering committee. - The n8n hook matchers are read from `n8n-io/skills`. That ecosystem's full treatment isn't published on this site yet; the file is cited here as evidence, not as a guide to using it. - The security and portability comparisons are our synthesis of separately documented facts, not vendor guidance. - Specification version, repository details, and documentation quoted here are current as of **16 August 2026**. ## Sources - [Agent Plugins](https://agent-plugins.org) and [`agentplugins/agent-plugins-spec`](https://github.com/agentplugins/agent-plugins-spec) — specification 1.0.0, package layout, governance - [agentskills.io — specification](https://agentskills.io/specification) — the portable skill format and its progressive-disclosure model - [Cursor — Plugins (official docs)](https://cursor.com/docs/plugins) — Agent Plugins support and plugin structure - [`cursor/plugins` (GitHub)](https://github.com/cursor/plugins) — `third_party/gmail/mcp.json` and the first-party plugins carrying `skills/`, read directly - [`openclaw/openclaw` (GitHub)](https://github.com/openclaw/openclaw) — `skills/mcporter/SKILL.md`, read directly - [`n8n-io/skills` (GitHub)](https://github.com/n8n-io/skills) — `hooks/hooks.json` PreToolUse matchers, read directly - [Codex — Build skills (official docs)](https://developers.openai.com/codex/skills) — `agents/openai.yaml` MCP dependency declaration - [Claude Code — Skills (official docs)](https://code.claude.com/docs/en/skills) — skill folders that load as plugins bundling MCP servers - [ClawHub — Security Audits (official docs)](https://docs.openclaw.ai/clawhub/security-audits) — the skill-side risk taxonomy --- ## SKILL.md: The Agent Skill File Format A **SKILL.md** is a markdown file with YAML frontmatter that turns a folder into an agent skill. The frontmatter tells an agent when the skill is relevant; the body tells it what to do once it is. ```yaml --- name: deploy-staging description: Deploy or roll back a service to staging. Use when asked to ship, deploy, release, or revert. --- Step-by-step instructions for the agent to follow. ``` That is a complete, valid skill. Two fields and a body — everything else is optional. The format is the [Agent Skills open standard](https://agentskills.io), developed at Anthropic and released for anyone to implement. It is now read by a long list of agents, which is what makes the file portable: the same `SKILL.md` runs in Claude Code, Codex, Cursor, OpenClaw and others without modification. ## The directory A skill is a folder, not just a file. The conventions: ```text my-skill/ ├── SKILL.md # required ├── scripts/ # optional: executable code the agent can run ├── references/ # optional: documentation loaded on demand └── assets/ # optional: templates, images, data files ``` Only `SKILL.md` is required, and the folder may contain anything else you need. The three named directories are conventions the spec recommends rather than a rigid schema — but they map onto how agents load material, which is the next section. ## Frontmatter, with the constraints that actually bite | Field | Required | Constraint | |---|---|---| | `name` | Yes | 1–64 characters. Lowercase letters, digits and hyphens only. No leading, trailing or consecutive hyphens. **Must match the parent directory name** | | `description` | Yes | 1–1024 characters. What the skill does *and when to use it* | | `license` | No | A licence name, or a reference to a bundled licence file | | `compatibility` | No | Up to 500 characters. Environment requirements — intended product, system packages, network access | | `metadata` | No | A map of string keys to string values. Where runtimes put their own extensions | | `allowed-tools` | No | Space-separated list of pre-approved tools. **Experimental** | Two of these deserve more than a table row. **`name` must match the folder.** A mismatch is a silent failure, and so is the wrong filename case — `skill.md` rather than `SKILL.md` is one of the most commonly reported causes of a skill never appearing. See [agent skills not working](/agent-skills-not-working/#filename-case). **`allowed-tools` is experimental**, and the specification says support "may vary between agent implementations." It is the field people reach for when they want to constrain what a skill can do, and it is the least reliable field in the format. Do not treat it as a security control. ## How agents load a skill The format is built around **progressive disclosure** — three stages, so that a large skill library costs almost nothing until it's needed: | Stage | What loads | Cost | |---|---|---| | **Discovery** | `name` and `description` only, for every installed skill | ~100 tokens per skill | | **Activation** | The full `SKILL.md` body, when a task matches | Recommended under 5,000 tokens | | **Execution** | Files in `scripts/`, `references/`, `assets/` | Only when the instructions call for them | This is the single most important thing to understand about the format, because it explains the two rules that otherwise look arbitrary. **Why the description carries so much weight.** At discovery time it's the *only* thing the agent sees. It is not a summary for humans; it is the entire basis on which the agent decides whether to read the rest. **Why `SKILL.md` should stay short.** The spec recommends keeping it under 500 lines and moving detail into `references/`. A long body isn't just untidy — it's loaded in full the moment the skill activates. ## What's standardised, and what isn't Here is where the specification stops and reality starts. Every runtime that implements the standard adds things, and those additions are the reason a "portable" skill sometimes isn't. ### Where skills live is not standardised at all The spec says nothing about directories. Every runtime chose its own, and the results are genuinely different: | Runtime | Roots | Notable | |---|---|---| | **Claude Code** | `~/.claude/skills/`, `.claude/skills/`, plugin skills, enterprise settings | Documented precedence chain; nested project scoping | | **Codex** | `$HOME/.agents/skills`, `.agents/skills` up the project chain | Also scans `~/.codex/skills`, which its own source marks deprecated | | **Cursor** | Eight roots | Reads `.claude/skills/` and `.codex/skills/` for compatibility | | **OpenClaw** | Six roots, in a documented precedence order | Explicitly refuses Codex's root; offers a migration command instead | | **Hermes Agent** | `~/.hermes/skills/` plus configured `external_dirs` | Category-organised | One convention has emerged from the bottom up rather than from the spec: **`.agents/skills`** is read natively by Codex, Cursor and OpenClaw. A skill kept there is shared across three runtimes with no copying. That's the closest thing to a portable location the ecosystem has. Full detail per runtime is in each cluster: [Claude Code](/claude-code-skills/), [Codex](/codex-skills/), [Cursor](/cursor-skills/), [OpenClaw](/openclaw-skills/), [Hermes](/hermes-agent-skills/). ### The context budget is not standardised Discovery costs tokens, so runtimes cap the index — with different numbers, and one publishing none: | Runtime | Documented budget | |---|---| | Codex | 2% of the context window or 8,000 characters, whichever is smaller | | Claude Code | Approximately 1% of context | | OpenClaw | ~97 characters per skill plus field lengths, against a configurable ceiling; degrades by shortening then dropping descriptions | | Cursor | None published | This is why description-length advice varies so widely. The spec permits 1,024 characters; OpenClaw's own authoring guide asks for under 160; practical reports in Claude Code suggest under 200 when running many skills. All three are correct for their runtime. ### Invocation is not standardised | Runtime | Explicit invocation | |---|---| | Claude Code, Cursor | `/skill-name` | | Codex | `$skill-name` in the CLI and IDE; `@skill-name` in ChatGPT | | OpenClaw | `$name` as a composable reference in a message, `/name` as a standalone command, up to eight per message | Automatic invocation — the agent choosing a skill from its description — exists everywhere, but the control for turning it off is spelled differently in each: `disable-model-invocation` in Cursor, OpenClaw and Claude Code; `policy.allow_implicit_invocation` in Codex's `agents/openai.yaml`. ### Name collisions are not standardised Install the same skill name twice and behaviour diverges sharply. Claude Code applies a precedence chain (enterprise over personal over project). OpenClaw takes the highest-priority root. Codex shows **both, without merging**. Cursor documents nothing. ### Runtime-specific frontmatter Each runtime extends the format. These fields work at home and travel nowhere: | Field | Runtime | What it does | |---|---|---| | `paths` | Cursor | Scopes a skill to files matching glob patterns — triggering on files touched rather than on phrasing | | `metadata.openclaw.requires` / `os` / `install` | OpenClaw | Dependency gating; a skill hides when its binary, env var or platform is absent | | `command-dispatch: tool` | OpenClaw | The slash command bypasses the model entirely | | `agents/openai.yaml` | Codex | UI metadata, invocation policy, MCP dependencies | | `context: fork` | Claude Code | The skill runs as a forked subagent | | `metadata.hermes.requires_toolsets` | Hermes Agent | Conditional activation against available toolsets | Most of these degrade harmlessly — another runtime ignores what it doesn't recognise. **One does not.** Adding Cursor's `paths` field to a skill in Claude Code makes it entirely undiscoverable, per a [public issue read to resolution](/agent-skills-not-working/#paths-breaks-discovery-in-claude-code). That is the sharpest portability trap in the format, and it's invisible from either vendor's documentation alone. ## Validating a skill The standard ships a reference library for checking frontmatter and naming conventions: ```bash skills-ref validate ./my-skill ``` It checks the format, not the behaviour. Whether the description actually triggers is a separate question with [its own method](/agent-skills-not-working/#testing-triggering-instead-of-guessing). This site publishes a browser-based checker built on the same field constraints as the table above, plus what's documented for portability across the five runtimes it covers: [the SKILL.md validator](/skill-md/validate/). Every rule it checks has its own reference page at [`/skill-md/rules/`](/skill-md/rules/), sourced the same way as this page. ## What SKILL.md is not Three distinctions that account for most of the confusion around the format: **Not a persistent instruction file.** `AGENTS.md`, `CLAUDE.md` and Cursor rules load on every task; a skill loads when it's relevant. The difference is context cost, and it's the whole basis for choosing between them — see [Codex skills vs AGENTS.md](/codex-skills-vs-agents-md/) and [Cursor skills vs rules](/cursor-skills-vs-rules/). **Not an MCP server.** MCP gives an agent access to a system; a skill gives it the judgement to use that access well. They are complementary layers, and there is now a standard that packages both together — [Agent Skills vs MCP](/agent-skills-vs-mcp/). **Not a plugin.** A plugin is an envelope. It may contain skills, MCP servers, both, or neither — many published plugins contain no skills at all. ## Caveats - We have not run any of these runtimes. Everything here is the published specification or documented runtime behaviour, with per-runtime detail carried from the research behind each cluster. - The standard's origin date is not stated here. Secondary sources give conflicting dates and we could not confirm either against a primary source; rather than pick one, we've left it out. - Runtime behaviour, budgets and field sets are as documented on **16 August 2026**. These products ship frequently, and the divergences above are the fastest-moving part of this page. ## Sources - [Agent Skills — Specification](https://agentskills.io/specification) — fields, constraints, directory conventions, progressive disclosure, validation - [Agent Skills — Overview](https://agentskills.io) and the [client showcase](https://agentskills.io/clients) - Runtime documentation: [Claude Code](https://code.claude.com/docs/en/skills), [Codex](https://developers.openai.com/codex/skills), [Cursor](https://cursor.com/docs/context/skills), [OpenClaw](https://docs.openclaw.ai/tools/skills), [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) --- ## Where to Find Agent Skills Start with what you already have. Every agent covered on this site ships skills you don't install — Cursor has 19 built in, OpenClaw bundles 51, Claude Code and Codex both ship their own. Those need no trust decision from you, and a surprising amount of what people go looking for is already sitting in the box. For everything else, the useful question isn't "which directory has the most skills." It's **who vouches for this, and what happens if they're wrong.** ## The seven kinds of source | Kind | Who vouches | Examples | |---|---|---| | **Bundled catalogue** | The runtime vendor | Cursor's 19 built-ins, OpenClaw's 51, Claude Code's bundled skills, Codex's samples | | **Vendor plugin marketplace** | The vendor, with review | Cursor Marketplace, `claude-plugins-official`, `claude-plugins-community` | | **Open registry** | Nobody by default; automated scanning | ClawHub, skills.sh | | **Cross-agent installer** | Nobody — it's a transport | `npx skills` | | **Vendor skill pack** | The product whose domain it covers | `n8n-io/skills`, `NVIDIA/skills`, `trailofbits/skills`, `supabase/agent-skills` | | **Curated community list** | A maintainer's judgement | `VoltAgent/awesome-agent-skills`, `spencerpauly/awesome-cursor-skills` | | **Third-party directory** | Nobody; aggregated listings | SkillsMP, LobeHub Skills, and similar | The rest of this page is what separates them. ## Bundled catalogues Already installed, vendor-maintained, and the only category with no supply-chain question at all. Also the most overlooked — several runtimes ship skills for jobs people go hunting for. Worth knowing: bundled skills can be *conditionally hidden*. OpenClaw gates most of its 51 on a binary, an environment variable, or an operating system, so a skill you can't see may be working exactly as designed rather than missing. See [the OpenClaw catalogue](/best-openclaw-skills/) and, for the others, [Claude Code](/best-claude-code-skills/), [Codex](/best-codex-skills/), [Cursor](/best-cursor-skills/) and [Hermes](/best-hermes-agent-skills/). ## Vendor plugin marketplaces The strongest trust signal available, because a named party stands behind the listing and applies a process before publication. - **Cursor Marketplace** — Cursor's documentation states all listed plugins undergo manual review. The public repository is [`cursor/plugins`](https://github.com/cursor/plugins) (MIT). - **Claude Code marketplaces** — `claude-plugins-official` is curated by Anthropic and added automatically on first interactive launch; `claude-plugins-community` accepts submissions that pass automated validation and safety screening, pinned to a commit SHA. One structural caveat: a plugin is a packaging format, not a guarantee of contents. Reading the manifests in `cursor/plugins` directly, most of the third-party integrations there are MCP-only — a `plugin.json` and an `mcp.json` with no `skills/` directory at all. "Available in the marketplace" doesn't mean "is a skill." See [Agent Skills vs MCP](/agent-skills-vs-mcp/). ## Open registries Anyone can publish. What differs is what happens after they do. **ClawHub** ([clawhub.ai](https://clawhub.ai)) is the most developed model. Publishing requires a GitHub account old enough to pass an upload gate — a spam gate, not a review. The real screening is an automated audit whose result is public on every listing, combining SkillSpector, VirusTotal and ClawHub's own ClawScan, and reported as an **audit status** (`Pass` / `Review` / `Warn` / `Malicious` / `Pending` / `Error`) alongside a separate **risk level** (`Low` / `Medium` / `High`). Those two answer different questions, and conflating them is the common mistake. In ClawHub's own words: risk level asks how much power is here; audit status asks what you should do about it. A publishing skill sitting at `Review` / `Medium` isn't a warning — it means the skill can act with real account authority and you should decide whether you want that. The full treatment is on [are OpenClaw skills safe?](/openclaw-skills-security/). **skills.sh** is run by Vercel and takes the opposite approach: no audit layer, but public install counts and topic browsing. It's the discovery front-end for the `npx skills` installer below. ## Cross-agent installers [`npx skills`](https://github.com/vercel-labs/skills) (Vercel Labs, MIT, ~29,000 stars as of 16 August 2026) is a transport rather than a source. Its README states support for 76 agents, and it installs from GitHub shorthand, full URLs, GitLab, any git URL, or a local path — including private repositories using your existing git credentials. Two options change what you get: - `--copy` copies files instead of symlinking them into agent directories. Given that [symlinked skill roots break discovery in both Codex and Claude Code](/agent-skills-not-working/#a-path-the-runtime-wont-follow), this flag is worth knowing about before you need it. - `skills use` generates a prompt from a skill without installing it at all. ## Vendor skill packs A distinct and under-appreciated category: a product publishing official skills **for other agents to load**, rather than implementing skills itself. | Pack | Stars | Licence | Pushed | |---|---|---|---| | [`VoltAgent/awesome-agent-skills`](https://github.com/VoltAgent/awesome-agent-skills) | 30,389 | MIT | 2026-08-16 | | [`NVIDIA/skills`](https://github.com/NVIDIA/skills) | 2,967 | Apache-2.0 | 2026-08-14 | | [`trailofbits/skills`](https://github.com/trailofbits/skills) | 6,612 | CC-BY-SA-4.0 | 2026-08-14 | | [`supabase/agent-skills`](https://github.com/supabase/agent-skills) | 2,522 | MIT | 2026-08-12 | | [`n8n-io/skills`](https://github.com/n8n-io/skills) | 431 | Apache-2.0 | 2026-08-15 | | [`PostHog/skills`](https://github.com/PostHog/skills) | 59 | MIT | 2026-08-16 | *Repository metadata read via the GitHub API on 16 August 2026; these figures drift.* Their appeal is provenance: the organisation that owns the domain wrote the skill. Their catch is that many carry prerequisites — n8n's pack requires an n8n instance with instance-level MCP enabled before any of its 14 skills does anything useful. Read the README before installing. ## Curated community lists A maintainer's taste, expressed as a repository. Useful for the same reason any awesome-list is useful, and unreliable in the same ways. `VoltAgent/awesome-agent-skills` is the largest general one; `spencerpauly/awesome-cursor-skills` (694 stars, CC0-1.0) is the strongest Cursor-specific one; `travisvn/awesome-claude-skills` (14,671 stars, no declared licence) is the Claude-oriented equivalent. Skill counts advertised in these READMEs are the maintainers' own claims and we have not audited them. ## Third-party directories Aggregators that index skills from elsewhere and present them with their own search and categorisation. They are genuinely useful for discovery and genuinely unreliable as evidence of anything: a listing count is inventory, not adoption, and the aggregator is rarely the party that would fix a bad skill. Treat a directory as a search index that points at a repository, then evaluate the repository. --- ## What the popularity numbers actually count This is the part worth reading before you rank anything by "downloads." | Signal | What it measures | What it does not | |---|---|---| | **skills.sh install counts** | Platform-reported installs through its own tooling | Usage, retention, or quality | | **ClawHub install counts** | Best-effort telemetry from `clawhub install` **while logged in**, disableable via `CLAWHUB_DISABLE_TELEMETRY=1` | Anything installed by other means — it is a floor, not a census | | **GitHub stars** | Attention paid to a *repository* | Installs of any individual skill inside it | | **Directory listing counts** | Inventory the aggregator has indexed | Adoption, and usually unverified | | **Everything else** | — | There is no telemetry at all | Two consequences. First, these are not comparable: a registry's install count and a repository's star count are different units and lining them up in one table produces a meaningless ranking. Second, most of the ecosystem has no popularity signal whatsoever, which is why every "best skills" page on this site states its evidence rather than implying a leaderboard. We are deliberately not quoting current install totals here. The figures published on these surfaces move constantly, and the ones we observed on 16 August 2026 were internally inconsistent within a single reading — worth verifying at the source rather than trusting a number copied into an article weeks ago. ## Evaluating a source before you install from it The checklist is the same one this site applies per-ecosystem, and it doesn't change with the source: 1. **Read the `SKILL.md` in full.** It's the artifact. If it's too long to read, it's too long to trust. 2. **Read everything in `scripts/`.** Bundled executables are the real risk surface, and no automated audit reliably catches a well-written malicious instruction — ClawHub's own documentation says its audits "are not a guarantee that a release is risk-free." 3. **Check that declared credentials match the job.** A skill requesting environment variables it has no visible use for is the clearest red flag available. 4. **Check the description for negative triggers.** Good skills say when *not* to fire; it's a strong proxy for author care. 5. **Check freshness and licence.** Both are visible in seconds and both matter. Two pages on this site work through that reasoning in more depth, with the runtime-specific risk model attached: [evaluating Claude Code skill repositories](/claude-code-skills-github/) and [evaluating Hermes skill repositories](/hermes-agent-skills-github/). ## Will it work in your agent? A skill found in one place doesn't automatically run everywhere. The portable core — `name`, `description`, the markdown body, and the `scripts/` / `references/` / `assets/` convention — travels well. Runtime-specific frontmatter does not, and in at least one case actively breaks: a Cursor `paths` field makes a skill [completely undiscoverable in Claude Code](/agent-skills-not-working/#paths-breaks-discovery-in-claude-code). [Agent Skills compatibility](/agent-skills-compatibility/) covers what travels and where it stops. ## A more targeted way to look Everything above is organised by source — where skills come from. If you'd rather start from the job itself, [AgentSkills Doctor](/doctor/) takes an agent and a goal and recommends a small, explained stack from this same curated set, with the compatibility tier and any overlap called out directly rather than left for you to work out. ## Caveats - We have not installed any skill from any source named here, and nothing on this page is a ranking. - Repository metadata, registry behaviour, and marketplace review processes are as documented and observed on **16 August 2026**. - Audit statuses, telemetry behaviour and review pipelines are the operators' descriptions of their own processes. We have not evaluated their accuracy. ## Sources - [ClawHub documentation](https://docs.openclaw.ai/clawhub) and [Security Audits](https://docs.openclaw.ai/clawhub/security-audits) - [`vercel-labs/skills`](https://github.com/vercel-labs/skills) — the `npx skills` README - [Cursor — Plugins](https://cursor.com/docs/plugins) and [`cursor/plugins`](https://github.com/cursor/plugins) - [Claude Code — plugin marketplaces](https://code.claude.com/docs/en/discover-plugins) - Repository metadata for every pack and list named above, via the GitHub API, 16 August 2026 - [agentskills.io — the specification](https://agentskills.io/specification) --- ## SKILL.md validator rules (23) Every rule the validator at https://agentskills.site/skill-md/validate/ checks has its own page at https://agentskills.site/skill-md/rules//. See https://agentskills.site/skill-md/rules/ for the full index.