Claude Skills Explained: How One SKILL.md Behaves in Claude Code, Codex and Octomind

Claude skills are folders of instructions and resources. The same SKILL.md can travel between tools, but where it goes and what makes it load depend on the host. I make Octomind, so I checked its current skill docs against Anthropic's and OpenAI's, October 27, 2026.

The short answer: write a folder with SKILL.md, name, description, and useful instructions; keep those two frontmatter keys if you want the widest compatibility. Claude Code and Codex can discover local folders and invoke a skill by slash command or $ mention. Claude.ai skills sync to Claude Code for the same signed-in account; API uploads are separate. Octomind adds rule-based activation and tap distribution. The shared format does not make their paths, triggers, or controls interchangeable.

What are Claude skills, and how do they work?

A Claude skill is a reusable directory containing a SKILL.md file and optional scripts, references, or assets. The open Agent Skills specification (2026) requires YAML frontmatter with name and description, followed by Markdown instructions. Claude and Codex use the description to decide whether a skill fits; Octomind can use declarative rules. After activation, the host reads the body and any supporting files as needed.

A skill tells an agent when and how to do a task; an MCP server exposes tools the agent can call. A skill can explain how to use a tool, but it doesn't itself provide the tool. Our earlier Claude skills vs MCP and CLI comparison lays out that boundary and the measured context cost.

How do I create a Claude skill that loads reliably?

Start with the two required fields, make the folder name match name, and make description say both what the skill does and which requests should trigger it. The specification sets a 64-character maximum for name and 1,024 characters for description; Anthropic's 2026 authoring docs say the description is what Claude matches against the request.

This is a portable, documentation-only example. I did not install or run it.

issue-triage/
├── SKILL.md
├── references/
│   └── severity-rules.md
└── scripts/
    └── collect-issue.sh

---
name: issue-triage
description: Triage a software issue by identifying its expected behavior, reproduction steps, affected area, and severity. Use when asked to classify or prepare a bug report.
---

# Issue triage

For each issue:

1. Separate observed behavior from expected behavior.
2. Record the shortest reproducible steps available.
3. Read `references/severity-rules.md` before assigning severity.
4. Do not run `scripts/collect-issue.sh` unless the user asks for repository evidence.

The two support files in that tree need real contents.

references/severity-rules.md:

- Critical: confirmed data loss, remote code execution, or broad unauthorized access.
- High: a repeatable security or availability failure with limited prerequisites.
- Medium: a user-facing defect with a workaround.
- Low: cosmetic or low-impact behavior.

scripts/collect-issue.sh:

#!/usr/bin/env bash
set -eu
git status --short
git diff --stat

The example skill doesn't run either file. It tells the agent when to read the reference and when it may ask to run the read-only helper. Claude and Codex load the description for selection and the instructions after selection (Anthropic, 2026; OpenAI, 2026). Octomind won't auto-activate this two-key portable example by description alone; use /skill issue-triage or add Octomind-specific domains and rules in a host-specific copy (Octomind docs, 2026).

The Agent Skills spec requires name and description and also defines optional license, compatibility, metadata, and allowed-tools fields. Avoid adding a Claude-specific key such as disable-model-invocation to this portable file: Claude Code understands it, while Codex implicit matching depends on description and agents/openai.yaml can disable implicit invocation; Octomind ignores unknown keys.

Keep optional reference material in separate files and link to each directly from SKILL.md; Claude Code's docs recommend keeping the main file under 500 lines.

Where does each tool look for a skill?

The folder format is shared; installation is not. These paths and behaviors are from vendor docs or Octomind's skill documentation, checked October 27, 2026.

Sources: Claude Code, Claude Agent Skills overview, Codex, Octomind skills guide, Octomind measurement.

Claude Code skills can also come from plugin and managed locations. Claude Code reads metadata before the body and referenced supporting files, and syncs skills enabled on the same claude.ai account to ~/.claude/skills/synced/.

Claude apps accept a ZIP upload; API skills are uploaded through the Skills API and attached by skill_id. Apps and API load relevant metadata and instructions/resources on demand. API use requires the code execution tool; its container has no network access or runtime package installation.

Codex skills live in user and repository .agents/skills folders; Codex searches them from the current directory through the repository root. It presents each skill's name, description, and path, then reads SKILL.md after selection. Implicit matching depends on description; agents/openai.yaml can set policy.allow_implicit_invocation: false. The initial index uses at most 2% of the model context, falling back to 8,000 characters if Codex doesn't know the window size; skills.max_context_tokens can raise the budget to 10,000 tokens, and oversized lists may omit entries with a warning.

Octomind also reads tap and plugin skills; taps win duplicate names. Its parser requires name and description, recognizes listed fields, and ignores unknown keys. Automatic activation needs a matching domains entry and non-empty rules; activated bodies are injected and supporting paths are listed for later reads. Documentation sets no count or field-length limit, and doesn't validate name/description lengths. The /skill command lists 15 per page; the AI-facing skill tool's list action defaults to 20. See the rules and directory precedence and our activation design.

