SuperAPI AI Directory

soia-meta-publish-market

General & other

View repository

Updated 10-16 08:47

About this skill

soia-meta-publish-market

Publishalready officially releasedskills to external marketplaces. Unlike the plugin marketplace (soia marketplace), the external marketplace accepts only one skill at a time, and what the user gets isan isolated copy—so publishing is not copy-paste; it requires filtering and rewriting first.

Execution prerequisite: there must be explicit authorization from the client for that instance, and only already-released content may be published. Publishing is an outward-facing action, and once an external platform includes it there are review and display records, making withdrawal more costly than on the plugin marketplace. The client saying "change this skill" does not equal "publish it". Additionallyonly submit main the official release on: dev snapshots carry -SNAPSHOT, and publishing means sending an in-development state to unfamiliar users. --dry-run Pre-check and --list-eligible inventory require no authorization.

Client-readable description

What this skill can do

The client wants The skill will do The client can see
See which skills can be published Scan the whole repository and filter by hard dependencies Per-skill publishability and reasons
Publish a skill to SkillHub Package → overlay platform fields → --dry-run pre-check → hand off to client for submission Staging path, pre-check results, commands to be executed
Send to Xiaohongshu Red Skill Package and provide upload instructions Staging path and upload entry instructions
Update an already published skill Repackage while keeping the slug unchanged, and prompt to fill in a change description Version comparison and changelog suggestions
Check whether a skill is ready before publishing Package and run the R1-R6 readiness gates on the staged artifact Item-by-item pass/warning/hard-gap report; hard gaps reject packaging

How the client uses it

# 1. 看这个仓哪些技能可以上架
python3 scripts/stage_for_market.py --repo-dir <域仓路径> --list-eligible

# 2. 打包某一个(不会上传;按渠道过滤文件)
python3 scripts/stage_for_market.py --repo-dir <域仓路径> \
  --skill <技能名> --out <暂存目录> --channel skillhub|redskill \
  --display-name "<中文展示名>"

# 3. 发版前咨询:对工作树跑一遍就绪门禁,不留产物(见「上架就绪门禁」)
python3 scripts/stage_for_market.py --repo-dir <域仓路径> \
  --skill <技能名> --out <暂存目录> --allow-unreleased --check-only

The packaged content is exported directly from origin/main without reading the working copy—whichever branch the local checkout is on does not affect the result, so unpublished content will not be mistakenly packaged because someone switched branches (this is the norm when multiple AIs share a checkout)., without reading the working copy—whichever branch the local checkout is on does not affect the result, so unpublished content won't be mistakenly packaged just because someone switched branches (this is the norm when multiple AIs share a checkout). main no such skill exists, or the main version carries -SNAPSHOT, packaging is rejected in all cases.

--channel redskill when --display-name is required, and if omitted it refuses to run outright; for the reason see Display name and platform primary key。

After packaging,the client themselvesexecutes the submission command—see the two channels below.

Dependencies and installation

Dependency Type How to handle when missing
Python 3 Hard dependency Retry after installation
skillhub CLI SkillHub channel See the installation command below; if not installed, only packaging and pre-check instructions are provided
SkillHub real-name verification + API Token SkillHub channel Without verification, a Token cannot be created and publishing is impossible; prompt the client to complete it first
@xhs/skillhub-upload Red Skill channel (Path A) If not installed, switch to web upload (Path B), or prompt the customer to install first
Browser login session Red Skill channel (Path B) The customer operates it themselves on the Xiaohongshu Creator Service Platform

Two hard rules (these determine how this skill filters and rewrites)

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-meta@soia

Install only this one skill:

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-meta-publish-market -y

WorkBuddy 's unit of installation is role-based experts rather than plugins,npx skills add -a '*' does not cover it, requires separate installation, see docs/install/workbuddy.md。

1. Only list skills with zero hard dependencies

Users of the external marketplacewill not simultaneously install companion skills from our repo. Declared dependencies.hard skills are broken links over there—even if installed, they can't run. The script automatically filters based on this, and upon encountering a hard dependency directly refuses to package and explains the reason.optional dependencies are not blocking, but a line should be written in the introduction: "Works better with such-and-such skill".

2. Only official releases can go to the marketplace (hard gate)

What the marketplace gets is what end users directly use, and it must be released content. The scriptdirectly from origin/main export, rather than validating the working copy—the latter depends on which branch is checked out and is unreliable.

Situation Result
The skill exists on main and the version has no -SNAPSHOT Export and package
The skill does not exist on main Reject: "Not yet released, cannot be listed"
The main version carries -SNAPSHOT Reject: "Not an official release"

