Agent Skills: .claude/skills vs .agents/skills Setup

For a repository shared by Claude Code, Codex, Cursor and Gemini CLI, keep the maintained skill files in .agents/skills/<skill-name>/. Expose each shared skill to Claude Code through a relative directory symlink under .claude/skills/. Then check discovery and invocation in each client before adopting the layout across your team.

This setup gives you one editable copy of a workflow while accommodating the clients’ different discovery rules. A team using only Claude Code can keep its existing .claude/skills/ layout; moving directories is useful when you actually need another client to consume the same skills.

Did AAIF standardize the directory name?

AAIF hosts the standard, while clients still choose where to discover skills. Anthropic announced the donation on October 22, 2026, and the foundation welcomed Agent Skills as a hosted project.

The client implementation guide explicitly leaves the containing directory outside the specification’s requirements. It recommends considering .agents/skills/ for interoperability alongside a client’s own directory. That recommendation does not make every existing client scan it.

The portable unit is a directory containing SKILL.md, YAML frontmatter and Markdown instructions. The format specification requires name and description; optional resources can accompany them. Invocation syntax, script runtimes and permissions still depend on the host. In particular, allowed-tools remains experimental with varying implementation support, so it is not a portable permission policy.

Which paths do the four tools scan?

Use the documented local filesystem roots below. The paths and controls in this guide reflect official documentation as of 2026-10-26; append <skill-name>/SKILL.md to each root for the layout used here.

Tool	Repository roots	User roots	Choice for a shared repository
Claude Code	.claude/skills/	~/.claude/skills/	Add a per-skill alias from .claude/skills/ to the shared directory.
Codex CLI and IDE extension	.agents/skills/	~/.agents/skills/	Read the shared directory directly.
Cursor Agent	.agents/skills/, .cursor/skills/; also .claude/skills/ and .codex/skills/ for compatibility	The same four directory names under ~/	Use .agents/skills/; no additional Cursor alias is needed.
Gemini CLI	.agents/skills/ and .gemini/skills/	~/.agents/skills/ and ~/.gemini/skills/	Read .agents/skills/ directly. It wins over .gemini/skills/ within the same scope.

Claude Code’s current guide does not list native .agents/skills/ discovery, and feature request #31005 remains open. Conversely, the Codex and Gemini guides above do not list .claude/skills/ as a discovery root. Use the documented paths rather than treating either directory as universally interchangeable.

These are local discovery paths. A skill in your laptop’s home directory is not automatically available inside a remote worker or fresh container; that environment must receive the files too.

Create one shared skill and a Claude Code alias

Store the complete skill under .agents/skills/ and link its directory, including any future scripts or references. A per-skill alias also leaves room for existing Claude-specific skills.

Start with an installed, authenticated client that can already work in your repository, plus Git. No new API credential is needed for this filesystem setup; normal client access and tool permissions still apply.

Write the portable skill

Create .agents/skills/review-staged/SKILL.md in your editor, creating its parent directories if necessary. If that skill already exists, choose another name and change the directory, frontmatter and commands consistently.

Paste this complete file:

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

The workflow reviews the Git index: the changes prepared for the next commit. Git’s diff reference documents --cached for that comparison and --check for whitespace errors and conflict markers. The example asks the agent to run ordinary commands instead of relying on client-specific prompt expansion.

Add the alias in Bash on macOS or Linux

Create a relative symlink for this skill. Claude Code explicitly documents support for symlinked skill directories.

Run this in Bash, from anywhere inside the intended Git repository:

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

The expected output is ../../.agents/skills/review-staged, with exit status 0. The two .. components are relative to the link’s parent, .claude/skills/, and return to the repository root.

If the destination already exists, inspect it before changing anything. Keep an existing correct alias; reconcile an existing real skill directory with the canonical copy deliberately. The command refuses to replace either a directory or a dangling link.

Create the equivalent link on Windows

Use PowerShell 7.1 or later for the relative directory link below. Microsoft’s New-Item documentation documents that version requirement; Windows symbolic-link creation normally needs elevation, or supported Windows with Developer Mode enabled.

With the canonical SKILL.md already saved, run this from the repository root:

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

Expect LinkType to be SymbolicLink and the file check to return True. If creation fails with a privilege error, use your organization’s approved Developer Mode or elevated setup process.

Do not assume native Git Bash behaves like Linux: Git for Windows documents that its default ln -s behavior creates copies. Use the PowerShell procedure and inspect the resulting link.

A different failure can appear after cloning. With core.symlinks=false, Git checks out a symbolic link as a regular file containing its target text. Diagnose that in PowerShell:

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

If the alias is a text file, inspect its contents before replacing that specific placeholder with a real link. Enable supported symlink checkout behavior for future clones. Changing the Git setting alone does not convert an already checked-out text file into a directory link.

Verify discovery, activation and output

Check the client’s catalog first, then invoke the skill explicitly. A file existing on disk does not prove the client discovered it, and a catalog entry does not prove its instructions were loaded.

Open or launch each client at the repository root. Use these controls inside the client, not at a Bash or PowerShell prompt:

Client	Confirm discovery	Invoke the example
Claude Code	Run /skills; use /reload-skills if necessary, as documented in its commands reference.	Send /review-staged.
Codex CLI or IDE extension	Open /skills or the $ skill picker.	Send $review-staged Review my staged changes.
Cursor Agent	Open Customize → Skills, then find the skill in the / picker.	Select review-staged and request a review of staged changes.
Gemini CLI	Run /skills list; use /skills reload after adding files.	Ask: Use the review-staged skill to review my staged changes.

Gemini’s documented activation flow uses activate_skill and an interactive consent prompt. Approve the intended skill directory when prompted. Its management guide covers listing and reload commands.

The expected answer begins with Skill loaded: review-staged, followed by findings and suggested checks, or No staged changes. when the index is empty. Inspect the activation or file-read trace and the Git commands as well as the marker. This establishes that the workflow loaded; it does not establish that every review finding is correct.

Cursor reads both paths in this layout. Its IDE 3.25 release notes, dated October 14, 2026, say same-name skills can appear as separate menu rows. Check for duplicate entries in your installed version; do not assume every client deduplicates aliases identically.

Use a predictable monorepo and CI layout

Keep shared skills at the repository root and start each client there for the first successful setup. For package-specific workflows, name the package in the skill’s description and instructions instead of depending on identical nested-directory discovery. The example above deliberately reviews the entire Git index.

A practical layout assigns one responsibility to each location:

Location	Responsibility
.agents/skills/review-staged/SKILL.md	Maintained shared instructions.
.agents/skills/review-staged/references/	Optional supporting documents shipped with that skill.
.claude/skills/review-staged	Relative alias to the complete shared skill directory.
packages/mobile/	Application code named in the requested task.

Scope rules differ. Claude Code and Codex walk upward from the starting directory to the repository root for their respective skill directories. Cursor also documents nested project skills scoped to files beneath their containing directory. Gemini’s management guide describes workspace skills relative to the current directory. Starting all four at the root avoids relying on those differences.

Keep each shared skill in an immediate child directory of the skills root. Gemini’s getting-started guide limits discovery to that depth; Cursor’s recursive discovery does not make an extra category layer portable.

For a package-only workspace, repeat the discovery check in that workspace and install or link the shared skill there if needed. Do not reuse the root alias’s ../../ target at a deeper location without recalculating it.

Commit the canonical directory and the relative symlink if your team’s checkout environments support it. Keep the target inside the repository so a fresh clone can resolve it without access to one developer’s home directory.

For a Linux CI checkout, this Bash check verifies the required files and link:

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

Exit status 0 means those filesystem checks passed. Client discovery and invocation still need the checks above in the actual execution environment.

If the skill still does not load, check the failing layer

Fix the layer that failed instead of changing the prompt repeatedly. These are alternative diagnostic branches, not a sequence of settings everyone should change.

• Absent from the catalog: Confirm the workspace root, directory spelling and exact SKILL.md filename. Read the file through the path that the client scans. If the canonical path works but the Claude path fails, repair the link or checkout.
• File found, metadata rejected: Check YAML delimiters, a nonempty description of at most 1024 characters, and a matching directory/name of 1–64 lowercase letters, digits or hyphens. Avoid leading, trailing or consecutive hyphens.
• New file not visible yet: Reload Claude or Gemini skills with the commands above. Codex documents automatic detection with restart as the fallback; reopen Cursor when startup discovery needs repeating.
• Gemini workspace skill missing: Check folder trust through /permissions trust. The current configuration reference lists skills.enabled as true by default, while administrator policy can prohibit skills. Resolve a disabled setting or trust decision through the appropriate controls.
• Wrong skill runs: Inspect personal and project copies with the same name. Claude gives personal skills priority over project skills; Codex can list both; Gemini gives workspace skills priority over user skills. Prefer distinct names for genuinely different workflows.
• Listed but not selected automatically: Invoke it explicitly first. If that works, improve the description to name the task it handles. A clearer description helps selection; moving a correctly discovered file does not.
• Loaded but commands fail: Check Git availability, the working directory and the reported permission error. Directory portability does not install a runtime or grant permission to execute commands.