How to Install a Skill in Claude Code, claude.ai & Codex

A skill is a plain-markdown SKILL.md package — a folder of instructions, no code to compile and nothing to run. Installing one means dropping that folder where your agent already looks: the skills directory for Claude Code, a Project's knowledge for claude.ai, or an AGENTS.md reference for Codex. There's no restart and no build step. The agent reads it on the next relevant request and follows it.

That's the whole trick. The rest of this page is where the folder goes for each runtime, how to confirm the agent actually picked it up, and how to swap in a new version when one ships.

What's actually in the crate

A skill package is a directory. At minimum it holds a SKILL.md — a markdown file with a short front-matter header (name + a description that tells the agent when to reach for it) followed by the procedure itself. Bigger skills add a references/ folder the SKILL.md points to for the heavy detail. AgentSource packages also ship a QUICKSTART.md, a LICENSE.txt, and a CHANGELOG.md so you can see what moved between versions.

Nothing here executes on its own. The agent loads the markdown into context and works from it, the same way it would follow a runbook you pasted in — except it's issued as a folder, versioned, and it stays put.

The worked example

We'll install one real skill three ways: the App Store Keyword Engine — the full ASO workflow that pulls the actual ranked apps, mines their tokens, and rebuilds your metadata field by field. Its field report is a documented run on a Productivity app that didn't rank for its own brand name: the skill's intent-poisoning gate caught a single word in the app's Name filing it into the wrong category's search results, against journaling incumbents with six-figure review counts. That's the shape of what you're installing — a procedure that ran on live listings, not pattern-matched boilerplate.

Every AgentSource zip includes a QUICKSTART.md with these same steps plus a copy-paste first-run prompt. Unzip the download first; you'll have a folder named after the skill.

1. Install a skill in Claude Code

Claude Code discovers skills from a skills/ directory. You pick the scope.

Where the file goes — personal vs. project

Personal (available in every project on your machine):

mkdir -p ~/.claude/skills/app-store-keyword-engine
cp -R SKILL.md references ~/.claude/skills/app-store-keyword-engine/

Project (scoped to one repo, and commit-able so your team gets it too):

mkdir -p .claude/skills/app-store-keyword-engine
cp -R SKILL.md references .claude/skills/app-store-keyword-engine/

Copy the whole folder — SKILL.md and any references/ — not just the one file. Claude Code picks it up automatically; there's no config to edit.

Verify Claude Code picked it up

Open a new session (a session already running won't see a folder you dropped mid-flight). Then either type / and confirm app-store-keyword-engine autocompletes as a slash command, or ask the agent to do the job the skill covers ("do keyword research on my app…") and watch it follow the workflow. Asking "what skills do you have?" also lists the discovered set. If it's not there, check the path — the folder name and its SKILL.md both have to sit inside the skills/ directory.

2. Install a skill in claude.ai Projects

claude.ai has no local filesystem, so the skill rides in a Project's knowledge instead.

Upload to Project knowledge

1. Create or open a Project in claude.ai.
2. Add SKILL.md to the Project's knowledge/files. Add the references/*.md files too — the SKILL.md points at them.
3. Wait for the upload to finish processing.

That's it. The skill now applies to any chat started inside that Project — not to your global chats, which is the point: you get a keyword-research Project, a QA Project, and they don't bleed into each other.

Verify

Start a chat in the Project and ask for the job the skill covers. If the workflow drives the session — the App Store Keyword Engine opens with its brand-defense check — it's live. If the agent answers generically, confirm the files finished processing and that you're inside the Project, not a loose chat.

3. Install a skill in OpenAI Codex

Codex reads an AGENTS.md file for standing instructions. You keep the skill in the repo and point at it from there.

Drop the folder, reference it from AGENTS.md

Put the package somewhere in the repo — skills/app-store-keyword-engine/ is the convention — then add one line to your AGENTS.md at the repo root:

When asked for App Store keyword research or ASO, follow skills/app-store-keyword-engine/SKILL.md.

The reference is what makes Codex load it; the folder alone is inert. One line per skill keeps AGENTS.md readable as the kit grows.

Verify

Start a Codex run in the repo and ask for the job. It should open skills/app-store-keyword-engine/SKILL.md and follow it. If it ignores the skill, confirm AGENTS.md is at the root (or the directory Codex is working from) and that the path in your reference line actually matches where you put the folder.

Updating when a new version ships — the locker re-download

Skills get maintained. Apple moves a character limit, a platform surface changes, a documented gotcha gets added — the version bumps and the fix lands in the package, not in a changelog you have to re-implement by hand.

Getting the update is a re-download, not a re-purchase. Every AgentSource order gives you a permanent locker link. When a skill you own ships a new version, pull the fresh zip from your locker, read the bundled CHANGELOG.md to see what changed, and copy the folder over the old one — same destination, same steps as the first install. In Claude Code that's a cp -R over the existing directory; in claude.ai you replace the files in the Project; in Codex you overwrite the folder in the repo. No session survives the swap seeing the old copy — start a fresh one and you're on the new version.

One skill, three runtimes

The reason a single package installs everywhere is that it's plain text. The Deep QA Audit Loop — whose field report is a real Layer-3 finding, a actual >= dailyTarget comparison that passed trivially against an unset target — and the Demand Validation Engine, which shows two documented runs landing a BUILD and a discovery-path-gate reversal, both install by the exact three methods above. Nothing about the procedure is runtime-specific; only the drop location differs. Requisition once, deploy it wherever your agent runs.

Two habits keep you out of trouble: copy the whole folder (references and all), and after any install or update, start a fresh session before you check your work — that single step resolves most "the agent isn't using it" reports. Beyond that, the QUICKSTART in every package has the steps for whichever runtime you're standing in.