Using Skills with Code Agents

The Agent Skills Specification keeps the SKILL.md format consistent across agents. What differs is where each agent looks for skills on disk and how you install them.

Where Skills Live

Each agent discovers skills from known directories. You create a skill by placing a SKILL.md file in a named subdirectory at one of these paths:

Scope	Path	Applies to
Personal	~/.claude/skills/<name>/SKILL.md	All your projects
Project	.claude/skills/<name>/SKILL.md	This project only

Claude Code also watches for changes — adding, editing, or removing a skill takes effect within the current session without restarting.

Scope	Path
Repository	.agents/skills/<name>/SKILL.md
User	~/.agents/skills/<name>/SKILL.md
Admin	/etc/codex/skills/<name>/SKILL.md

Codex discovers skills from all three locations; when the same skill name appears in more than one, the repository copy is used first, then the user copy, then the admin copy.

Project-local paths:

• .opencode/skills/<name>/SKILL.md
• .claude/skills/<name>/SKILL.md
• .agents/skills/<name>/SKILL.md

Global paths:

• ~/.config/opencode/skills/<name>/SKILL.md
• ~/.claude/skills/<name>/SKILL.md
• ~/.agents/skills/<name>/SKILL.md

OpenCode walks up from the current working directory to the git root, checking each level.

Scope	Path
Project	.pi/skills/<name>/SKILL.md
Shared repo tree	.agents/skills/<name>/SKILL.md
User	~/.pi/agent/skills/<name>/SKILL.md
Shared user	~/.agents/skills/<name>/SKILL.md

Pi scans the Pi-specific paths plus the shared .agents/skills/ tree, so the same skill can work in Pi and other harnesses without duplication.

Installing a Skill

We'll use the hf-cli skill as a real-world example. It gives agents access to the Hugging Face Hub CLI for downloading, uploading, and managing repositories.

The Hugging Face CLI also provides a cross-agent skill installer. Use it when you want the same skill in more than one agent or want a shared install flow:

# Project-local install
hf skills add

# Agent-specific symlinks
hf skills add --claude
hf skills add --codex --opencode --global

Skills are distributed as plugins via marketplaces. Inside a Claude Code session, add a marketplace, then install the plugin that contains the skill:

/plugin marketplace add huggingface/skills
/plugin install hf-cli@huggingface-skills