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](https://github.com/huggingface/skills) 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:

```bash
# 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:

```text
/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:

```text
$skill-installer hf-cli
```

Or, you can install the entire Hugging Face plugin:

```text
/plugins
```

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

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

```bash
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`:

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

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

```bash
# 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).

```text
# 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
```

```bash
# 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.

```text
# 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:

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

Or check installed plugins inside a Claude Code session with:

```text
/plugin
```

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

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

```bash
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:

```bash
.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.