# Claude Skills Explained: How One SKILL.md Behaves in Claude Code, Codex and Octomind > Claude skills are portable folders, but paths and triggers differ. Compare Claude Code, Claude apps/API, Codex and Octomind skills, limits checked October 2026. 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)](https://agentskills.io/specification) 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](/blog/mcp-vs-cli-vs-skills) 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) say the description is what Claude matches against the request. This is a portable, documentation-only example. I did not install or run it. ```text issue-triage/ ├── SKILL.md ├── references/ │ └── severity-rules.md └── scripts/ └── collect-issue.sh ``` ```markdown --- 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`: ```markdown - 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`: ```bash #!/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](https://code.claude.com/docs/en/skills); [OpenAI, 2026](https://learn.chatgpt.com/docs/build-skills)). 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](/docs/usage/15-skills)). 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](/docs/usage/15-skills). Keep optional reference material in separate files and link to each directly from `SKILL.md`; [Claude Code's docs](https://code.claude.com/docs/en/skills) 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. | Host | Skill folder (user / project) | How it triggers | Limit worth knowing | | ------------------- | ---------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------- | | Claude Code | `~/.claude/skills`; `.claude/skills` | Automatic by relevance; `/skill-name` | Name 64 chars; description 1,024; file under 500 lines | | Claude apps and API | Upload ZIP / API Skills upload | App relevance; API attaches `skill_id` | API needs code execution; no network or package install | | Codex CLI | `$HOME/.agents/skills`; repo `.agents/skills` | Description match; `/skills` or `$skill-name` | Index: 2% context; 8,000 chars if window unknown | | Octomind | User `~/.config/agents/skills`; project `.agents/skills`; tap `/skills` | Matching rules; `/skill`; `OCTOMIND_SKILLS` | No documented count cap; `/skill` 15/page, tool list default 20 | Sources: [Claude Code](https://code.claude.com/docs/en/skills), [Claude Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), [Codex](https://learn.chatgpt.com/docs/build-skills), [Octomind skills guide](/docs/usage/15-skills), [Octomind measurement](/blog/mcp-vs-cli-vs-skills). 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](/docs/usage/15-skills) and [our activation design](/blog/agent-skills-auto-activation). ## 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](https://learn.chatgpt.com/docs/build-skills)). For Claude Code, control fields such as `disable-model-invocation` affect invocation ([Anthropic, 2026](https://code.claude.com/docs/en/skills)). For Octomind, `capabilities` can associate a skill with runtime capabilities ([Octomind docs, 2026](/docs/usage/15-skills)). 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](/blog/mcp-vs-cli-vs-skills). 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](https://github.com/anthropics/skills), 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](https://code.claude.com/docs/en/plugins)). Octomind has a community [tap registry](/tap) 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 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: | Symptom | Likely cause | Fix | | ------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Skill is absent from the list | Wrong root or `SKILL.md` is not inside a named skill directory | For Claude Code, check `.claude/skills//SKILL.md` or `~/.claude/skills//SKILL.md`; for Codex, check `.agents/skills//SKILL.md` or `$HOME/.agents/skills//SKILL.md`. | | Skill is listed but does not trigger | Description is generic, missing the task's phrases, or a host-specific trigger is missing | State what the skill does and give real example request language. In Octomind, add a matching `domains` entry and non-empty `rules`; a description alone does not enable auto-activation. | | Upload reports invalid frontmatter | Missing `---` delimiters, malformed YAML, unclosed quotes, or an invalid name | Use valid YAML and the required fields. The [Agent Skills spec](https://agentskills.io/specification) caps names at 64 characters and descriptions at 1,024; use lowercase hyphenated names. | | Works in one Claude surface but not another | Claude.ai syncs to same-account Claude Code; API uploads remain separate | Check which account is signed in; upload the API skill separately. | | Codex lists many skills but misses one | The initial description index hit its context budget | Shorten descriptions and remove redundant skills; Codex may omit entries from an oversized initial list. | Anthropic's [skill-building guide](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) 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](https://github.com/anthropics/skills/discussions/244) 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](/blog/agent-skills-auto-activation) · [MCP vs CLI vs skills](/blog/mcp-vs-cli-vs-skills) · [how we distribute taps](/blog/introducing-taps) · [Octomind's tap registry](/tap)