Does the same SKILL.md work in Claude Code, Codex and Octomind?

The minimal file above can be shared, but “works” means only that each host can parse and load its common core. Trigger behavior still changes: Claude and Codex use the description for implicit matching (which Codex can disable in agents/openai.yaml), while Octomind automatic activation needs its own domains and rules fields. Those Octomind fields aren't part of the portable example.

A practical split is to keep shared instructions and references in one folder, then add a small host-specific layer only when you need host-specific triggers, tool permissions, or distribution.

For Codex, optional agents/openai.yaml supplies UI metadata; it isn't required for a basic skill (OpenAI, 2026). For Claude Code, control fields such as disable-model-invocation affect invocation (Anthropic, 2026). For Octomind, capabilities can associate a skill with runtime capabilities (Octomind docs, 2026). Each one is useful in its host and shouldn't be mistaken for standard metadata.

Claude apps and API add another boundary: a skill uploaded to Claude.ai syncs to Claude Code for the same signed-in account, while API uploads remain separate. OpenAI documents standalone skills for ChatGPT desktop and Codex, while skills bundled in plugins have additional ChatGPT availability. Check the destination surface before promising that a file is “installed everywhere.”

What does a large Claude skills library cost?

It can cost more context than expected, even when the full skill bodies aren't loaded. In our recorded measurement, 115 Octomind tap skills contained 304,534 tokens across their full SKILL.md files. A one-line name and description for each was 8,971 tokens, and the median full skill was 2,601 tokens. We counted with OpenAI's o200k_base; Claude's tokenizer gives different figures. See the measurement and method.

The decision rule is to measure the index your host loads, not to multiply the full-body total by your skill count. Claude and Codex describe progressive disclosure: metadata is presented for discovery and the body is read when selected. Codex caps that initial index (2% of context) and can omit entries; Octomind's docs don't publish a total-list cap. In Octomind, activated skills can bring supporting files into view by path instead of injecting every reference into the prompt.

A skill library is useful when each entry has a distinct job. If descriptions overlap, sharpen their triggers or merge them; installing more folders doesn't make matching more precise.

Where can I find Claude skills, and is there an official Claude skills marketplace?

Start with Anthropic's public skills repository, which contains official skills and examples. Anthropic documents it as installable through Claude Code's plugin marketplace. That's a plugin distribution route for Claude Code; the Agent Skills format itself is an open standard, not a promise that every third-party catalog is official or reviewed by Anthropic.

For other people's work, browse the repository before installing it. Anthropic defines a Claude Code plugin marketplace as a repository or directory whose marketplace.json lists plugins and where to fetch them; it's a catalog, not a hosted store (Anthropic, 2026).

Octomind has a community tap registry that distributes prepared agent configurations, capabilities, workflows, and skills. The site listed 157 specialists as of October 25, 2026. The registry is a starting point for discovery, not a substitute for reviewing what a skill can read, write, or execute.

Use this review pass before enabling a third-party skill:

• Read every file. Inspect SKILL.md, scripts, and linked references. Check whether network calls, file access, and commands match the stated task.
• Follow every link. A reference that points to missing files or an external URL can change what the agent sees.
• Check the requested tools. Skills provide instructions and may ask the host to use shell, filesystem, or code tools; don't assume their metadata grants or limits those permissions.
• Try it on a disposable project. Use a low-risk task and inspect the output before giving it access to private repositories or secrets.

Anthropic warns that a malicious skill can direct Claude to misuse tools, run code, or expose data. Its security guidance says to audit every bundled file and treat skills like software you install. A skill is plain text, but its instructions can still induce actions through the agent's available tools.

Why isn't my Claude skill loading?

Most failures come from the file structure, frontmatter, or a description that doesn't match the request. Check these in order:

Anthropic's skill-building guide names the upload error Could not find SKILL.md in uploaded folder: make sure the filename is exactly SKILL.md and upload the containing skill folder as a ZIP. It also gives Invalid frontmatter for YAML formatting problems.

In Claude Code, SKILL.md placed directly inside .claude/skills/ is the wrong shape; use a named subdirectory. A reported Anthropic skills discussion walks through that same detection failure, but its community suggestions aren't official product guarantees.

Which skill format should you choose?

Use the two-key Agent Skills core when you want the instructions to move between runtimes. Add host-specific metadata only when you accept that the feature may work in one tool and be ignored elsewhere. Use Claude Code's slash invocation for an action that should wait for you, Codex's $skill when you want to name the skill directly, or Octomind rules when you need activation based on project context rather than description matching.

The format is portable. Its runtime contract is not. Keep the core small, test the skill in the host where it will run, and review its scripts before granting access to a real workspace.

Related reading: how skills activate in Octomind · MCP vs CLI vs skills · how we distribute taps · Octomind's tap registry