majiayu000 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.jsonto.claude/settings.jsonif found
[!TIP] If
AGENTS.mddoesn't exist when setting up Gemini, the script will instruct you to run theskills-index-updaterskill 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 -lashows symlinks pointing to correct targets -
git statusshows no untracked symlinks -
.gitignorecontains 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 |