--allow-unreleased is for local rehearsal only,must not be used for real listing。

4. Listing-readiness gate (machine check after packaging)

The external marketplace uses AI to evaluate listed skills; the types of gaps called out in historical reviews must be caught by machine at the packaging stage—hard gaps directly refuse packaging, not letting them flow to the marketplace to be reviewed. For gate details, see below Listing-readiness gate。

Listing-readiness gate

The external marketplace (Tencent SkillHub, etc.) uses AI to evaluate listed skills. Historical reviews have called out several types of gaps— no capability boundaries, no trigger words, no real output samples, no test guarantees, dependency sources all overseas—these are caught by machine at the packaging stage, and hard gaps directly refuse packaging, not letting them flow to the marketplace to be reviewed.

stage_for_market.py After packaging, againststaged artifacts(not the repository) run five checks:

No. Check Level Criterion Fix guidance
R1 Capability boundaries Hard gap SKILL.md has no section titled "Not responsible for"/"Capability boundaries" Add a section "What it is not responsible for", using two or three lines to clarify what it does not do
R2 Trigger words Hard gap frontmatter description does not contain "Trigger"/"Triggers" In the description, state the trigger scenario, e.g. "Trigger: ..."
R3 Output example Hard gap There is no "Samples/Examples" subsection containing real data; all <占位符> tables do not count Provide a sample table of real input→output
R4 Test evidence Hard gap tests/ contains no dedicated self-contained test that references only this skill and the standard library; or there is one but it cannot run after being packaged Write a self-contained minimal test for the skill: reference only files within this skill package and the standard library; shared tests that reference other skill names do not go into the package
R5 Overseas source notice Warning The package contains only overseas URLs (no .cn/npmmirror and other domestic sources) Prefer replacing with a domestically accessible installation source or mirror
R6 Security pre-check Hard gap The package contains suspected credential-style strings (npm_/ghp_/xox and other prefixes + long random segments), lowercase identifiers starting with npm_ (security scans falsely flag them based on key prefixes; Yunding reported on 2026-08-08 that ai-cli-upgrade had a health score of 47), or pipe-to-shell command wording (curl … | sh) Remove real credentials and replace placeholders with obviously fake values; rename identifiers to avoid the prefixes; change installation suggestions to a "download→review→execute locally" wording

Gate behavior: print pass/warning/hard gap item by item; if there is aHard gap → delete the staging directory and refuse to package (exit code 1); if there are only warnings → produce as usual. R4 only accepts "dedicated" tests—self-contained tests that reference only files within this skill package and the standard library; they willbe copied into the packageas evidence and actually run in the package layout; cross-skill shared tests that reference other skill names do not go into the package (managed by repository-level CI), and are only noted as skipped in the report.

This gate does not predict evaluation scores; it only eliminates the types of gaps called out in historical review comments.

Consultation usage: --check-only

# 对工作树做就绪检查(不导出 main、不留暂存产物,只出报告)
python3 scripts/stage_for_market.py --repo-dir <域仓路径> \
  --skill <技能名> --out <暂存目录> --allow-unreleased --check-only

--check-only runs the entire packaging + gate process and then deletes the staging artifacts, leaving only the report—suitable for running a consultation first during the PR stage, without waiting for a release. Combined with --allow-unreleased it becomes "perform a consultation check on the working tree".

3. Use the in-repository skill name for the slug, and use Chinese for the display name

slug must be globally unique; our skill names already have the soia- prefix, so they naturally satisfy this, and correspond one-to-one with in-repository names for easy traceability;displayName additionally provides a Chinese readable name for ordinary users.

slug: soia-env-network-diagnose          # = 仓内技能名,勿改
displayName: 网络诊断助手                  # 中文,面向市场读者
summary: <一句话简介,缺省取 description>
license: MIT

Platform fieldsSuperimposeOn top of the original frontmatter, without replacing it—the in-repository name/version/ created_by and other fields are retained; in actual testing they coexist with platform fields without conflict.

Channel 1: Tencent SkillHub (CLI)

One-time preparation (completed by the customer)

  1. Log in with a mobile phone number at https://skillhub.cn → complete in the personal centerReal-name verification(a Token cannot be created without verification)
  2. Personal center → API keys → Create → copy the Token starting with skh_ (shown only once)
  3. Install the CLI and log in:
curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
skillhub login --key <你的Token> --host https://api.skillhub.cn

skillhub auth whoami should output three lines: userId / handle / role.

Submission

skillhub publish <暂存目录>/<技能名> --dry-run

Seeing ✓ Dry-run passed: <slug>@<version> indicates the format is compliant. After confirmation, the customer executes:

