Agent skill

skills-local-setup

Set up AI tool symlinks in a repository for multi-agent compatibility. Use when the user wants to set up skills for Gemini, Claude, or other AI tools, or when they mention "setup skills", "configure agents", or "link AGENTS.md".

View SKILL.md on GitHub Repository
Stars 1
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/dparedesi/agent-global-skills/tree/main/skills-local-setup

SKILL.md

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

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

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

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

dparedesi/agent-global-skills

llms-dashboard

Generate and update HTML dashboards for LLM usage (Claude, Gemini, Kiro, VS code, Cline, etc). Use when the user wants to visualize their AI coding assistant usage statistics, view metrics in a web interface, or analyze historical trends.

1 1
Explore
dparedesi/agent-global-skills

dev-browser

Browser automation with persistent page state. Use when users ask to navigate websites, fill forms, take screenshots, extract web data, test web apps, or automate browser workflows. Trigger phrases include "go to [url]", "click on", "fill out the form", "take a screenshot", "scrape", "automate", "test the website", "log into", or any browser interaction request.

1 1
Explore
dparedesi/agent-global-skills

humanize

Convert AI-written text to more human-like writing through subtle edits. Use when text reads "too AI", when the user mentions "humanize", "sounds robotic", "AI-written", "make it natural", or when editing for a more conversational voice.

1 1
Explore
dparedesi/agent-global-skills

synap-assistant

Manage a personal knowledge capture system. Use when the user wants to capture ideas, track todos, organize projects, review their synap, or mentions "synap", "brain dump", "capture this", "add to my list", "what's on my plate", "what should I focus on", or "daily review".

1 1
Explore
dparedesi/agent-global-skills

pdf

Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.

1 1
Explore
dparedesi/agent-global-skills

token-pacing

Calculate the optimal token usage burn rate to reach exactly 100% usage by reset. Use when the user asks about token budget, usage limits, spending speed, or "will I run out". Supports Claude, Gemini, Codex, VS Code, and other providers.

1 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results