nacos-skill-registry

name nacos-skill-registry description Discover, install, update, merge, and publish AI skills with Nacos for personal or team skill registries. Nacos Skill Registry This skill helps you discover, install, update, merge, and publish 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 skills across agents, machines, teammates, or execution environments 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 skills nacos-cli skill-get <name...> — Download and install one or more skills locally nacos-cli skill-upload <path> — Upload a skill and create an editing draft nacos-cli skill-review <name> [--version <version>] — Submit a draft for review nacos-cli skill-release <name> --version <version> — Release an approved version online nacos-cli skill-describe <name> — Inspect skill metadata and per-version status Other commands: nacos-cli profile edit|show [name] — Manage connection profiles nacos-cli config-list|config-get|config-set — Manage Nacos configurations nacos-cli agentspec-list|agentspec-get|agentspec-upload|agentspec-review|agentspec-release|agentspec-describe — Manage agent specs nacos-cli interactive — Start interactive terminal mode nacos-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 version skill-review : submits the draft, moving it toward reviewing skill-describe : use this to confirm the submitted version has passed review skill-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 If not found, install it using 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 ). 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, check if a default profile already exists: nacos-cli profile show If a profile exists (the command prints config content), proceed to Step 3. The default profile requires no extra flags: nacos-cli skill-list To use a named profile: nacos-cli --profile dev skill-list If no profile exists (the command reports an error or shows empty/default values), 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 the local profile file on their machine: mkdir -p ~/.nacos-cli ${EDITOR:-vi} ~/.nacos-cli/default.conf Tell the user to fill in only their local connection values: host, port, auth type, credentials when the selected auth type needs them, and namespace. Do not include concrete usernames, passwords, access keys, or secret keys in shared docs or skill examples. For sts-hiclaw , the profile should set authType: sts-hiclaw ; do not store STS credentials in the profile. 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 config, verify it works: nacos-cli profile show Then do a quick connectivity test: nacos-cli skill-list 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 Creating Additional Profiles If the user needs to connect to multiple Nacos servers (e.g., dev and prod), they can create named profiles: # Create or edit a named profile locally (e.g., "dev") mkdir -p ~/.nacos-cli ${EDITOR:-vi} ~/.nacos-cli/dev.conf Do not hard-code real credentials in shared docs, repositories, or skill examples. Fill the local profile with the actual host, auth type, username, password, and namespace only on the user's machine. Then use it with --profile : nacos-cli --profile dev skill-list 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 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 Nacos publishedAt — Timestamp (epoch ms) of when this version was published on Nacos slug — 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: # Convert publishedAt (epoch ms) to a reference timestamp for comparison PUBLISHED_AT=$(python3 -c "import json; print(json.load(open(' $HOME /.skills/<skill-name>/_meta.json'))['publishedAt'] / 1000)" ) # Find files modified after publishedAt 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: # 1. Back up the current local skill cp -r ~/.skills/<skill-name> /tmp/<skill-name>-local-backup # 2. Pull the latest remote version (overwrites local) 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.