skillhub publish <暂存目录>/<技能名> --changelog "首次发布"

Returning ✓ Published: skillId=xxx status=pending_review will enter review. When updating, keep the slug unchanged and change version,--changelog write this change.

Note:publish is an external publishing action; this skill does not perform it on the client's behalf; the precheck --dry-run can be run on their behalf.

Common failures

Symptom Cause
403 请先完成实名认证 Authentication not completed
409 slug 已被占用 This slug already exists across the network; change the name
401 invalid api key Token expired; re-create it

Channel 2: Xiaohongshu Red Skill

Red Skill hastwo upload paths, both handled by Xiaohongshu's official tool for delivery; this skill is only responsible for upfront packaging.

Path A: official uploader skill (recommended, AI-driven)

Xiaohongshu has released @xhs/skillhub-upload — a CLI + companion skill, driven by an AI assistant to complete authorization, packaging, upload, and submission.Do not implement upload logic yourself: the interfaces and fields are maintained by the platform side; building your own will inevitably drift.

One-time setup (performed by the client):

npm install -g "https://fe-video-qc.xhscdn.com/fe-platform-file/104101b83221qt9bu7k0653u0hejenq0004pf88k9rpr6a.tgz"

Installingwill not automatically register the skill, you also need to copy the SKILL.md inside the package into the agent's skills directory:

mkdir -p <agent-skills-dir>/skillhub-upload
cp "$(npm root -g)/@xhs/skillhub-upload/skill/SKILL.md" \
   <agent-skills-dir>/skillhub-upload/SKILL.md

Then hand the staging directory produced by this skill to it:

Please follow the instructions in https://redskill.xiaohongshu.net/uploader.md to help me upload <暂存目录>/<技能名> to Xiaohongshu SkillHub

The process after the official skill takes over (for understanding only, not implemented by us):whoami check authorization → login --agent output authorization link and user code (open in mobile browser to jump to App) → pull the real-time tag list → ask for source (original/reposted) and tag → publish --dry-run --agent output the payload to be submitted for review → only actually submit after the user explicitly says "submit".

Key points:Skill ID is the platform primary key and cannot be renamed across versions, if the dry-run stage indicates it cannot be auto-derived, after careful confirmation use --identifier to specify.

Testing notes (obtained from running the full chain on 2026-08-05)

Red Skill has a file type allowlist; SkillHub does not. For the same skill directory, SkillHub --dry-run passes directly, while Red Skill reports 目录中包含不支持上传的文件:agents/openai.yaml,请移除后重试—it only accepts .md/.txt/.html/.css/.js/.py/.json/.xml, while our agents/openai.yaml(Codex interface metadata) is not among them. Therefore packaging must include --channel redskill for exclusion; after exclusion dry-run passes, and in the payload version is exactly the official version number of main.

CLI output is RESULT_JSON: structured lines. In testing, the skillhub-upload shim on PATH swallowed the output in some environments (command silent, exit code 0); only by directly invoking node "$(npm root -g)/@xhs/skillhub-upload/cli/index.mjs" <子命令> can you see it. When troubleshooting, confirm with this first; don't mistake silence for success.

--dry-run does not require authorization, only a real submission does; so the precheck can be run at any time.

The CLI only supports first-time publishing; version updates go through the web page. Tested on 2026-08-06: after skill 1.2.0 passed review and went live, submitting 1.3.1 via CLI for the same Skill ID was rejected SUBMIT_REJECTED: Skill ID 已被占用(in the first-time publishing response, first_version: true is also circumstantial evidence). For version updates of an already-listed skill, go to the Creator Platform Builder hub → that skill → Update version → Upload the folder/zip prepared by this skill; packaging is still done by this skill, while the upload is performed by the client themselves.

login will automatically renew with a refresh token,publish will not. after the access token expires publish it directly reports NEED_LOGIN; at this point, first run login --agent—when there is an unexpired refresh token, it silently renews and returns loggedIn: true, with no need to re-scan the QR code for authorization.

Tags are fetched in real time, do not hardcode them—actual testing currently shows Efficiency Tools / Content Creation / Learning & Growth / Workplace & Office / Programming & Development / Life Decisions / Finance & Wealth / Other, but whatever is fetched prevails.

Display name and platform primary key (required)

name must not fall on the skill name inside the repository. 2026-08-06 the first real submission was rejected: SUBMIT_REJECTED: 名称长度不符合要求—the payload's name was taken from the frontmatter's soia-env-network-diagnose(25 characters), exceeding the platform limit; after changing it to “Network Diagnostics Assistant,” it passed. The official uploader's value priority is flags.name || metadata.name || identifier (submit.mjs), so the correct approach is to pass it during delivery --name,without touching the frontmatter in the repository— changing the frontmatter will also affect identifier derivation and the skill identity in the repository.

