91 lines
5.6 KiB
Markdown
91 lines
5.6 KiB
Markdown
# 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 命令 —— 质量保障通过仓库自身的生命周期技能完成（见"运行技能"）。
|
||
|
||
## 顶层架构
|
||
|
||
仓库分为三类目录，理解这三者的关系才能正确操作：
|
||
|
||
1. **`skills/`** — **生命周期管理技能**（9 个），是操作本仓库的工具集。用户唯一入口是 `skill-lifecycle`，它按意图路由到 8 个子技能：`skill-discover / skill-router / skill-tester / skill-auditor / skill-debugger / skill-updater / skill-publisher / skill-retire`。改动技能包时应通过这些技能驱动，而不是手工修改。
|
||
|
||
2. **`meta-skills/`** — **技能的技能**（5 个），描述"如何为某框架创建技能"。被 `skill-router` 在创建阶段调用。每个 meta-skill 目录固定包含 `skill.json / prompt.md / spec.md / examples/ / CHANGELOG.md`。
|
||
|
||
3. **`<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 暂不支持 |
|
||
|
||
发布步骤：
|
||
|
||
1. 修改前将当前版本快照复制到 `<framework>/versions/<name>/v<X.Y.Z>/`。
|
||
2. 必须先 `--dry-run`：`skillhub publish <路径> --namespace <ns> --dry-run`。
|
||
3. `.conf` 文件会被 SkillHub 拒收，需重命名为 `.conf.txt`。
|
||
4. 发布后同步更新 `<framework>/publish/registry.json`、`<framework>/skills/<name>/CHANGELOG.md` 以及顶层 `SKILL-REGISTRY.md`。
|
||
5. 完整流程见 `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` — 外部技能导入流程
|