Kinema's Skill Making Pipeline

KinemaClaw cross-platform Skill development and publishing specification. Defines the standard process for Codex and Claude plugin development, version management, marketplace indexing, and publishing. All skills built in KinemaClaw must follow this specification. Trigger: Creating new skills, publishing skills, modifying existing skills.

Kinema.@leeshunee

Install

openclaw skills install @leeshunee/kinema-skill-making-pipeline

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 | 核心原则

Git First - All modifications must be managed in Git repository | 所有修改必须在 Git 仓库中管理
Atomic Commits - Each commit must be a meaningful independent change | 每次 commit 必须是有意义的独立变更
Versioned Releases - Must create Git tag before publishing | 发布前必须打 Git tag
No In-Place Publishing - Publish from a clean repository or filtered temporary package, never from a runtime install/cache directory | 从干净仓库或过滤后的临时包发布，禁止从运行时安装/缓存目录原位发布
Onboarding Required - Every skill must have installation/configuration guide | 每个 skill 必须有安装/配置引导
Cross-Platform Sync - After release, sync every installed target: source repo, GitHub Release, ClawHub, Claude Code, and Codex | 发版后同步源码、GitHub Release、ClawHub、Claude Code 与 Codex
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 仓库

text

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

bash

# 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）：

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

版本校验工具: 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 修复

text

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 正文开头（标题之后）必须声明作者信息：

markdown

# 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 之前）必须包含以下引导块：

markdown

## ⚠️ 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 执行的引导文档，必须按以下结构编写：

markdown

# <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 不应直接执行此文件，而是读取其内容，根据当前环境适配执行
内容是安装流程的模板代码，展示检测→安装→验证的逻辑模式

bash

# 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 使用以 ./ 开头的相对路径：

json

{
  "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 | 目录结构

text

<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 | 自动化脚本示例

bash

#!/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

References | 参考资料

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

Kinema's Skill Making Pipeline

Install

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

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

Core Principles | 核心原则

Development Workflow | 开发流程

1. Create Skill Repository | 创建 Skill 仓库

2. Development Guidelines | 开发规范

3. Release Process | 发布流程

4. Version Numbering | 版本号规则

Required Elements | 必须要素

1. SKILL.md

2. Onboarding | Onboarding

2.1 SKILL.md 中的 Onboarding 引导

2.2 references/ONBOARDING.md 结构规范

2.3 setup.reference.sh（可选）

2.4 Onboarding 触发场景

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

3.1 共享约束

3.2 Claude Code manifest

3.3 Codex manifest

3.4 版本同步规则

4. Prohibited Content | 禁止内容

GitHub Repository Guidelines | GitHub 仓库规范

Directory Structure | 目录结构

Automation Script Example | 自动化脚本示例

Related Documentation | 相关文档

References | 参考资料

Related skills