@xiashe/skill

Creator-facing XiaShe Skill registry helper.

This package is intentionally separate from the full @xiashe/cli product CLI and from @xiashe/agent-skill, which is the runtime feed helper for external Agents.

Purpose

xiashe-skill helps creators prepare a Skill folder for XiaShe Store and Red Skill:

• inspect a local Skill project
• run one high-level Agent-friendly publish handoff command
• run lower-level registry setup commands that prepare XiaShe and Red handoffs
• generate a public-safe Agent Ack block for anonymous cross-platform install and call analytics
• diagnose whether a local Skill has the expected registry disclosure, Agent Ack instructions, and runtime callback wiring where supported
• send labeled local verification events so the Dashboard can confirm integration health
• write an explicit xiashe.skill.json registry manifest
• build and upload the XiaShe complete Skill package to XiaShe File Storage when the xiashe target is selected
• generate one unified UPLOAD_HANDOFF.md that the creator's Agent can use with Xiaohongshu's official skillhub-upload or uploader.md
• generate optional runtime analytics snippets

It does not install background services, run postinstall hooks, read secrets, or override Red Skill upload rules. XiaShe package upload is handled by this CLI for the XiaShe-owned registry; the creator's Agent is responsible only for third-party packaging and uploading according to Xiaohongshu's official flow.

The user-facing product flow should point creators at the official publish Markdown page and the xiashe-publish Skill. Direct CLI commands are implementation details for local Agents and developers.

setup --hub all now defaults to XiaShe Store and Red Skill. It writes private .xiashe/* handoff files for local Agents, uploads the XiaShe complete package as .tgz through the registry storage flow, plus writes no-secret public runtime protocol files at xiashe/runtime.yaml, xiashe/AGENT_ACK.md, and xiashe/REGISTRY_DISCLOSURE.md for Red Markdown/YAML source packages when the target platform accepts them. Users should not need to pick files manually. When Red Skill provides uploader.md, skillhub-upload, or its own upload prompt, follow that official flow first; XiaShe keeps tokens, signing secrets, package hashes, storage ids, and private handoff files local while recording Red usage through Agent Ack when the host Agent safely calls it.

Protected Red release

A protected Red release is deliberately different from a free-source upload. It creates one reviewable v22 capability-access guide: it keeps the original local Skill name, includes a verified creator-card link that matches the local registry environment, and separates public usage copy from a minimal Agent-only protocol. The publishing Agent writes a factual 120–260-character Chinese public description from the original project’s public materials: the real Skill purpose, intended users, and the type of result users can obtain after the capability is enabled. The generated copy truthfully says the Skill enables XiaShe capability in the current Agent; it is neither a simulated preview task nor a payment notice. Then run:

npx -y @xiashe/[email protected] publish . --to xiashe,red --protected-red \
  --red-connector-description "<120–260 character public Skill description>"

The command uploads the private package to XiaShe, then creates the dedicated red-skill-upload/ folder containing exactly one root SKILL.md. It does not ask the creator to configure a Red identifier or a separate display name: by default both come from the original project. --red-connector-description is normalized with Unicode NFKC and must state the original Skill’s purpose, intended users, and result type. --red-preview and --red-description remain compatible aliases. The legacy --red-public-starter flag is ignored so an old Agent task cannot bring preview copy back. The only URL exception is one verified creator-card link from the current registry environment. On first real use, the Agent must show that card and ask once before it can make any request—even if the first message already says “开始使用” or “获取完整版”. Only an answer to that question may use the embedded four-field POST. Its origin is generated from the verified local registry binding; AgentPie dev/beta stays on staging, while XiaShe CN stays on actions.xiashe.chat, and doctor stops only if the identity, endpoint, or creator card belongs to a different environment. The Red file retains the start response only in the current Agent’s private state and follows only the server-provided, allowlisted continuation. That private response selects @xiashe/[email protected] for capable shell hosts; the runtime package and shell commands are never written to the Red file. An HTTP 200 is never treated as delivery. The runtime helper checks access, performs the approved official confirmation path, and retrieves the complete local package. Wallet, payment-command, host-session, credential, and backend-stage implementation details are absent from the Red file. In Red's official flow, select only red-skill-upload/—not the original project or its SKILL.md. The private prompt, source bundle, public token, storage ID, download URL, and creator credentials stay out of Red.

After Red returns its public URL, record publication attribution locally with track --event hub_upload_succeeded --hub red --platform-skill-url <url>. This is not a runtime-use counter. Test with a new Agent: its first real use must show the creator card and directly ask the one-time “开始使用” question; installing or reading the file must not POST; explicit start consent must reach the Agent-only entry without exposing payment details or service credentials.

Local development

node packages/xiashe-skill-cli/bin/xiashe-skill.mjs --help
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs inspect .
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs doctor .
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs preflight --claim-url https://<registry-host>/registry/skill/claim --json
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs publish . --code XS-XXXX-XXXX --claim-url https://<registry-host>/registry/skill/claim --to xiashe,red
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs setup . --code XS-XXXX-XXXX --hub all
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs setup . --code XS-XXXX-XXXX --hub red
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs red-package . --protected-red --red-connector-description "<120–260 character public Skill description>"
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs verify . --hub red --dry-run --json
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs verify . --hub red
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs attach . --code XS-XXXX-XXXX
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs attach . --public-token pub_xxx --skill-id sk_xxx
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs prompt . --hub red --source-url https://example.com/my-skill-repo
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs snippet . --target js
node packages/xiashe-skill-cli/bin/xiashe-skill.mjs track . --event skill_invoked --hub red --dry-run --json

Use the claimUrl returned with a dashboard dynamic code exactly as issued. publish validates that destination before it consumes a code, so a code cannot accidentally be sent to a different service. For an existing Skill update, run the normal publish command from the original project folder. The CLI reads and validates its saved local connection before it writes or uploads anything. Do not copy internal endpoint options into a user-facing update task.

When an existing project was originally linked through XiaShe, @agentpie/skill publish can reuse that local connection only for an update without a dynamic code or public token. It validates the recorded connection first, then creates a separate AgentPie local connection while retaining the XiaShe original. If it cannot verify the link, it stops before changing files or uploading a package. This keeps distinct services isolated without asking users to understand internal deployment details.

Reliable publish and recovery

The publish path keeps three different values separate:

• Source fingerprint — a stable SHA-256 of reviewed Skill source files. It is the idempotency key for the publish job.
• Artifact checksum — SHA-256 of the generated .tgz bytes, sent with the upload request.
• Storage metadata checksum — an upload-store diagnostic; it is never trusted as the sole proof of the uploaded bytes.
• Verified upload checksum — the backend rehashes the exact stored archive bytes and compares that value with the artifact checksum. None of these are compared with the source fingerprint.

If the network breaks after the server receives a dynamic-code claim, rerun the exact same publish command before that code expires. The registry accepts only the same code and source fingerprint, returns the original local manifest credentials, and reuses the same package job. It never creates a second Skill or a second upload job. Do not generate a new dashboard code merely because a local HTTP response was interrupted.

If an upload has already started, rerun the same command. The CLI queries the existing package job first and either reports success, waits for processing, or resumes the failed upload with the same public token and source fingerprint.