Skip to content

feat: introduce 'skills link' for symlinking agent skills (like extensions link) #18294

@MushuEE

Description

@MushuEE

What would you like to be added?

This feature introduces a link command that creates symbolic links instead of copying files. It also adds support for recursive discovery, allowing a single command to
link all skills within a complex directory structure.

Key Features

1. Recursive Discovery: Automatically finds all SKILL.md files in a source tree (ignoring node_modules and .git).
2. Name Sanitization: Automatically handles skill names with characters that are invalid for filenames (e.g., gke:prs-troubleshooter becomes a directory/link named
gke-prs-troubleshooter).
3. Conflict Detection: Identifies and blocks links if multiple skills in the source path share the same name to prevent non-deterministic overwriting.
4. Atomic Overwrites: If a skill with the same name already exists at the destination, the command prompts for consent and replaces the existing directory/link with the
new symlink.
5. Interactive Support: A new /skills link slash command for management within the REPL.

Why is this needed?

Currently, the skills install command copies skill directories into the user or workspace storage. For developers working on skills locally or teams maintaining a
repository of private skills, this workflow is cumbersome because changes in the source directory aren't reflected until the skill is re-installed.

Additional context


Usage Examples

Terminal Command

Link all skills from a local repository to your global user tier:

gemini skills link ~/projects/my-local-expertise

Link skills specifically to the current workspace:

gemini skills link ./custom-tools --scope workspace

Interactive Mode

Quickly link a new skill while chatting in the REPL:

/skills link /path/to/experimental-skill

Proposed UI/UX

Discovery and Consent Output

Searching for skills in /home/user/my-skills...
Linking agent skill(s) from "/home/user/my-skills".

The following agent skill(s) will be linked:
  * foo-bar-helper: A helpful foo-bar capability
    (Source: /home/user/my-skills/foo-bar-helper/SKILL.md) (5 items in directory)

  * data-cleaner: Cleans up your messy data
    (Source: /home/user/my-skills/data-cleaner/SKILL.md) (3 items in directory)

Link Destination: /home/user/.gemini/skills
[?] Do you want to proceed? (Y/n)

### Conflict Error during Recursive Discovery (Removed)

Error: Duplicate skill name "utility-tool" found at multiple locations:
  - /home/user/my-skills/category-a/utility-tool/SKILL.md
  - /home/user/my-skills/category-b/utility-tool/SKILL.md

Technical Implementation Notes

~ - Refactor loadSkillsFromDir in @google/gemini-cli-core to support an optional recursive flag (defaulting to false to keep install shallow).~

  • Implement a centralized linkSkill utility to handle globbing, collision checking, and symlink creation.
  • Update skillsConsentString to use "Link" terminology when appropriate.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/coreIssues related to User Interface, OS Support, Core Functionalitystatus/need-triageIssues that need to be triaged by the triage automation.status/possible-duplicate

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions