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

[!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

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