Symlink entire skills directory instead of individual skill entries

[aviadr1]

Problem

agentsync currently symlinks individual skills into .claude/skills/ instead of symlinking the directory itself.

Proposal

When syncing skills, create a single directory-level symlink:

• .claude/skills -> .agents/skills

instead of creating per-skill symlinks/files.

Why this is better

• New skills created by Claude under .claude/skills/ automatically appear in .agents/skills/.
• Keeps skill namespace unified and avoids drift between the two paths.
• Simplifies sync logic and reduces per-skill link management edge cases.

Expected behavior

If .agents/skills exists, agentsync should prefer creating/updating a directory symlink for .claude/skills (with clear fallback behavior on filesystems that do not support symlinks).

[linear]

DALLAY-197

[aviadr1]

Adding concrete rationale and examples for why directory-level symlinking is the better default.

Stronger reasoning

1) Prevents drift that per-skill links cannot avoid cleanly

Per-skill linking only syncs skills that existed at apply-time. New skills created later under .claude/skills/* (or renamed dirs) can silently diverge until a later apply.

With .claude/skills -> .agents/skills, create/rename/delete is immediately unified because both paths resolve to the same tree.

2) Correct-by-construction for bidirectional authoring

Teams often author from different contexts:

• one person adds ./.agents/skills/new-skill/SKILL.md
• another adds ./.claude/skills/another-skill/SKILL.md

Per-skill links require reconciliation and cleanup logic. Directory symlink removes reconciliation entirely.

3) Lower AgentSync complexity

Per-skill mode must handle lifecycle edge cases:

• newly added skill directories
• removed skills and stale links
• renamed skills (delete old link + create new link)
• partial failures during apply

Single directory symlink is one atomic invariant.

4) Better DX for frequent skill iteration

Skill development is iterative: create, rename, split, merge, delete. Directory-level symlink means no resync thinking during that loop.

Concrete examples

Example A: New skill after apply

1. Run agentsync apply (per-skill links created)
2. Add .claude/skills/mine-ideas/SKILL.md
3. Expectation: canonical .agents/skills reflects it

Per-skill: not reflected until next apply (easy to miss).
Dir symlink: reflected immediately.

Example B: Rename skill folder

1. Rename .agents/skills/post-run-report -> .agents/skills/post-report

Per-skill: old destination link can remain stale depending on cleanup path.
Dir symlink: rename is inherently consistent under both paths.

Example C: Parallel edits

Two contributors edit via different roots (.claude/skills vs .agents/skills).

Per-skill: can create “which side is canonical?” confusion.
Dir symlink: both entrypoints map to one tree.

Suggested policy

• Prefer directory-level symlink for skills targets when source is a directory.
• Fall back to per-skill materialization only when dir symlinks are unavailable.
• Emit explicit mode in dry-run/apply output, e.g. skills sync mode: dir-symlink vs fallback: per-skill-copy.

Acceptance criteria

• Creating a skill in either path appears in the other path without rerunning apply.
• Renaming/deleting skill dirs cannot leave stale entries after apply.
• Dry-run clearly states chosen strategy and fallback reason.

This gives the behavior users intuitively expect: one canonical skills tree, multiple entrypoints, no drift.

[yacosta738]

@aviadr1 This issue should be resolved in version >=1.35.0. Please try again in a repository and see if the configuration import works correctly.