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

Cross‑agent skill locations follow the Agent Skills standard, with per‑host directories enumerated in docs/architecture.md and 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 and reinforced in 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 (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:

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

---

Installing Skills to Cross‑Agent Locations

Per docs/install.md, you can leverage the shared ~/.agents/skills directory for maximum compatibility:

# 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	Maps per‑host skill directories and defines <SKILLS_HOME>/<slug>/ structure
docs/install.md	Documents cross‑agent clone paths and "one command, any host" behavior
SKILL.md	Specifies host‑detection algorithm, probe order, selection rules, and fallback prompts
tools/validate_skill.py	Validates generated 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.
• 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 (algorithm), docs/architecture.md (paths), and 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 § 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.

How does OpenAI Codex handle symlinks in skill directories?

Codex follows symlinks during discovery, as noted in docs/architecture.md. This enables flexible organization where ~/.agents/skills could symlink to another location while remaining functional for Codex's native discovery mechanism.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}