Agent skill guide
Install Agent Skills in Codex, Claude Code and Cursor: Verify Every Layer
Install a complete skill folder in the right scope, confirm discovery separately from dependencies, and troubleshoot Codex, Claude Code and Cursor without guessing compatibility.
Install a skill by placing its complete, reviewed folder in a directory supported by your agent, then verify discovery, dependencies and a small task separately. A file appearing in a selector does not prove its scripts or connectors work. These local setup paths were checked against official documentation on 20 October 2026; the directory’s third-party skills have not been independently installed or executed.
What should you inspect before installation?
Identify the repository, the exact skill folder and the commit you intend to use. Read the manifest and inspect any scripts, references, assets or remote downloads it names. Check the applicable license rather than assuming that a public repository grants redistribution rights. Use a test working directory with synthetic data for the first run.
Keep the complete folder structure. Copying only SKILL.md can leave the agent able to discover a skill while breaking every referenced helper. A repository may contain many separate skills; installing the entire repository is a broader decision than adding one folder. Compare the actual installed name with the manifest and the host’s discovery rules.
Which project directory should you use?
| Host | Example project-local path | Discovery check | Official reference |
|---|---|---|---|
| Codex | .agents/skills/pdf/SKILL.md | Check the skill selector or mention the installed skill explicitly | OpenAI local skill guidance |
| Claude Code | .claude/skills/frontend-design/SKILL.md | Use the installed skill’s command name in the intended project session | Claude Code skills |
| Cursor | .cursor/skills/web-design-guidelines/SKILL.md | Find the skill in Agent’s slash-command selection | Cursor skill directories |
These are example folder locations, not a claim that each example skill has been tested on all three hosts. Codex also supports user-scoped local skills; Claude Code has personal, project and plugin scopes; Cursor documents both .cursor/skills and .agents/skills locations. Begin project-locally to keep an experiment’s intended scope visible.
How do you perform a controlled manual installation?
- Open the profile’s pinned source link and select the intended version.
- Obtain that complete folder through the publisher’s documented distribution method or a reviewed checkout. Keep a record of the commit; avoid mixing helper files from another revision.
- Place the folder in the chosen project-local location. Preserve references and assets rather than flattening the directory.
- Confirm the skill appears in the host’s intended project session. Consult current host guidance if it does not; avoid repeatedly installing duplicate copies.
- Inspect the required tools and credentials separately, then authorize only the minimum needed for a synthetic trial.
- Run a bounded task and compare the resulting artifact with explicit acceptance checks.
The community skills CLI is another distribution route. Its documentation demonstrates npx skills add vercel-labs/agent-skills for that repository. This command downloads and runs an installer, and can expose multiple candidate skills. It is not a universal command to paste for any product URL. Review the installer, source, selection and destination before using it. See the CLI publisher’s documentation.
Why can discovery succeed while the task fails?
Discovery reads enough metadata to identify a workflow. Execution needs the actual capabilities referenced by that workflow. The Figma profile requires a working design integration; the Linear profile needs workspace access; Audio Transcribe needs an API processing route and key. Installing text instructions creates none of those accounts or permissions.
Older skill examples can also contain setup flags, tool names or home-directory assumptions that no longer match the host. Compare those lines with current official documentation. Do not weaken permissions or copy a token into chat merely because a source example suggests a particular environment.
How should you troubleshoot a missing or broken skill?
| Symptom | First check | Avoid |
|---|---|---|
| Skill is not discovered | Exact SKILL.md filename, valid metadata, folder scope and active project | Installing copies in every global directory |
| Skill appears but a helper is missing | Complete folder contents and relative paths at the same commit | Replacing the missing helper with unrelated code from a newer revision |
| Connector tool is unavailable | Current integration support, account access and host policy | Assuming the skill includes a connected account |
| A permission request appears | Which operation needs access and whether the task justifies it | Granting broad account access as a generic installation fix |
| Output exists but is wrong | Input assumptions and artifact-specific checks | Calling installation successful execution or execution verified quality |
How do updates and removal affect the environment?
Update deliberately: keep the previously reviewed version, inspect the new manifest and helpers, and repeat the smoke test. A latest-version label does not identify what was reviewed. If a skill fetches moving external references, preserve that evidence too.
Remove a project-local skill by removing that intended folder through your normal file-management process and checking discovery again. Removing instructions does not revoke OAuth access, delete generated files or stop an independently started service. Review those components separately when retiring an integration.
Installation questions
Will a local skill automatically appear in a cloud agent?
Do not assume so. A remote runner has its own filesystem and policy. Verify the specific product’s documented synchronization or repository-scoped distribution behavior before relying on a local installation.
Does a shared file format mean the skill works everywhere?
No. File discovery and runtime capabilities are separate. A workflow can depend on a connector, shell, browser or approval behavior that the second host does not provide.
What changed: first edition separates discovery, dependency setup and runtime verification, with three host-specific directory examples. Continue with the evaluation workflow after installation.