Kinema's Skill Making Pipeline | Kinema Skill 开发与发布规范

• Author: LeeShunEE
• Organization: KinemaClawWorkspace
• GitHub: https://github.com/KinemaClawWorkspace/kinema-skill-making-pipeline

本规范定义了 KinemaClaw ecosystem 中 skill 的开发、版本管理和跨 Codex、Claude Code、GitHub、ClawHub 发布的标准化流程。

⚠️ Before First Use | 首次使用必读

首次使用此 skill 前，必须先读取 references/ONBOARDING.md 完成环境配置。

• 首次配置 → 读取 references/ONBOARDING.md 完成全部步骤
• 环境不可用（命令不存在、依赖缺失、连接失败）→ 读取 references/ONBOARDING.md Troubleshooting 排查修复
• 配置完成后 → 直接使用下方开发流程

Core Principles | 核心原则

1. Git First - All modifications must be managed in Git repository | 所有修改必须在 Git 仓库中管理
2. Atomic Commits - Each commit must be a meaningful independent change | 每次 commit 必须是有意义的独立变更
3. Versioned Releases - Must create Git tag before publishing | 发布前必须打 Git tag
4. No In-Place Publishing - Publish from a clean repository or filtered temporary package, never from a runtime install/cache directory | 从干净仓库或过滤后的临时包发布，禁止从运行时安装/缓存目录原位发布
5. Onboarding Required - Every skill must have installation/configuration guide | 每个 skill 必须有安装/配置引导
6. Cross-Platform Sync - After release, sync every installed target: source repo, GitHub Release, ClawHub, Claude Code, and Codex | 发版后同步源码、GitHub Release、ClawHub、Claude Code 与 Codex
7. Marketplace on First Publish - Register a brand-new skill in every supported marketplace index; version updates must NOT add duplicate entries | 全新 skill 首发时必须登记所有支持平台的 marketplace 索引；版本更新不得重复登记

Development Workflow | 开发流程

1. Create Skill Repository | 创建 Skill 仓库

projects/<skill-name>/
├── .claude-plugin/plugin.json       # Required: Claude Code manifest
├── .codex-plugin/plugin.json        # Required: Codex manifest
├── skills/<skill-name>/SKILL.md     # Required: Codex discovery entry
├── SKILL.md              # Required: skill definition
├── scripts/              # Optional: automation scripts
├── references/           # Required: references and onboarding
│   └── ONBOARDING.md     # Required: onboarding guide
└── other project files

2. Development Guidelines | 开发规范

• Atomic commits: One thing per commit | 每个 commit 只做一件事
• Commit frequently: Commit after completing each feature/fix | 完成一个功能/修复一个问题后立即 commit
• Descriptive messages: Use meaningful commit messages | 使用描述性的 commit message

# Good | 好
git commit -m "Add install command to searxng-search CLI"

# Bad | 不好
git commit -m "update" 
git commit -m "fix stuff"

3. Release Process | 发布流程

发版流程已外置到 references/release-process.md。Agent 发版时必须读取该文档并按 Step 1→9 顺序执行。

发布前先判断类型 | Determine release type first:

类型	额外动作
全新 skill 首发（marketplace 索引中尚无该 skill）	走常规流程 + 更新 marketplace 索引 → 读取 references/marketplace-publishing.md
已有 skill 版本更新	仅走常规流程，不动 marketplace 索引

判断方法：分别在 marketplace 的 .claude-plugin/marketplace.json 与 .agents/plugins/marketplace.json 中检索本 skill 的 name。任一支持平台缺失都需要补登记；均存在则是版本更新。

发版流程概要（详细步骤见 reference）：

1. 确认变更已提交
2. 同步更新 SKILL.md + Claude/Codex 两份 plugin.json 版本号
3. 提交并打 Git tag
4. Push 到 GitHub
5. 创建 GitHub Release（Release Notes 强制含「更新内容」+「更新指令」两个 section；更新内容每行一条新功能/bug 修复并附 @commit-id）
6. 发布到 ClawHub（临时文件夹模式，排除两种 plugin manifest 与 Codex wrapper）
7. 更新 ClawHub 本地缓存（仅 ~/.openclaw 存在时）
8. 更新已安装的 Claude Code 与 Codex 插件：Claude 完成后提醒重载；Codex 完成后提醒新开对话
9. 全量版本校验

