# 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>/` 中进行。
- **`SKILL-REGISTRY.md`** — 全仓库技能总清单，增删技能时必须同步。
- **`AGENTS.md`** — 面向所有 AI 助手的规则文件，本 CLAUDE.md 是其超集。

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

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

| 框架 | 核心文件 | 备注 |
|------|---------|------|
| OpenClaw | `SKILL.md` + `_meta.json` | SKILL.md 含 YAML frontmatter，原生兼容 SkillHub |
| 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/`） |

## 发布流程（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` 配置）。

## 关键文件索引

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