feat(cli): add builtin /skills sync command

[zhangxaochen]

Summary

Adds a native /skills sync slash command to automatically synchronize skills from external AI tools (Claude Code, OpenCode). This replaces the need for external shell scripts or TOML-based prompt commands, providing a faster, more reliable, and conflict-aware implementation.

Details

• High Performance: Implemented syncSkills in skillUtils.ts using Promise.all for parallel I/O, capable of handling hundreds of skill links in milliseconds.
• Robust Conflict Detection: Scans actual skill contents (SKILL.md) across multiple tiers (Extension, User Alias, User Standard) to prevent name collisions even when directory names differ (e.g., pymc/ directory vs pymc-bayesian-modeling skill name).
• Intelligent Cleanup: Automatically identifies and removes:
  • Broken symbolic links.
  • Links that conflict with native skills.
  • Redundant links pointing to the same source (standardizes naming to the actual skill name).
• Path Standardization: Handles trailing slashes and relative paths consistently during comparison.
• UI Integration: Added /skills sync subcommand to skillsCommand.ts with detailed feedback on synced, cleaned, and skipped skills.

Related Issues

Related to #21562

How to Validate

Manual Verification

1. Create a mock Claude skill:

mkdir -p ~/.claude/skills/sync-test-demo
cat <<EOF > ~/.claude/skills/sync-test-demo/SKILL.md
---
name: sync-test-demo
description: Verification skill for builtin sync
---
Sync is working!
EOF

2. Start the CLI: npm run start
3. Run the sync command: /skills sync
4. Verify the output: Sync complete. Synced 1 skill (sync-test-demo).
5. Verify the link: ls -l ~/.gemini/skills/sync-test-demo (should point to ~/.claude/skills/sync-test-demo)
6. Test cleanup: rm -rf ~/.claude/skills/sync-test-demo then run /skills sync again. It should report Cleaned up 1 stale link.

Automated Tests

Run the new comprehensive tests:
npx vitest run packages/cli/src/utils/skillUtils.test.ts packages/cli/src/ui/commands/skillsCommand.test.ts

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant enhancement to the CLI by adding a built-in /skills sync command. This command streamlines the process of integrating skills from external AI tools like Claude Code and OpenCode, eliminating the need for manual scripts or TOML configurations. The implementation focuses on performance, reliability, and user experience, ensuring that skill synchronization is fast, intelligent, and provides clear feedback on its operations.

Highlights

• New Command: Introduced a native /skills sync command for automated skill synchronization from external AI tools.
• Performance: Implemented syncSkills using Promise.all for efficient parallel I/O operations, capable of handling many skill links quickly.
• Conflict Detection: Added robust logic to detect and prevent name collisions between external and native skills by scanning actual skill contents.
• Intelligent Cleanup: Included automatic removal of broken symbolic links, links conflicting with native skills, and redundant links.
• Path Standardization: Ensured consistent handling of skill paths, including trailing slashes and relative paths during comparison.
• Enhanced UI Feedback: Provided detailed feedback to the user on synced, cleaned, and skipped skills directly in the CLI.

Changelog

• packages/cli/src/ui/commands/skillsCommand.test.ts
  • Mocked syncSkills and reloadSkills for testing purposes.
  • Added a new test suite for the sync subcommand, covering successful synchronization, already-in-sync scenarios, and error handling.
• packages/cli/src/ui/commands/skillsCommand.ts
  • Imported the new syncSkills utility.
  • Implemented the syncAction asynchronous function to handle the logic for the /skills sync command, including displaying progress and results.
  • Registered the sync subcommand with its description and action.
• packages/cli/src/utils/skillUtils.test.ts
  • Imported syncSkills and Storage.
  • Mocked os.homedir and Storage methods to control the test environment.
  • Added a new test suite for syncSkills, verifying successful synchronization from external tools, proper handling of conflicts with native skills, and cleanup of broken or conflicting symbolic links.
• packages/cli/src/utils/skillUtils.ts
  • Imported glob for pattern matching.
  • Implemented the syncSkills function, which orchestrates the skill synchronization process. This includes identifying existing native skills, scanning external skill directories, performing a cleanup pass to remove invalid or redundant links, and finally, creating symbolic links for new external skills while handling conflicts.

Activity

• No human activity (comments, reviews) has occurred on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request introduces a new /skills sync command to synchronize skills from external tools. The implementation is well-structured, using parallel operations for performance and including logic for conflict detection and cleanup. The associated UI command and tests are also comprehensive.

[jackwotherspoon]

I am not sure I agree that this should be something we add into Gemini CLI natively.

Agent Skills are standardized and we support reading from .agents/skills which most providers support as well.

For providers like CC who do not support .agents you can still create a symbolic link outside of Gemini CLI.

What is the value to adding the command into Gemini CLI, better discoverability?

Not sure the maintenance burden of this code justifies it.

But happy to discuss and hear more on the use-case or something I may be missing here 😁

[zhangxaochen]

Thank you for the thoughtful feedback, @jackwotherspoon! I really appreciate your perspective on keeping the core lean and adhering to the .agents/skills standard.

The primary motivation for this PR comes from handling skill collections at scale. While manual symbolic linking or the existing /skills link works well for a handful of skills, users often have massive collections (e.g., 200+ skills in Claude Code's directory). At this scale, manual management becomes quite difficult for a few reasons:

1. Content-Aware Conflict Detection: Unlike a simple shell ln -s, this builtin command parses the actual SKILL.md files. This is crucial because directory names often differ from the actual registered skill names (e.g., a folder named pymc might provide a skill named pymc-bayesian-modeling). Manual linking in such cases frequently leads to "Skill conflict detected" errors that are hard for users to debug. This implementation prevents those collisions automatically across all tiers (Extensions, User Alias, and User Standard).
2. Environment Self-Healing: It automatically identifies and prunes broken symbolic links and removes redundant links (standardizing them to the official skill name). This keeps the user's environment clean without them needing to hunt through hidden directories.
3. Performance at Scale: I've implemented the scanning logic using Promise.all to ensure that even with hundreds of links, the synchronization is nearly instantaneous.

I agree that maintenance burden is always a concern. To mitigate this, I've included a comprehensive test suite covering these edge cases. My goal was to provide a "one-click" experience for users moving between tools, making Gemini CLI the most seamless hub for their entire skill library.

I'm very open to your suggestions on how we might refine this logic to be even lighter or more aligned with the project's long-term vision! 😁

[jackwotherspoon]

@zhangxaochen I am not sure I follow the above.

While manual symbolic linking or the existing /skills link works well for a handful of skills, users often have massive collections (e.g., 200+ skills in Claude Code's directory). At this scale, manual management becomes quite difficult for a few reasons:

You can create a single symbolic link from .claude/skills folder to .gemini/skills folder and all 200+ skills now become available.

Which I think is probably the best to recommend for the time being. I don't think we want to be maintaining this and would rather hope that CC adds support for .agents/skills soon.

I could see in the future us wanting to add a gemini migrate command or something to migrate from other providers. But that could be brittle as we then are at the mercy of the other providers implementing breaking changes.

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we have updated our contribution policy (see Discussion #17383).

We only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'. All other community pull requests are subject to closure after 14 days if they do not align with our current focus areas. For this reason, we strongly recommend that contributors only submit pull requests against issues explicitly labeled as 'help-wanted'.

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding and for being part of our community!