版本校验工具: bash scripts/version-check.sh [expected-version] — 校验 SKILL.md、Claude/Codex manifests 与 git tag 四处版本号一致。

4. Version Numbering | 版本号规则

Follow Semantic Versioning: | 遵循语义化版本 (Semantic Versioning):

• MAJOR: Incompatible API changes | 不兼容的 API 变更
• MINOR: Backward-compatible new features | 向后兼容的新功能
• PATCH: Backward-compatible bug fixes | 向后兼容的 bug 修复

v1.0.0 → First release | 首次发布
v1.1.0 → New features | 新功能
v1.1.1 → Bug fixes | bug 修复
v2.0.0 → Breaking changes | 重大变更

Required Elements | 必须要素

Each skill must include: | 每个 skill 必须包含：

1. SKILL.md

Must include: | 包含：

• name: skill name | skill 名称
• displayName: human-readable name with feature description | 人类可读名称（含功能描述）
• version: semantic version number | 语义化版本号
• description: functionality description and trigger condition | 功能描述和触发条件
• Complete usage instructions | 完整使用说明

作者声明规范:

SKILL.md 正文开头（标题之后）必须声明作者信息：

# Skill Name

- **Author**: [AuthorName](https://github.com/authorname)
- **Organization**: [OrgName](https://github.com/orgname)
- **GitHub**: https://github.com/orgname/skill-name

字段	说明
Author	作者 GitHub 个人主页链接
Organization	所属组织 GitHub 主页链接
GitHub	Skill 源码仓库链接

displayName 格式规范:

• 统一格式: `Name (Feature Description)`

2. Onboarding | Onboarding

references/ONBOARDING.md 是必选文件。 SKILL.md 不包含安装/配置细节，仅引用 references/ONBOARDING.md。

2.1 SKILL.md 中的 Onboarding 引导

SKILL.md 文件开头（# 标题之后、Environment Variables 之前）必须包含以下引导块：

## ⚠️ Before First Use | 首次使用必读

**首次使用此 skill 前，必须先读取 [references/ONBOARDING.md](references/ONBOARDING.md) 完成环境配置。**

- **首次配置** → 读取 references/ONBOARDING.md 完成全部步骤
- **环境不可用**（命令不存在、依赖缺失、连接失败）→ 读取 references/ONBOARDING.md Troubleshooting 排查修复
- **配置完成后** → 直接使用下方 Run Commands

Agent 读取 SKILL.md 时会看到此块，根据场景决定是否继续读取 references/ONBOARDING.md。

2.2 references/ONBOARDING.md 结构规范

references/ONBOARDING.md 是给 AI Agent 执行的引导文档，必须按以下结构编写：

# <Skill Name> Onboarding

> 本文档指导 AI Agent 完成首次环境配置。按顺序执行，遇到问题时参考 Troubleshooting。

## Prerequisites | 前置条件
（列出运行此 skill 所需的系统和软件条件）

## Step 1: <步骤名称>
### 检测
（检测命令 + 期望输出，agent 据此判断是否需要执行本步骤）
### 安装
（多种降级方案，按优先级排列，agent 逐条尝试）
### 验证
（验证命令 + 期望输出，确认本步骤完成）

## Step 2: <步骤名称>
...

## Step N: <验证连接或最终检查>

## Troubleshooting | 故障排除
（按错误信息分类的排查表，每行包含：错误 → 原因 → 解决方案）

编写规则：

规则	说明
按顺序执行	Steps 之间有依赖关系，不可跳步
每步可独立验证	每个 Step 必须有验证命令 + 期望输出
降级策略	每步提供多种方案（至少 2 种），适配不同环境
不硬编码路径	用 <skill_dir> 等占位符，agent 运行时替换
需要用户输入时明确标注	如"必须询问用户" "用户提供"，不猜测
Troubleshooting 覆盖常见错误	列出所有已知失败场景和解决方案

2.3 setup.reference.sh（可选）

对于安装配置较复杂的 skill，可提供 scripts/setup.reference.sh 作为参考范式。

注意：

• 文件名必须包含 reference，明确标识为参考文件而非可执行脚本
• Agent 不应直接执行此文件，而是读取其内容，根据当前环境适配执行
• 内容是安装流程的模板代码，展示检测→安装→验证的逻辑模式

# scripts/setup.reference.sh - SETUP REFERENCE (DO NOT EXECUTE DIRECTLY)
# Agent should read this file and adapt commands to current environment.

# Step 1: Check Python
python3 --version

# Step 2: Install dependencies (try in order)
uv pip install --system requests 2>/dev/null || \
pip3 install requests 2>/dev/null || \
sudo pip3 install --break-system-packages requests

# Step 3: Create symlink
sudo ln -sf <skill_dir>/scripts/tool.py /usr/local/bin/tool

# Step 4: Verify
tool --help

2.4 Onboarding 触发场景

场景	Agent 行为
首次使用	读取 references/ONBOARDING.md，按 Step 1-N 顺序执行
环境不可用	读取 references/ONBOARDING.md Troubleshooting，按错误信息匹配解决方案
依赖缺失	跳转到对应 Step 重新执行安装
版本升级后	重新执行 references/ONBOARDING.md 全流程（新版本可能引入新依赖）

3. Cross-Platform Plugin Manifests | 跨平台插件清单

同时支持 Claude Code 与 Codex 的 skill 必须把以下文件作为源码提交，均不得加入 .gitignore：

文件	用途
.claude-plugin/plugin.json	Claude Code plugin metadata
.codex-plugin/plugin.json	Codex plugin metadata 与 UI 信息
skills/<skill-name>/SKILL.md	Codex skill 发现入口

3.1 共享约束

• 两份 manifest 的 name 必须与根 SKILL.md 一致。
• 根 SKILL.md 与两份 manifest 的版本必须一致。
• Codex wrapper 目录名必须与 skill 名称一致。
• Codex wrapper frontmatter 只使用 name 和 description，正文通过相对路径引用根规范与 references，避免复制方法论。
• 只有实际存在对应文件时，Codex manifest 才声明 apps 或 mcpServers。

3.2 Claude Code manifest

.claude-plugin/plugin.json 继续使用 Claude Code 支持的 displayName、version、description、author、homepage、repository、license 与 keywords 字段。

3.3 Codex manifest

.codex-plugin/plugin.json 至少包含 name、严格 SemVer version、description、author.name 和完整 interface。skills 使用以 ./ 开头的相对路径：

{
  "name": "my-skill-name",
  "version": "1.0.0",
  "description": "Short description of the skill functionality.",
  "author": {
    "name": "AuthorName",
    "url": "https://github.com/authorname"
  },
  "repository": "https://github.com/OrgName/my-skill-name",
  "license": "GPL-3.0",
  "skills": "./skills/",
  "interface": {
    "displayName": "My Skill Name",
    "shortDescription": "Create and publish a cross-platform skill.",
    "longDescription": "Longer user-facing plugin description.",
    "developerName": "OrgName",
    "category": "Developer Tools",
    "capabilities": ["Interactive", "Write"],
    "websiteURL": "https://github.com/OrgName/my-skill-name",
    "defaultPrompt": ["Use this skill to review my plugin."],
    "brandColor": "#6366F1"
  }
}

Codex plugin 完成后运行官方 validator；Codex wrapper 完成后运行 skill quick validator。验证命令根据本机 skill 工具实际位置执行，不在仓库规范中硬编码用户目录。

3.4 版本同步规则

• 发版时同时更新根 SKILL.md、.claude-plugin/plugin.json 和 .codex-plugin/plugin.json。
• scripts/version-check.sh 必须检查三份版本声明及最新 git tag。
• Claude Code 参考：Plugins Reference。Codex 以当前安装的 plugin-creator 与 skill-creator 校验规则为准。

4. Prohibited Content | 禁止内容

Skills must NOT contain: | skill 中禁止包含：

• Personal websites, domains | 个人网站、域名
• Passwords, accounts, tokens | 密码、账号、Token
• Personal email, phone | 个人邮箱、电话
• Real names, identity information | 真实姓名、身份信息
• Cache files, build artifacts | 缓存文件、构建产物（.clawhub/、node_modules/、skills/ 等应通过 .gitignore 排除）

注意：.claude-plugin/、.codex-plugin/ 和受 manifest 引用的 skills/<skill-name>/ 都是项目源码，必须被 Git 跟踪。

GitHub Repository Guidelines | GitHub 仓库规范

• Default to Private repositories | 默认创建 Private 仓库
• Use meaningful repository names | 使用有意义的仓库名称
• Keep README.md in sync with SKILL.md | 保持 README.md 与 SKILL.md 一致
• No cache files in repo | 仓库中禁止缓存文件，.gitignore 必须排除 .clawhub/、skills/ 等 CLI 产物

Directory Structure | 目录结构

<skill-name>/                     # Git repository | Git 仓库
├── .claude-plugin/plugin.json    # Required: Claude Code manifest
├── .codex-plugin/plugin.json     # Required: Codex manifest
├── .gitignore                    # Required: must exclude CLI cache files | 必需：排除 CLI 缓存
├── SKILL.md                      # Required: skill definition | 必需
├── skills/<skill-name>/SKILL.md  # Required: Codex discovery wrapper
├── README.md                     # Recommended: project readme | 推荐
├── LICENSE                       # Recommended: license | 推荐
├── scripts/                      # Optional: scripts | 可选
│   ├── version-check.sh          # Optional: version consistency checker | 可选：版本一致性校验
│   └── setup.reference.sh        # Optional: setup reference | 可选（见 Onboarding 章节）
└── references/                   # Required: references and onboarding | 必需（低频/详细内容外置）
    ├── ONBOARDING.md             # Required: onboarding guide | 必需（见 Onboarding 章节）
    └── release-process.md        # Recommended: release process guide | 推荐：发版流程文档

Automation Script Example | 自动化脚本示例

#!/bin/bash
# skill-publish.sh - Publish skill to GitHub + ClawHub
# 完整发版流程见 references/release-process.md

SKILL_NAME=$1
VERSION=$2
CHANGELOG=${3:-"Release v$VERSION"}

if [ -z "$SKILL_NAME" ] || [ -z "$VERSION" ]; then
    echo "Usage: $0 <skill-name> <version> [changelog]"
    exit 1
fi

cd projects/$SKILL_NAME

# Version consistency check | 版本一致性校验
bash scripts/version-check.sh "$VERSION"
if [ $? -ne 0 ]; then
    echo "Error: Version mismatch. Fix before releasing."
    exit 1
fi

# Check for uncommitted changes | 检查是否有未提交的修改
if ! git diff --quiet; then
    echo "Error: Commit all changes first | 先提交所有修改"
    exit 1
fi

# Create tag | 打 tag
git tag -a v$VERSION -m "Release v$VERSION"

# Push | 推送
git push origin <default-branch>
git push origin v$VERSION

# Publish to ClawHub (temp folder mode) | 发布到 ClawHub（临时文件夹模式）
# Plugin metadata causes ClawHub to misidentify the package | 插件元数据会导致 ClawHub 误判
TMPDIR=$(mktemp -d /tmp/clawhub-publish-XXXXXX)
rsync -a --exclude='.git' --exclude='.claude-plugin' --exclude='.codex-plugin' --exclude='.claude' --exclude='.clawhub' --exclude='skills' . "$TMPDIR/"
clawhub publish "$TMPDIR" --slug $SKILL_NAME --version $VERSION --changelog "$CHANGELOG"
EXIT_CODE=$?
rm -rf "$TMPDIR"
exit $EXIT_CODE

Related Documentation | 相关文档

• ClawHub Documentation | ClawHub 文档
• Codex skill-creator and plugin-creator built-in skills | Codex 内置创建与校验规范

References | 参考资料

• references/release-process.md — 完整发版流程（Step-by-Step，含平台检测、版本校验、缓存问题解决）
• references/marketplace-publishing.md — 全新 skill 首发时更新 marketplace 索引的完整步骤
• references/clawhub-api-fallback.md — clawhub publish 返回 502 时的 API 备用发布脚本