CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目性质

SkillSpace 是一个文档工程，不是应用代码仓库。产出物是各类 Agent 框架的技能包（Markdown + Shell + JSON）。所有面向用户的文档使用中文。仓库没有 build/test/lint 命令 —— 质量保障通过仓库自身的生命周期技能完成（见"运行技能"）。

顶层架构

仓库分为三类目录，理解这三者的关系才能正确操作：

skills/ — 生命周期管理技能（9 个），是操作本仓库的工具集。用户唯一入口是 skill-lifecycle，它按意图路由到 8 个子技能：skill-discover / skill-router / skill-tester / skill-auditor / skill-debugger / skill-updater / skill-publisher / skill-retire。改动技能包时应通过这些技能驱动，而不是手工修改。
meta-skills/ — 技能的技能（5 个），描述"如何为某框架创建技能"。被 skill-router 在创建阶段调用。每个 meta-skill 目录固定包含 skill.json / prompt.md / spec.md / examples/ / CHANGELOG.md。
<framework>/ — 框架技能目录，共 5 个框架：qoder/、claude-code/、codex/、openclaw/、hermes-agent/。每个框架目录结构固定：
- skills/<name>/ — 技能源码
- versions/<name>/v<X.Y.Z>/ — 版本快照（修改前必须先归档）
- publish/registry.json — 已发布记录
- docs/ — 框架适配文档

此外：

archives/ — 外部技能压缩包及解压目录，不可变。严禁修改其中的技能文件，仅允许更新其 README.md 和 CHANGELOG.md。技能迭代必须在 <framework>/skills/<name>/ 中进行。命名约定：<name>-<version>（解压目录）、<name>-<version>.zip（压缩包）、<name>-<version>_server（服务端变体）。
SKILL-REGISTRY.md — 全仓库技能总清单，增删技能时必须同步。
AGENTS.md — 面向所有 AI 助手的规则文件，本 CLAUDE.md 是其超集。

框架文件格式差异（关键）

同一份"技能"在不同框架里格式不同，处理时必须区分：

框架	核心文件	备注
OpenClaw	`SKILL.md`	SKILL.md 含 YAML frontmatter，原生兼容 SkillHub。技能目录通常还包含 `QUICKSTART.sh`、`assets/`、`scripts/`、`references/`
Hermes Agent	`SKILL.md`	frontmatter 含 `metadata.hermes` 段；description ≤1024 字符且以 `"Use when ..."` 开头
Qoder / Codex / Claude Code	`skill.json` + `prompt.md`	发布到 SkillHub 前需合并生成临时 `SKILL.md`（放在 `<framework>/publish/.staging/`，临时目录，不提交 git）

发布流程（SkillHub）

远程 registry：https://skill.solahqb22.cn，CLI 是 @astron-team/skillhub。

命名空间按目录前缀自动映射：

目录前缀	SkillHub 命名空间
`openclaw/skills/`	`sola-openclaw-work`
`claude-code/skills/`	`sola-claude-code-work`
`codex/skills/`	`sola-codex-work`
`qoder/skills/`	`sola-qoder-work`
`hermes-agent/skills/`	SkillHub 暂不支持

发布步骤：

修改前将当前版本快照复制到 <framework>/versions/<name>/v<X.Y.Z>/。
必须先 --dry-run：skillhub publish <路径> --namespace <ns> --dry-run。
.conf 文件会被 SkillHub 拒收，需重命名为 .conf.txt。
发布后同步更新 <framework>/publish/registry.json、<framework>/skills/<name>/CHANGELOG.md 以及顶层 SKILL-REGISTRY.md。
完整流程见 skills/skill-publisher/prompt.md。

关键约束

版本号严格 SemVer：MAJOR.MINOR.PATCH。修复用 PATCH，向下兼容新功能用 MINOR，破坏性变更用 MAJOR。禁止 2.0 或 v1 之类的非标准写法。
Shell 脚本禁止将 Shell 变量拼进 Python 字符串。 必须通过 os.environ 传递：
- ❌ python3 -c "x = '$VAR'"
- ✅ VAR="$VAR" python3 -c "import os; x = os.environ['VAR']"
SKILL.md 措辞：SkillHub 的 YARA 扫描会对危险命令字面量报警，即便是文档示例。用中文描述替代危险命令字面量（例如"递归强制删除根目录"而非直接写 rm -rf /）。
description 长度：OpenClaw ≤160 字符；Hermes ≤1024 字符且以 "Use when ..." 开头。

运行技能

本仓库没有传统的 build/test 命令。若要执行技能相关操作，通过 Claude Code 的 Skill 工具调用 skill-lifecycle（或直接调用某个子技能），描述意图即可，例如：

"调研有没有现成的 Docker 调试技能" → skill-discover
"创建一个 OpenClaw 的 PDF 处理技能" → skill-router → 对应 meta-skill
"测试 openclaw/skills/cloud-deploy" → skill-tester
"发布 openclaw/skills/cloud-deploy 到 SkillHub" → skill-publisher

提交与远程

Commit message 使用英文、描述性风格。
远程仓库：https://git.solahqb22.cn/solahqb/SkillSpace.git（凭证已通过 credential.helper store 配置）。
Git post-commit hook：每次提交会自动调用 qodercli commit --hook 上报至 Qoder 追踪系统。不要移除或绕过此 hook。

关键文件索引

SKILL-REGISTRY.md — 技能总清单（增删任何技能都要同步）
AGENTS.md — 通用 AI 助手规则（本文件的精简版）
skills/skill-publisher/prompt.md — 完整发布流程含格式适配细节
meta-skills/create-<framework>-skill/spec.md — 各框架的技能规范摘要
archives/README.md — 外部技能导入流程

5.6 KiB Raw Permalink Blame History Unescape Escape