The platform's length limit is not public; we only know that 25 was rejected and 6 passed. Therefore, do not guess the threshold; instead use one deterministic constraint:--channel redskill must be given --display-name, and if omitted it directly refuses to run. A long English skill name is meaningless to market readers anyway.

--identifier must be explicitly pinned. The Skill ID is the platform primary key and cannot be renamed across versions. When not explicitly specified, it is derived from the frontmatter's name and once renamed in the future will, on the platform,create another new skill, rather than updating the original one. So the delivery command fixedly includes --identifier <仓内技能名>。

--yes does not override the final confirmation gate. confirmBeforeSubmit is unconditional: it reads one line from stdin, which must be the literal submit, and empty input is treated as cancellation. This is the platform-designed manual gate and must be answered only after the client explicitly says to submit;edit followed by key=value lines can change during the confirmation stage name/identifier/version/ description/detail/tag。

Path B: Web upload

Creator service platform → Builder hub → Red Skill → Upload Skill → upload file. Two steps: ① upload the source code ② fill in the information.

Constraint Value
Accepted form containing SKILL.md 'sfolderor zip
file type .md/.txt/.html/.css/.js/.py/.json/.xml and other code and configuration
Single file limit 10 MB
Total size limit 30 MB
Required item Content source (original / reposted), check 《Skill Publishing Security Specifications》

Our skill directory (SKILL.md + scripts + references) naturally satisfies these constraints.

Coordination with the media domain

soia-media-publish-rednote-card notes produced can mount the corresponding Skill card—the content talks about the scenario, while the card directly converts, forming a closed loop within the same platform.

What it is not responsible for

  • does not execute on behalf of the client publish or click upload. These two actions send content to external platforms and enter the review record, and must be performed by the customer themselves. This skill only does packaging and pre-checks.
  • Do not publish unreleased content. Package only from the domain repository main(official release); dev snapshots carry -SNAPSHOT。
  • Do not modify skills in the repository. Packaging is done in a staging directory and does not write back to the source repository; to change dependencies or descriptions, follow the normal PR process, and publish only after release.
  • Do not build your own upload implementation. Red Skill delivery is handled by the official @xhs/skillhub-upload , and SkillHub by the official skillhub CLI; the platform interfaces and fields are maintained by them, and we only do pre-filtering and packaging, to avoid creating a copy that is bound to drift.
  • Do not manage the plugin marketplace。soia marketplace pin refresh belongs to soia-meta-skill-release。

Private information and intermediate data

  • Do not read, echo, or store API Tokens. Login is performed by the customer via skillhub login , and credentials are stored in the CLI's own configuration; this skill only calls skillhub auth whoami to confirm login status.
  • The staging directory is placed in the system temporary directory by default and does not enter the repository; packaging artifacts can be regenerated at any time.

Logs and completion receipts

Skill Channel slug Version Pre-check Status
<skill> SkillHub / Red Skill <slug> <version> passed / failed Pending customer submission / Submitted pending review

Forward testing

  • --list-eligible Can correctly distinguish between skills with zero hard dependencies and skills with hard dependencies
  • When packaging a skill with hard dependencies, report an error and explain the reason, and do not produce a staging directory
  • After packaging, the frontmatter contains both platform fields and original fields, with the body unchanged word for word
  • --display-name When absent, fall back to the original name,--summary When absent, fall back to description
  • --channel redskill When missing, exit code is non-zero, and no staging directory is produced --display-name When absent, exit code is non-zero, and no staging directory is produced
  • redskill's delivery command also includes --name and --identifier, and what is given is the --dry-run form
  • The readiness gates R1-R6 each haveone positive and one negativetest cases: missing boundary section/trigger words/real examples/exclusive tests; R6 covers the three negative cases of pipe-to-shell wording, npm_ prefix identifiers, and credential-style strings, and the two positive cases of uppercase environment variables/npm_ in the middle of a word not being falsely flagged are rejected, and allowed through after being completed; all-overseas URLs are recorded as warnings without blocking, while the presence of domestic sources such as npmmirror results in no warning
  • R4 copies only the "exclusive" tests (referencing only this skill and the standard library) into the package and actually runs them in the package layout; layout-coupled tests will be caught and the package rejected; cross-skill shared tests that reference other skill names are not included in the package and are only noted in the report
  • --check-only After running the entire process, leave no staging artifacts