Adonis0123/adonis-skills / .agents/skills/agent-symlink-init
agent-symlink-init
VerifiedInitialize or migrate agent-skill symlinks in any repository. Use when a project needs `.claude/skills` linked to `.agents/skills`, `AGENTS.md` linked to `CLAUDE.md`, migration away from `.ruler`-based AI rules, or removal of legacy `sync-llm-skills` copy/sync setups. Trigger on requests about Claude/Codex skill symlinks, AGENTS/CLAUDE symlinks, `.claude/skills` setup, replacing copied skill folders with symlinks, or cleaning old ruler/sync automation.
Agent Symlink Init
Set up or migrate a repository to the symlink-based agent-skill layout.
Outcomes
- Make
.agents/skillsthe source of truth. - Ensure
.claude/skillspoints at the repository's.agents/skillsdirectory. - Ensure
AGENTS.mdis a symlink toCLAUDE.mdwhenCLAUDE.mdexists. - Remove obsolete ruler or sync automation only when it is actually present and the user explicitly requested that migration.
- Keep the migration idempotent and non-destructive.
Detect Before Editing
Confirm the requested repository or project root before editing. For a Git repository, use git rev-parse --show-toplevel and work from that root within the authorized scope. Do not require .git to be a directory: worktrees and separate Git directories use a .git file. A package.json alone does not prove a Git root.
For a non-Git project, use the root explicitly identified by the user; if it is unclear, ask for the target directory. Perform only the requested filesystem setup and report that Git tracking checks are unavailable.
Inspect these paths first:
.agents/skills.claude/skillsCLAUDE.mdAGENTS.md- the .ruler directory
- the sync-llm-skills.ts script under the scripts directory
package.json.gitignore
Classify the work into these modules:
symlink-initRun when.claude/skillsis missing or does not point at the repository's.agents/skillsdirectory, or whenAGENTS.mdshould point toCLAUDE.mdbut does not.migrate-from-rulerOffer when a .ruler directory exists orpackage.jsonstill contains ruler-related scripts orpostinstallfragments. Run only when the user's request includes migrating/removing ruler.migrate-from-syncOffer when legacy copy-based sync automation exists. A--sync-llmflag alone is not proof: inspect the referenced script/function. If it only ensures.claude/skills -> .agents/skills, it already implements the target symlink model and must remain.
Detection identifies candidates; it does not authorize every module. Run symlink-init alone when that is all the user requested. Before deleting .ruler, sync scripts, or package scripts, require a request that clearly authorizes that migration and name the exact removal set. Preserve or back up untracked/otherwise hard-to-recover content before replacement or deletion.
If the user explicitly names only one link, narrow symlink-init to that link. For example, “only initialize .claude/skills” must not create or replace AGENTS.md; report the other link as an optional follow-up instead.
Execute symlink-init
- Ensure
.agents/skillsexists:
mkdir -p .agents/skills
- Ensure
.claudeexists:
mkdir -p .claude
- If
.claude/skillsis a regular directory or file instead of a symlink, preserve it before replacing it:- Prefer a backup named .claude/skills.bak
- If that backup path already exists, choose a timestamped backup name
- Create or refresh the symlink:
ln -sfn ../.agents/skills .claude/skills
- Unless the user narrowed the request to
.claude/skillsonly, ifCLAUDE.mdexists, ensureAGENTS.mdpoints to it:- If
AGENTS.mdis a regular file, back it up before replacing it
- If
ln -sfn CLAUDE.md AGENTS.md
- Update
.gitignore:- Remove any .claude/skills and AGENTS.md ignore entries if they exist. These symlinks must be tracked by git so that collaborators get them on clone.
- Remove any associated comments (e.g.
# Agent skills (symlinked),# START Ruler Generated Files). - Do not add new ignore entries for the symlinks.
Execute migrate-from-ruler
Run this module only when ruler artifacts still exist and the user requested ruler migration/removal.
- Remove the .ruler directory.
- Edit
package.json:- Remove scripts whose keys clearly belong to ruler automation, such as
ruler:applyorruler:check - Remove only the ruler-related fragment from
postinstall - Remove
postinstallentirely if nothing remains
- Remove scripts whose keys clearly belong to ruler automation, such as
- Edit
.gitignore:- Remove ruler-specific ignore entries (e.g. ruler block comments,
/CLAUDE.md,/AGENTS.mdif they were ruler-generated ignores) - Do not re-add
/AGENTS.mdto.gitignore— the symlink must be tracked by git
- Remove ruler-specific ignore entries (e.g. ruler block comments,
- Do not delete
CLAUDE.mdunless the user explicitly asks. The goal is to replace the automation mechanism, not to discard the current source-of-truth document.
Execute migrate-from-sync
Run this module only when legacy copy/sync automation is present and the user requested sync migration/removal. Do not run it against a current symlink helper merely because its CLI flag is named --sync-llm.
- Remove the sync-llm-skills.ts file under
scripts/if it exists. - Edit
package.json:- Remove
scripts["skills:sync:llm"] - Remove only the
--sync-llmflag fromskills:test:localif the rest of the command is still valid - Remove sync-related fragments from
postinstall - Remove
postinstallentirely if nothing remains
- Remove
- Edit
.gitignore:- Remove the .claude/skills ignore entry and any associated comments — the symlink must be tracked by git, not ignored
- The old ignore was for copy-based sync artifacts; symlinks should be committed
- Leave
.agents/skillscontents in place. Migrate the linkage model, not the skill payload itself.
Editing Rules
- Make the smallest safe change set.
- Preserve unrelated
package.jsonscripts. - When cleaning
postinstall, remove only the obsolete command fragment and keep remaining commands in order. - Skip modules whose signals are absent.
- If the repository already matches the target layout, report that no migration is needed instead of rewriting files.
Verify
Run lightweight checks after editing:
test -L .claude/skills && readlink .claude/skills
test -f CLAUDE.md && test -L AGENTS.md && readlink AGENTS.md
Also inspect:
package.jsonfor stale ruler or sync commands.gitignorefor duplicate or contradictory entriesgit diff --stator equivalent to summarize the migration
Report Back
Return:
- Which modules ran
- Which files were created, updated, backed up, or removed
- Verification results
- Any follow-up action the user should consider, such as reinstalling dependencies if
postinstallbehavior changed
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |