# Where Cross‑Agent Skill Locations Are Stored and How the Host Is Detected

> Discover where cross-agent skill locations are stored and how the host is detected. Learn about filesystem probing and interactive fallback in our technical guide.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: internals
- Published: 2026-08-25

---

**Cross‑agent skill locations follow the Agent Skills standard, with per‑host directories enumerated in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) and [`docs/install.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/install.md), while host detection relies on filesystem probing of these known roots plus interactive fallback when multiple or zero matches exist.**

The **book-to-skill** repository implements a portable skill format that works across multiple AI coding agents. Understanding where skills are stored and how the system identifies which host is running ensures seamless installation and consistent behavior whether you're using GitHub Copilot CLI, Amp, Claude Code, or OpenAI Codex.

---

## Cross‑Agent Skill Storage Locations

The Agent Skills standard defines conventional directories where each host agent discovers installed skills. These paths are documented in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) and reinforced in [`docs/install.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/install.md):

### Personal Skill Roots (Probed in Order)

| Host Agent | Personal Skill Root Discovery Order |
|------------|-------------------------------------|
| **GitHub Copilot CLI** | `~/.copilot/skills` → `~/.agents/skills` |
| **Amp** | `~/.agents/skills` → `~/.config/agents/skills` → `~/.config/amp/skills` |
| **Claude Code** | `~/.claude/skills` |
| **OpenAI Codex** | `~/.agents/skills` (native discovery, follows symlinks) |

### Project‑Local Skill Roots

| Host Agent | Project‑Local Root |
|------------|-------------------|
| **GitHub Copilot CLI** | `.github/skills` → `.claude/skills` → `.agents/skills` |
| **Amp** | `.agents/skills` |
| **Claude Code** | `.claude/skills` |
| **OpenAI Codex** | `.agents/skills` |

These **cross‑agent skill locations** enable the same skill to be installed once and accessed by any compatible host, provided it resides in a mutually recognized directory.

---

## How Host Detection Works

Host detection operates through a filesystem‑probing algorithm defined in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (lines 8‑15). The converter selects the appropriate `SKILLS_HOME` through a deterministic four‑step process:

1. **Probe candidate roots** — Iterate through the host‑specific directory list for the current environment.

2. **Single match autopilot** — If exactly one candidate root exists, it is selected automatically as `SKILLS_HOME`.

3. **Zero‑match fallback** — If no roots exist (fresh machine), the user is prompted to choose from host‑specific options.

4. **Ambiguity resolution** — If the host cannot be identified from directory structure alone, the system asks the user to specify their agent (Copilot CLI, Amp, Codex, or Claude Code).

This **directory existence checking** combined with **interactive fallback** ensures robust host detection without requiring environment variables or configuration files.

---

## Implementation: Host Detection in Practice

The probing and selection logic appears in the skill generation flow. Here is the algorithm extracted from the codebase:

```bash

# Probe candidate roots for the current host

for root in $HOST_CANDIDATE_ROOTS; do
    if [ -d "$root" ]; then
        FOUND_ROOTS+=("$root")
    fi
done

# Apply selection rules (SKILL.md § Selection rules)

case "${#FOUND_ROOTS[@]}" in
  1) SKILLS_HOME="${FOUND_ROOTS[0]}" ;;               # exactly one → use it

  0) ask_user_to_choose_root "$HOST_CANDIDATE_ROOTS" ;; # none → prompt

  *) error "Multiple skill roots found – ambiguous host" ;;
esac

```

The `HOST_CANDIDATE_ROOTS` variable is populated from the host‑specific probe order listed in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md).

---

## Installing Skills to Cross‑Agent Locations

Per [`docs/install.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/install.md), you can leverage the shared `~/.agents/skills` directory for maximum compatibility:

```bash

# Clone the repo into the shared cross‑agent location

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill

# Reload the skill in any host (Copilot CLI, Amp, or Codex)

/skills reload
/skills info book-to-skill

```

The `~/.agents/skills` path is recognized by Copilot CLI (fallback), Amp (primary), and Codex (primary), making it the most portable installation target.

---

## Key Source Files

| File | Purpose |
|------|---------|
| **[`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md)** | Maps per‑host skill directories and defines `<SKILLS_HOME>/<slug>/` structure |
| **[`docs/install.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/install.md)** | Documents cross‑agent clone paths and "one command, any host" behavior |
| **[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)** | Specifies host‑detection algorithm, probe order, selection rules, and fallback prompts |
| **[`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py)** | Validates generated [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) against host‑specific location rules |

---

## Summary

- **Cross‑agent skill locations** are standardized per the Agent Skills specification, with host‑specific personal and project‑local roots enumerated in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md).
- **Host detection** probes these known directories; automatic selection occurs with exactly one match, while zero or ambiguous matches trigger interactive prompts.
- The **`~/.agents/skills`** directory offers the broadest cross‑host compatibility, recognized by Copilot CLI, Amp, and Codex.
- Implementation details reside in **[`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md)** (algorithm), **[`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md)** (paths), and **[`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/validate_skill.py)** (validation).

---

## Frequently Asked Questions

### What happens if multiple skill roots exist on my system?

The system raises an ambiguity error and requires manual intervention. According to [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) § Selection rules, more than one discovered root prevents automatic `SKILLS_HOME` assignment to avoid installing skills to unintended locations.

### Can I force installation to a specific host's directory?

Yes. When the detector finds zero matching roots, it prompts you to choose from the host‑specific options. You can select the directory corresponding to your preferred agent (e.g., `~/.claude/skills` for Claude Code) even on a fresh machine.

### Does Claude Code recognize the shared `~/.agents/skills` directory?

No. Claude Code exclusively uses **`~/.claude/skills`** for personal skills and **`.claude/skills`** for project‑local skills. It does not probe `~/.agents/skills` in its discovery order, per [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md).

### How does OpenAI Codex handle symlinks in skill directories?

Codex follows symlinks during discovery, as noted in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md). This enables flexible organization where `~/.agents/skills` could symlink to another location while remaining functional for Codex's native discovery mechanism.