context-course/pr_7/en/unit1/using-skills.md

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

Use /plugin to browse, enable, and disable installed plugins. Plugin skills are namespaced as /<plugin-name>:<skill-name> (for example, /hf-cli:download-model) to prevent conflicts.

Use the built-in skill installer for curated skills:

$skill-installer hf-cli

Or, you can install the entire Hugging Face plugin:

/plugins

Then select 'Hugging Face' and click 'Install plugin'.

Create the skill directory in any supported location and add a SKILL.md file:

hf skills add

This will create the skill directory and add the SKILL.md file in .agents/skills/hf-cli/SKILL.md.

OpenCode discovers it automatically.

You can control which skills agents may use via opencode.json:

{
  "permission": {
    "skill": {
      "*": "allow",
      "experimental-*": "ask"
    }
  }
}

Pi discovers the shared .agents/skills/ tree that hf skills add creates, so the simplest install flow is:

# Creates .agents/skills/hf-cli/SKILL.md
hf skills add

# Start Pi in the same repository
pi

For one-off testing, you can also load a skill explicitly with pi --skill /absolute/path/to/SKILL.md.

Invoking Skills

Once installed, skills activate in two ways: implicitly (the agent matches your request to a skill's description) or explicitly (you invoke a skill by name).

# Implicit — Claude matches your request to the skill description
Download the latest version of meta-llama/Llama-4-Scout-17B-16E

# Explicit — invoke a plugin skill by its namespaced name
/hf-cli:download-model

# Implicit — Codex selects based on task matching
codex "Upload my model to the Hub"

# Explicit — mention by name
$hf-cli

Agents invoke skills via the native skill tool by passing the skill name. OpenCode matches tasks to skills automatically based on the description in frontmatter.

# Implicit — Pi selects based on task matching
Upload my model to the Hub

# Explicit — force the skill
/skill:hf-cli Upload my model to the Hub

Troubleshooting Skills

Skill Doesn't Activate

Problem: Skill is installed but the agent doesn't use it.

Check that the description field includes keywords matching your request, use terms that align with the skill's stated purpose, or invoke the skill explicitly by name. A description like "Hugging Face Hub CLI for downloading, uploading, and managing repositories" activates on requests mentioning "upload," "download," or "Hugging Face," but a vague request like "push my files somewhere" may not match.

Did Your Skill Fire?

The fastest way to debug a new skill is to test activation pressure directly:

1. Ask for the skill with an obvious prompt that should match its description.
2. Ask again with a vaguer prompt that a real user might write.
3. If only the first prompt works, tighten the description until both prompts reliably activate the skill.

For Codex, this is exactly where $skill-creator helps. Feed it the skill, the prompt that failed to activate, and the behavior you wanted so it can sharpen the description without rewriting the whole skill.

Skill Not Found

Problem: Agent can't locate the skill.

Verify the skill is in the correct directory for your agent:

ls .claude/skills/hf-cli/SKILL.md

Or check installed plugins inside a Claude Code session with:

/plugin

ls .agents/skills/hf-cli/SKILL.md

ls .opencode/skills/hf-cli/SKILL.md

ls .pi/skills/hf-cli/SKILL.md
ls .agents/skills/hf-cli/SKILL.md

Pi loads either path, plus the user-level directories under ~/.pi/agent/skills/ and ~/.agents/skills/.

Skill Conflicts

Problem: Multiple skills have overlapping functionality.

Make each skill's description field specific enough that the agent can distinguish between them. If two skills cover related tasks (e.g., validation and publishing), give each a clear scope in its description.

Best Practices

Organize skills by domain — keep related skills together so agents can discover related functionality easily:

.claude/skills/
├── hf-cli/
│   └── SKILL.md
├── dataset-validation/
│   └── SKILL.md
├── model-training/
│   └── SKILL.md
└── model-evaluation/
    └── SKILL.md

Keep each skill focused on one task. If a SKILL.md exceeds 500 lines, split it into multiple skills or move reference material to supporting files in the same directory.

Next Steps

Next, we'll build a skill from scratch.