Local Skills Setup

Create symlinks so multiple AI tools can use the same skill definitions from .claude/.

Why? Different AI tools look for config in different places (.claude/, .agent/, GEMINI.md). This skill creates symlinks so you maintain ONE source of truth in .claude/ and AGENTS.md.

Quick Start

# Run from any repo root (script is in the global skill location)
~/.claude/skills/skills-local-setup/scripts/skills-local-setup.sh [agent|opencode|gemini|all]

Directory Structure

.claude/skills/   <- SOURCE (tracked in git)
.agent/skills/    -> symlink to .claude/skills/ (gitignored)
.opencode/skill/  -> symlink to .claude/skills/ (gitignored, singular!)
GEMINI.md         <- directive file (gitignored)

Supported Tools

Tool	Command	What It Does
Agent	`agent`	Creates `.agent/skills/` symlink to `.claude/skills/` (backward compat)
OpenCode	`opencode`	Creates `.opencode/skill/` symlink to `.claude/skills/` (singular!)
Gemini	`gemini`	Creates `GEMINI.md` with directive to load `AGENTS.md`
All	`all`	Sets up all compatibility layers (agent + opencode + gemini)

[!NOTE] .claude/skills/ is the source of truth and should be tracked in git. Only the compatibility symlinks/files are gitignored.

Workflow

1. Run the Setup Script

# From repo root — script lives in the global skills directory
~/.claude/skills/skills-local-setup/scripts/skills-local-setup.sh [agent|opencode|gemini|all]

The script automatically:

Validates prerequisites (git repo)
Creates .claude/skills/ directory if needed (source of truth, tracked in git)
Creates compatibility symlinks with relative paths
Adds symlinks/directive files to .gitignore
Asks for Y/N confirmation before overwriting existing files
Migrates existing .agent/settings.json to .claude/settings.json if found

[!TIP] If AGENTS.md doesn't exist when setting up Gemini, the script will instruct you to run the skills-index-updater skill first to create it.

2. Verify Setup

# Check directories and symlinks
ls -la .claude/ .agent/ .opencode/ GEMINI.md 2>/dev/null

# Check .gitignore (should NOT include .claude/)
grep -E "GEMINI|\.agent|\.opencode" .gitignore

# Check git status (symlinks should be ignored)
git status

Quality Rules

.claude/ is the source of truth — Never edit symlinked files directly
Symlinks must be in .gitignore — Keep repo clean, only track actual content
Use relative paths — Symlinks should work regardless of absolute path
Confirm before overwriting — Script shows existing content and asks for Y/N confirmation before removing

Anti-Patterns

Don't	Why	Do Instead
Use absolute paths in symlinks	Breaks when repo moves or on other machines	Use relative paths (`../`)
Commit symlinks to git	Creates merge conflicts, breaks for others	Add to `.gitignore`
Edit `.agent/` directly	Changes won't persist (it's a symlink)	Edit `.claude/` instead
Run outside repo root	Symlinks will be created in wrong location	`cd` to repo root first

Validation Checklist

Before considering setup complete:

ls -la shows symlinks pointing to correct targets
git status shows no untracked symlinks
.gitignore contains entries for all symlinks

Troubleshooting

Problem	Cause	Solution
"File exists" error	Target already exists	Check if it's a symlink first, backup if needed
Symlink broken after clone	Absolute path used	Recreate with relative path
Changes not syncing	Editing symlink, not source	Edit `.claude/` directly
Git tracking symlink	Missing .gitignore entry	Add entry to .gitignore
AGENTS.md not found	Missing AGENTS.md file	Run `/skills-index-updater` skill first