SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsskill-publisher

skill-publisher

Agents & models

View repository

Updated 10-15 16:45

About this skill

Skill Publisher

Publish an agent skill to GitHub in one click, automatically completing validation, README quality checks, completion, push, and real installation verification.

Prerequisites

  • gh CLI is installed and logged in (gh auth status）
  • The skill directory contains a valid SKILL.md(including YAML frontmatter name + description）
  • Prefer using /Users/joe/.agents/skills/<name> as the official source directory;.codex / .claude can serve as a compatibility entry point.

Publishing process

When the user asks to publish a skill, run the publishing script:

python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py <skill_dir>

Determine the skill directory

  • If the user says "publish this skill" and is currently in a skill directory → use the current directory
  • If the user specifies a skill name → prefer searching under ~/.agents/skills/ search under
  • If unsure → ask the user which skill to publish

Steps the script completes automatically

  1. Validate the YAML frontmatter of SKILL.md (name + description)
  2. Check gh CLI readiness status
  3. Create LICENSE (MIT, if missing)
  4. Generate or check README.md: when generating, no longer write a TODO template; when it already exists, block obvious placeholders
  5. Identify the repository name: prefer using the current origin repository name, to avoid publishing skill-publisher to the wrong repo by mistake
  6. Initialize git (if needed)
  7. Create or update GitHub public repository and push
  8. Validate npx skills add --list is discoverable, and perform a real installation in a temporary directory

Parameter options

Parameter Description
--private Create a private repository (public by default)
--dry-run Check only, do not actually publish
--skip-verify Skip npx skills validation
--github-user USER Specify the GitHub username (retrieved automatically by default)
--repo-name NAME Specify the GitHub repository name; by default prefer using the current origin repository name, otherwise use the skill name
--no-symlink Skip syncing ~/.agents/skills/ the physical directory

Automatically sync the ~/.agents/skills/ physical directory

After successful publishing, the script can automatically sync the skill to ~/.agents/skills/<name> as a physical directory.

This directory is the general Agent Skills standard directory, and the following tools will automatically read it: OpenCode, Codex CLI, Cursor, Gemini CLI, GitHub Copilot, Amp, Cline, Warp, etc.

Publish once, share across multiple tools, no repeated configuration needed.

If the current publishing source is already ~/.agents/skills/<name>, the script will skip syncing, to avoid mistakenly deleting your own source directory. If the skill name and repo name are inconsistent, or you do not want to create a local copy, add at publish time --no-symlink。

⚠️ SKILL.md YAML security rules (must check before publishing)

npx skills uses a strict YAML parser; the following writing style will cause installation failure (reporting "No valid skills found"):

❌ Incorrect writing ✅ Correct writing
description: 含有 "引号" 的文字 Switch to | block scalar (see below)
description: 含单引号'的文字 Use | block scalar
description: 含冒号: 的文字 Use | block scalar

Safest way to write description：

description: |
  描述放这里，可以随意包含 "双引号"、'单引号'、冒号: 等特殊字符
  触发词: 用户说...时触发

The script has built-in strict YAML validation (pyyaml), which will catch such errors before publishing and provide fix suggestions.

Update an already published skill

Run the same command again for a skill that already has a GitHub repository; the script will detect that the repository already exists and automatically commit + push the update.

Usage examples

用户：发布 yt-search-download 这个 skill
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py ~/.agents/skills/yt-search-download

用户：把当前 skill 发到 GitHub
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py .

用户：先检查一下能不能发布
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py <dir> --dry-run

用户：当前 skill name 与仓库名不同，明确发布到 qiaomu-skill-publisher
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py <dir> --repo-name qiaomu-skill-publisher

README quality check (mandatory before publishing)

The script only auto-generates a release page template when README does not exist. Before publishing, you must manually check/write the README to ensure it is valuable to unfamiliar users.

Latest standard: auto-generated README should not contain TODO、特性 1、[问题 1] placeholders like this; if an existing README contains obvious placeholder content, publishing will fail.

The 7 elements a README must contain

  1. Value proposition (Hook): the first paragraph should let users understand "what problem does this solve for me", using concrete scenarios rather than abstract descriptions.
  2. Above-the-fold evidence: product screenshots, output examples, real generated artifacts, or a short demo must appear near the first screen of the README; for web projects, prioritize placing a complete product screenshot.
  3. Dynamic trust signals: badges such as GitHub stars, forks, issues, last commit, license, and deploy/install buttons should be placed at the top; for projects suitable for public promotion, add Star History.
  4. Prerequisite checklist (checkbox format): use - [ ] to list all dependencies so users can confirm them one by one. Each item must clearly state how to install it; do not just say "requires xxx".
  5. Complete installation steps: numbered steps, detailed enough that a beginner can follow along. Each step should provide a verification command (such as --version）
  6. Natural language usage examples: show 2-3 sentences users would actually say, so people can immediately understand how to trigger it.
  7. Credit the original author: if the skill is based on a third-party tool/library, you must include the original project link and author.
  8. Necessary risk/limitation notes: risks related to write operations, accounts, and costs must be clearly disclosed.
  9. FAQ/Troubleshooting: list at least 3 common errors and solutions to reduce the user abandonment rate.

Web project README publishing standards

Refer to nexu-io/open-design and other high-conversion READMEs; web projects cannot just list installation commands, they must give users a judgeable first screen like a product launch page.

Recommended first-screen order：

  1. Project name + one-sentence Hook
  2. Main CTA:Deploy with Vercel / Live Demo / Install; buttons must be directly usable with the real repository URL.
  3. GitHub dynamic badges: stars, forks, issues, last commit, license, build status (if available)
  4. Product screenshot:docs/assets/product-screenshot.png, with alt text clearly describing the screenshot content.
  5. 3-6 core feature points; do not write generic "efficient/modern/elegant".

Web projects must prioritize completing：

  • docs/assets/product-screenshot.png: first-screen or core workflow screenshots.
  • docs/assets/ Sample output under: for example, an image generation website should include 3-6 representative generated images.
  • Sample tables in the README: show inputs, outputs, key differences, or use cases.
  • scripts/capture-screenshots.* Or an equivalent command: it can launch the website locally and then automatically refresh the README screenshots
  • Deployment instructions: entry points such as Vercel/Netlify/Docker must use the real repository URL and the fewest possible steps

Recommended README modules：

# Project Name

> 一句话说明用户会得到什么。

[Deploy with Vercel] [Live Demo] [Stars] [Forks] [Last commit] [License]

<img src="docs/assets/product-screenshot.png" alt="..." />

## 为什么值得用
## 样例输出
## 一键部署
## 本地开发
## 自动更新截图
## 数据/生成流程
## Star History
## Troubleshooting

Automatic screenshot requirements：

  • For projects with a frontend UI, prefer using Playwright/Puppeteer to generate README screenshots instead of taking screenshots manually
  • The screenshot script should allow the URL to be specified via an environment variable, for example SCREENSHOT_URL=http://127.0.0.1:3000 npm run capture:screenshots
  • Put screenshot files into docs/assets/, and reference them in the README using relative paths
  • The screenshot script is release asset generation, not equivalent to functional acceptance; unless the user requests it, do not package it as a complete E2E test

Language principles

By default, write the README in both Chinese and English, but put Chinese first. Chinese users are the primary audience, and English is a supplement for international users.

Bilingual structure (Chinese first)：

# skill-name

> 中文一行价值主张
> One-line English hook

**[中文](#中文) | [English](#english)**

---

<a name="中文"></a>
## 中文
[完整中文内容]

---

<a name="english"></a>
## English
[完整英文内容]

How to write an appealing README (most important)

The goal is not "to make people understand," but "to make people want to install it." Every paragraph must answer the question in the user's mind: What does this have to do with me?

Structure of a highly appealing README：

  1. Grab the pain point in the first sentence: describe the user's current pain, not your solution. One sentence, precise, no fluff.

    • ✅ "You ask AI a difficult question, and it gives you one answer, one angle."
    • ❌ "This is a multi-perspective reasoning tool, based on arXiv:2605.02396..."

  2. One-sentence reversal: immediately give the contrast of "after using this."

    • ✅ "HeavySkill lets K independent AIs think about the same question in parallel, then has Codex host the discussion and synthesize a conclusion more solid than any single answer."

  3. Specific output preview: tell users what they will get. Do not say "generate a report"; say "generate a Medium-magazine-style HTML report, with the reasoning process for each perspective, blind spots found during discussion, and a bolded final judgment."

  4. Above-the-fold screenshot or sample: let users see the real result first, then decide whether to keep reading. For web projects, include a product screenshot; for generation-based projects, include representative output; for CLI/Skill projects, include actual terminal output or a generated document snippet.

  5. One-line installation: minimum friction. Do not say "first clone, then cd, then npm install."

    npx skills add username/skill-name

  6. Natural language trigger examples: let users know how to use it. Not commands, but what they would actually say.

    • "Discuss React vs Vue"
    • "think harder: microservices or monolith architecture"

  7. Prerequisites checklist (checkbox format): place it after installation, not at the beginning where it may scare people off. Use - [ ] format to let users confirm items one by one.

  8. Dynamic project status: place stars/forks/issues/last commit/license badges at the top of public GitHub projects; add Star History when there is a growth narrative.

  9. Troubleshooting table: at least 3 items, to solve the last mile that makes users give up.

Writing guidelines that make people want to install it：

  • Short sentences. One idea per line, do not pile them into the same paragraph.
  • Specific beats abstract. "36k+ GitHub Stars, 9 million/month npm downloads" is more persuasive than "a popular open source project."
  • Make users imagine the "after using it" scenario, rather than describing the technical implementation.
  • Put risks or limitations last, don't start with "Note: this requires...".

README beginner-friendliness check

Check item by item before publishing:

  • The first sentence is the pain point, not a feature description
  • Has a concrete "after using it" scenario description
  • Installation command done in one line, placed in a prominent position
  • Web projects have a first-screen product screenshot, generation-type projects have representative output samples
  • GitHub projects have dynamic badges at the top, public projects have a Star History or repo activity entry point
  • Web projects have an automatic screenshot command, screenshots are in docs/assets/
  • Prerequisites use checkbox format, each entry explains how to install
  • Usage examples are what real users would say, not technical commands
  • Has a Troubleshooting table (problem → solution)

Common README bad smells (avoid)

  • ❌ Directly putting SKILL.md's AI instructions (Output Formatting Rules, Rule:...) into the README
  • ❌ The first paragraph is all technical description, with no value the user can feel
  • ❌ Starting with "Based on arXiv:XXXX..." — users don't care about the paper, they care about the results
  • ❌ Prerequisites placed at the beginning, scaring users away
  • ❌ Installation steps exceed 3 steps (if they do, it means you haven't thought clearly about how to simplify)
  • ❌ No Troubleshooting, users can only figure it out themselves when they hit problems
  • ❌ Web projects have no screenshots, or screenshots are outdated and cannot be reproduced
  • ❌ The Deploy button still points to your-org/your-repo placeholder URLs like this

Publishing workflow

1. 读取 SKILL.md，理解 skill 的功能和目标用户
2. 判断语言：默认中文，只在明确国际化需求时写双语
3. 检查 README.md 是否存在，若存在则评估吸引力（不只是完整度）
4. 若 README 不够吸引人，先重写再发布
5. README 确认后，再运行发布脚本
6. 如果当前仓库已有 `origin`，确认脚本使用的是 `origin` 仓库名；否则用 `--repo-name` 明确指定
7. 发布后必须验证 `npx skills add <user>/<repo> --list`，并尽量做临时目录真实安装

After publishing is complete

Show the user:

  • GitHub repository URL
  • Installation command:npx skills add <user>/<skill-name>
  • Verification result