| name | nacos-skill-registry |
| version | 1.0.0 |
| description | Discover, install, update, merge, publish, and synchronize AI skills with Nacos for personal or team skill registries. Route detailed skill-sync workflows to https://nacos.io/skill-sync/SKILL.md. |
Nacos Skill Registry
This skill helps you discover, install, update, merge, publish, and route synchronization workflows for AI skills through
Nacos using the nacos-cli tool.
When to Use This Skill
Use this skill when the user:
- Asks "how do I do X" where X might be a task with an existing skill in Nacos
- Says "find a skill for X" or "is there a skill in Nacos for X"
- Asks "what skills are available" or "list skills from Nacos"
- Wants to search for tools, templates, or workflows stored in Nacos
- Needs to download or install a skill from a personal, team, or organization Nacos registry
- Wants to upload or publish a local skill to Nacos for reuse
- Mentions sharing or synchronizing skills across agents, machines, teammates, or execution environments
- Asks about
nacos-cli skill-sync; route detailed sync workflow questions to https://nacos.io/skill-sync/SKILL.md
- Needs to merge local skill edits with a newer remote version and publish the merged result
What is nacos-cli?
The nacos-cli is a command-line tool for interacting with Nacos. It supports configuration management, skill management, agent spec management, and provides an interactive terminal.
GitHub: https://github.com/nacos-group/nacos-cli
Key skill commands:
nacos-cli skill-list -- Search and list available skillsnacos-cli skill-get <name...> -- Download and install one or more skills locallynacos-cli skill-upload <path> -- Upload a skill and create an editing draftnacos-cli skill-review <name> [--version <version>] -- Submit a draft for reviewnacos-cli skill-release <name> --version <version> -- Release an approved version onlinenacos-cli skill-describe <name> -- Inspect skill metadata and per-version status
Other commands:
nacos-cli profile list|show|set|get|switch|edit|delete -- Manage connection profilesnacos-cli skill-sync -- Synchronize skills across local agent directories, with optional Nacos-backed trackingnacos-cli config-list|config-get|config-set -- Manage Nacos configurationsnacos-cli agentspec-list|agentspec-get|agentspec-upload|agentspec-review|agentspec-release|agentspec-describe -- Manage agent specsnacos-cli interactive -- Start interactive terminal modenacos-cli completion [bash|zsh|fish|powershell] -- Generate shell completion scripts
Version-Aware CLI Contract
Always check the installed nacos-cli version and available skill commands before publishing or documenting a workflow:
nacos-cli -v
nacos-cli --help
Use the command contract that matches the installed version:
| Installed CLI | Skill publish workflow | Notes |
|---|
1.0.4 | skill-upload -> skill-review -> wait for approval -> skill-release | Current lifecycle. skill-publish is deprecated and only runs upload + review for compatibility. |
| Any other version | Inspect nacos-cli --help and command-specific help | Do not hard-code old behavior. Follow the commands actually present in the installed CLI. |
For 1.0.4, treat these as distinct states:
skill-upload: creates or updates an editing draft versionskill-review: submits the draft, moving it toward reviewingskill-describe: use this to confirm the submitted version has passed reviewskill-release: publishes a reviewed/approved version online; it requires an explicit --version
How to Help Users Find and Install Skills
Step 1: Ensure nacos-cli is Available
Check if nacos-cli is installed:
which nacos-cli
Use the npm package through npx if you do not want to install a persistent local binary:
npx @nacos-group/cli --help
npx @nacos-group/cli skill-list --host 127.0.0.1 --port 8848 -u nacos -p nacos
When using npx, replace nacos-cli in the examples below with npx @nacos-group/cli. For non-interactive agent
runs, use npx -y @nacos-group/cli ... if npx would otherwise prompt before downloading the package.
For a persistent local install, use the official installer script:
Linux / macOS:
curl -fsSL https://nacos.io/nacos-installer.sh | sudo bash -s -- --cli
Windows (PowerShell):
iwr -UseBasicParsing https://nacos.io/nacos-installer.ps1 -OutFile $env:TEMP\nacos-installer.ps1; & $env:TEMP\nacos-installer.ps1 -cli; Remove-Item $env:TEMP\nacos-installer.ps1
Step 2: Resolve Configuration (Profile)
nacos-cli uses a profile mechanism. Profile configs are stored in ~/.nacos-cli/<profile>.conf. The default profile is default (i.e., ~/.nacos-cli/default.conf).
Use nacos-cli profile ... commands instead of asking the user to edit profile files by hand.
Before asking the user to create or edit a profile, check whether the environment already provides a complete
sts-hiclaw setup:
printenv NACOS_AUTH_TYPE HICLAW_CONTROLLER_URL HICLAW_AUTH_TOKEN_FILE
If NACOS_AUTH_TYPE=sts-hiclaw, HICLAW_CONTROLLER_URL is set, and HICLAW_AUTH_TOKEN_FILE points to a readable local
token file, use sts-hiclaw mode directly. Do not require a local ~/.nacos-cli/<profile>.conf file in this case.
You can verify connectivity directly:
nacos-cli skill-list
Treat NACOS_AUTH_TYPE as the source of truth for environment-based auth selection. If it is not set to sts-hiclaw,
do not assume sts-hiclaw mode only because HICLAW_CONTROLLER_URL and HICLAW_AUTH_TOKEN_FILE exist. Fall back to
profile initialization when the explicit environment-based setup is missing or fails.
First, inspect available profiles:
nacos-cli profile list
nacos-cli profile show
nacos-cli profile show <profile>
If a usable profile exists, proceed to Step 3. The current/default profile requires no extra flags:
nacos-cli skill-list
To use a named profile:
nacos-cli --profile dev skill-list
If no usable profile exists, guide the user through first-time initialization.
First-Time Profile Initialization
Ask the user the following information:
- Nacos server address: the host and port of their Nacos server (e.g.,
127.0.0.1:8848, or a remote address like nacos.example.com:8848)
- Auth type:
none, nacos, aliyun, or sts-hiclaw
- Credentials:
- For
none auth: no credentials are required
- For
nacos auth: username and password from the user's local Nacos instance
- For
aliyun auth: AccessKey and SecretKey
- For
sts-hiclaw auth: credentials are fetched dynamically from HiClaw STS; the local environment must provide
HICLAW_CONTROLLER_URL and HICLAW_AUTH_TOKEN_FILE
- Namespace (optional): the Nacos namespace ID to use. Leave empty for the default public namespace.
Once the user provides the info, create or update the profile with profile set. The command creates the profile if it
does not exist, and sensitive values are encrypted before being saved.
nacos-cli profile set default server=<host>:<port> auth-type=none namespace=<namespace>
nacos-cli profile set dev server=<host>:<port> auth-type=nacos username=<username> password=<password> namespace=<namespace>
nacos-cli profile set dev server=<host>:<port> auth-type=aliyun access-key=<access-key> secret-key=<secret-key> namespace=<namespace>
Use host=<host> port=<port> instead of server=<host>:<port> if the values are already separate. Add scheme=https
when the server requires HTTPS. Omit namespace=<namespace> when using the default public namespace. Do not include
concrete usernames, passwords, access keys, or secret keys in shared docs or skill examples.
For sts-hiclaw, set the auth type but do not store STS credentials in the profile:
nacos-cli profile set dev server=<host>:<port> auth-type=sts-hiclaw namespace=<namespace>
The CLI reads HICLAW_CONTROLLER_URL and HICLAW_AUTH_TOKEN_FILE, then requests temporary credentials from
$HICLAW_CONTROLLER_URL/api/v1/credentials/sts.
After writing the profile, verify it:
nacos-cli profile show <profile>
nacos-cli profile get <profile> server
nacos-cli profile get <profile> auth-type
Then do a quick connectivity test:
nacos-cli --profile <profile> skill-list
Omit --profile <profile> when testing the current/default profile.
If the connection succeeds, tell the user:
Profile initialized! nacos-cli is now connected to <host>:<port>.
You can start searching and installing skills.
If it fails (auth error, connection refused, etc.), help the user troubleshoot:
- Connection refused -> check host/port, is Nacos server running?
- 401/403 -> check username/password or AK/SK
- Namespace error -> verify the namespace ID is correct
Additional Profile Operations
For multiple Nacos servers, use named profiles:
nacos-cli profile set dev server=<host>:<port> auth-type=<auth-type> namespace=<namespace>
nacos-cli --profile dev skill-list
If the user wants a named profile to become the default when --profile is omitted:
nacos-cli profile switch dev
For inspection and maintenance:
nacos-cli profile list
nacos-cli profile get dev
nacos-cli profile edit dev
nacos-cli profile delete dev
Use profile delete only when the user explicitly asks to remove a profile.
Step 3: Understand What They Need
When a user asks for help, identify:
- The domain (e.g., code review, testing, deployment, documentation)
- The specific task (e.g., writing tests, reviewing PRs, generating docs)
- Whether this is a common enough task that a skill likely exists in Nacos
Step 4: Search for Skills
List all skills:
nacos-cli skill-list
Filter by name (supports wildcard *):
nacos-cli skill-list --name "creator"
With pagination:
nacos-cli skill-list --page 2 --size 10
For example:
- User asks "can you help me review code?" ->
nacos-cli skill-list --name review
- User asks "is there a skill for testing?" ->
nacos-cli skill-list --name test
- User asks "what skills do we have?" ->
nacos-cli skill-list
The command returns results in this format:
Skill List (Page: 1/1, Total: N)
-------------------------------------------------------------------------------
1. <skill-name> - <description>
latest=<version> editing=<version-or-> reviewing=<version-or-> online=<count> status=enabled
scope=<scope> owner=<owner> updated=<yyyy-mm-dd hh:mm:ss> downloads=<count>
...
For scripts or exact verification, use JSON output:
nacos-cli skill-list --name <skill-name> --output json
nacos-cli skill-describe <skill-name> --output json
Step 5: Present Options to the User
When you find relevant skills, present them clearly:
- Summarize what skills were found
- Highlight the most relevant skill(s) based on user's needs
- Provide the install command
Example response:
I found N skills in Nacos. The most relevant one for your needs is:
**<skill-name>** - <description>
To install it:
nacos-cli skill-get <skill-name>
This will download the skill to ~/.skills/ and make it available immediately.
Would you like me to install it?
Step 6: Install the Skill
Download and install a skill:
nacos-cli skill-get <skill-name>
Download multiple skills at once:
nacos-cli skill-get skill-a skill-b skill-c
Download a specific version:
nacos-cli skill-get <skill-name> --version v2
Download via route label (e.g., latest, stable):
nacos-cli skill-get <skill-name> --label stable
Download to a custom directory (default is ~/.skills):
nacos-cli skill-get <skill-name> -o ~/my-skills
After installation, confirm the skill is available:
ls ~/.skills/<skill-name>/SKILL.md
Step 7: Keep Skills Synchronized Across Agents (Optional)
nacos-cli also supports skill-sync for keeping skills synchronized across local agent directories such as Codex,
Claude, Qoder, Cursor, Kiro, ~/.agents/skills, and ~/.skills. It can run in local-only mode or track skills through
a Nacos profile.
Use it when the user wants one skill source shared across agents, automatic linking, background synchronization, or
Nacos-backed team distribution:
nacos-cli skill-sync status
nacos-cli skill-sync add <skill> --profile <profile> --non-interactive
nacos-cli skill-sync start --profile <profile> --non-interactive
Keep the main Nacos Skill Registry workflow in this skill concise. For detailed skill-sync behavior, conflict handling,
agent directory management, daemon state, and local-only mode, route to the dedicated skill:
https://nacos.io/skill-sync/SKILL.md
Handling Version Conflicts When Updating Skills
When a user wants to update a locally installed skill from Nacos, there may be a conflict: the user has made local edits to the skill, and Nacos also has a newer version. This section describes how to detect and resolve such conflicts.
Understanding Skill Metadata
When nacos-cli skill-get installs a skill, it creates a _meta.json file in the skill directory with version and origin info:
{
"ownerId": "abc123",
"slug": "skill-name",
"version": "1.0.1",
"publishedAt": 1771756867954
}
Key fields:
version -- The version that was installed from NacospublishedAt -- Timestamp (epoch ms) of when this version was published on Nacosslug -- The skill's unique name in the registry
If the active local skill directory does not have _meta.json (for example, a skill under $CODEX_HOME/skills), use the
version field in SKILL.md frontmatter as the local version. If both exist, prefer _meta.json for install-origin
metadata and use SKILL.md frontmatter as a consistency check.
Step 1: Detect Local Changes
Before updating a skill, check if the user has made local modifications since it was installed.
Read the metadata:
cat ~/.skills/<skill-name>/_meta.json
Check if any files (excluding _meta.json) have been modified after the install. Compare file modification times against the publishedAt timestamp:
PUBLISHED_AT=$(python3 -c "import json; print(json.load(open('$HOME/.skills/<skill-name>/_meta.json'))['publishedAt'] / 1000)")
find ~/.skills/<skill-name> -name '_meta.json' -prune -o -newer <reference> -print
Or more simply, compare the SKILL.md modification time with the publishedAt timestamp. If the file was modified after install, there are local changes.
Step 2: Check Remote Version
Query the remote to see if a newer version is available:
nacos-cli skill-list --name <skill-name>
nacos-cli skill-describe <skill-name>
On nacos-cli 1.0.4, prefer skill-describe for version comparison because it shows each version and its lifecycle
status. Compare the remote online/latest version with the local _meta.json version. If the remote version is newer, an update is available.
If _meta.json is absent, compare the remote online/latest version with the version field in the local SKILL.md
frontmatter.
On older CLIs that do not have skill-describe, use skill-list --name <skill-name> and the fields available in that version.
Step 3: Determine the Scenario
Based on the results of Step 1 and Step 2, there are four possible scenarios:
| Local Changes? | Remote Newer? | Action |
|---|
| No | No | Already up to date. No action needed. |
| No | Yes | Safe update -- pull remote directly. |
| Yes | No | Local is ahead -- suggest publishing local changes. |
| Yes | Yes | Conflict -- needs resolution (see below). |
Version gate for publishing local edits:
- If the local version and remote online/latest version are the same, the remote has not advanced beyond the local base.
When local files contain intended edits, publish the local skill directly according to the installed CLI contract.
- If the remote online/latest version is greater than the local version, do not upload the local directory directly.
Download the newer remote version, diff it against the local directory, merge remote changes with local edits, then
publish the merged result as a new version.
- Example: local
0.0.6 and remote latest 0.0.6 means local edits can be uploaded. Local 0.0.6 and remote latest
0.0.7 means merge remote 0.0.7 first.
Step 4: Resolve Conflicts
When both local changes and a newer remote version exist, present the user with two options:
Option A: Discard local changes, use remote version
This is the simpler path. Back up the local version first, then overwrite with the remote:
cp -r ~/.skills/<skill-name> /tmp/<skill-name>-local-backup
nacos-cli skill-get <skill-name>
Tell the user:
Local changes have been backed up to /tmp/<skill-name>-local-backup.
The skill has been updated to the latest remote version (<remote-version>).
If you need to recover your local changes, the backup is available.
Option B: Merge local and remote changes, then submit a new version
This preserves both local and remote changes. The workflow:
cp -r ~/.skills/<skill-name> /tmp/<skill-name>-local-backup
nacos-cli skill-get <skill-name> -o /tmp/<skill-name>-remote
diff /tmp/<skill-name>-local-backup/SKILL.md /tmp/<skill-name>-remote/<skill-name>/SKILL.md
After reviewing the diff:
- Help the user merge the changes in
~/.skills/<skill-name>/ -- incorporate remote improvements while preserving local customizations.
- Keep the skill itself stateless. Runtime data such as processed issues, PR tracking, task state, or local work logs must stay in a user-level workspace outside agent-specific skill directories.
- Validate the merged skill before publishing.
- Publish or submit the merged result using the installed CLI contract.
For nacos-cli 1.0.4:
nacos-cli skill-upload ~/.skills/<skill-name>
nacos-cli skill-review <skill-name>
nacos-cli skill-describe <skill-name>
nacos-cli skill-release <skill-name> --version <new-version>
nacos-cli skill-describe <skill-name>
For any other version, inspect command help first and follow the installed behavior:
nacos-cli --help
nacos-cli skill-upload --help
nacos-cli skill-review --help
nacos-cli skill-release --help
nacos-cli skill-publish --help
Tell the user:
I've merged the local changes with the remote version.
- Local version: <local-version>
- Remote version: <remote-version>
- Merged version: <new-version>
The merged skill has been processed according to the installed nacos-cli contract.
- Target version: <new-version>
- Final status: <online|reviewing|editing>
- Latest label: <latest-version>
- Verification command: <skill-describe or skill-list command used>
Step 5: Present the Choice to the User
When a conflict is detected, always explain the situation clearly before acting:
Conflict detected for skill "<skill-name>":
- Local version: <local-version> (with local modifications)
- Remote version: <remote-version>
How would you like to proceed?
A) Discard local changes and update to the remote version (your changes will be backed up)
B) Merge local and remote changes, then publish as a new version
Never overwrite local changes without asking. Always back up before any destructive operation.
How to Help Users Publish Skills to Nacos
When a user wants to reuse or share a skill by publishing it to Nacos, follow these steps.
Step 1: Ensure nacos-cli is Available and Configured
Same as the discovery flow above -- check which nacos-cli, then use either a configured profile or the environment-based
sts-hiclaw setup. If NACOS_AUTH_TYPE=sts-hiclaw, HICLAW_CONTROLLER_URL, and HICLAW_AUTH_TOKEN_FILE are already set,
do not require nacos-cli profile show to succeed before publishing.
Step 2: Verify the Skill Directory
A valid skill directory must contain a SKILL.md file with proper frontmatter (name, description). Confirm the path:
ls <path-to-skill>/SKILL.md
If the file doesn't exist or lacks frontmatter, help the user create or fix it before publishing.
Step 3: Publish the Skill
First confirm the installed CLI contract:
nacos-cli -v
nacos-cli --help
Before uploading a locally edited skill, compare the local version with the remote online/latest version using
nacos-cli skill-describe <skill-name> --output json. If they match, proceed with upload/review/release. If the remote
version is newer, stop the direct publish path and use the conflict merge workflow above before publishing.
For nacos-cli 1.0.4, use the explicit lifecycle:
nacos-cli skill-upload ./my-skill
nacos-cli skill-review my-skill
nacos-cli skill-describe my-skill
nacos-cli skill-release my-skill --version <version>
nacos-cli skill-describe my-skill
Upload all skills in a directory:
nacos-cli skill-upload --all ./skills-folder
For 1.0.4, skill-publish is deprecated. It only runs skill-upload + skill-review for compatibility and does not complete skill-release.
For any other version, inspect command help before acting. Do not assume whether skill-publish uploads only or upload+submits.
Step 4: Verify the Publish
After upload/review/release, verify the exact version, not only that the skill name appears in skill-list.
nacos-cli skill-list --name <skill-name>
nacos-cli skill-describe <skill-name>
nacos-cli skill-describe <skill-name> --output json
For nacos-cli 1.0.4, the minimal acceptance check is:
- before release: target version is reviewed/approved in
skill-describe; do not run skill-release while it is only editing or still waiting for review
- after release: target version is
online
- if
--update-latest=false was not used: labels.latest equals the target version
- after downloading a specific version: local
_meta.json version equals the requested version
Example response to user:
Your skill "<skill-name>" has been processed with the installed nacos-cli workflow.
- Target version: <version>
- Final status: <online|reviewing|editing>
- Latest label: <latest-version>
Other agents, machines, or teammates can install it with:
nacos-cli skill-get <skill-name>
Connection Reference
Global flags (can override profile settings on any command):
| Flag | Short | Description |
|---|
| --host | | Nacos server host (e.g., 127.0.0.1) |
| --port | | Nacos server port (e.g., 8848) |
| --username | -u | Username for nacos auth |
| --password | -p | Password for nacos auth |
| --namespace | -n | Namespace ID |
| --profile | | Profile name, loads ~/.nacos-cli/<profile>.conf |
| --config | -c | Path to a config file (overrides profile) |
| --auth-type | | Auth type: none, nacos, aliyun, or sts-hiclaw |
| --access-key | | AccessKey for aliyun auth |
| --secret-key | | SecretKey for aliyun auth |
| --security-token | | STS SecurityToken for legacy/explicit sts-hiclaw auth |
For sts-hiclaw, prefer environment-based temporary credentials instead of storing credential values in a profile:
export NACOS_AUTH_TYPE=sts-hiclaw
export HICLAW_CONTROLLER_URL=<your-hiclaw-controller-url>
export HICLAW_AUTH_TOKEN_FILE=<path-to-local-token-file>
nacos-cli skill-list
Treat NACOS_AUTH_TYPE as the source of truth. Do not assume sts-hiclaw mode unless NACOS_AUTH_TYPE=sts-hiclaw is
set explicitly.
When No Skills Are Found
If no relevant skills exist in Nacos:
- Acknowledge that no existing skill was found
- Offer to help with the task directly using general capabilities
- Suggest creating and publishing a new skill
Example:
I searched for skills related to "xyz" in Nacos but didn't find any matches.
I can still help you with this task directly! Would you like me to proceed?
If this is something your team does often, you could create a skill and
publish it to Nacos for everyone:
nacos-cli skill-upload /path/to/your-skill
nacos-cli skill-review <skill-name>
nacos-cli skill-release <skill-name> --version <version>
Tips for Effective Use
- Use specific keywords: "react testing" is better than just "testing" when filtering
- Try alternative terms: If "deploy" doesn't work, try "deployment" or "ci-cd"
- Check namespaces: Different teams may store skills in different Nacos namespaces -- use
-n <namespace> to switch
- Use profiles: Save connection details with
nacos-cli profile set, inspect them with profile list/show/get, and switch defaults with profile switch
- Version and label: Use
--version or --label with skill-get to pin specific skill versions
- Shell completion: Run
nacos-cli completion zsh (or bash/fish) for tab completion support
