Add AGENTS.md and SKILL-REGISTRY.md

- AGENTS.md: AI agent guidance in Chinese, covering immutable archives rule, SemVer versioning, framework namespace mapping, publish workflow, shell script security pattern, and YARA avoidance - SKILL-REGISTRY.md: master inventory of all 18 skills across lifecycle, frameworks, meta-skills, and archives
2026-07-02 01:48:17 +08:00 · 2026-07-02 01:48:17 +08:00 · 1bcf196779
commit 1bcf196779
parent f806d9a698
2 changed files with 173 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,58 @@
+# AGENTS.md
+
+本文件为 AI 助手在此仓库中工作时提供指导。
+
+## 项目性质
+
+这是一个**文档工程**，核心产出是 Markdown 文件和 Shell 脚本（智能体技能包），不包含应用代码。所有文档使用**中文**编写。
+
+## 关键规则
+
+- **`archives/` 不可变。** 严禁修改其中的技能文件，仅允许更新 `README.md` 和 `CHANGELOG.md`。所有技能迭代必须在 `<框架>/skills/<名称>/` 中进行。
+- **版本号必须遵循 SemVer**（`MAJOR.MINOR.PATCH`），不允许 `2.0` 或 `v1` 等非标准格式。修复用 PATCH，新功能用 MINOR，破坏性变更用 MAJOR。
+- **Shell 脚本中禁止将 Shell 变量拼入 Python 字符串。** 必须用 `os.environ` 传递。错误写法：`python3 -c "... = '$VAR'"`。正确写法：`VAR="$VAR" python3 -c "... = os.environ['VAR']"`。
+
+## 框架 → 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 暂不支持 |
+
+## 各框架文件格式差异
+
+| 框架 | 核心文件 | 说明 |
+|------|---------|------|
+| OpenClaw | `SKILL.md` + `_meta.json` | SKILL.md 含 YAML frontmatter |
+| Hermes Agent | `SKILL.md` | YAML frontmatter 含 `metadata.hermes` 段 |
+| Qoder / Codex / Claude Code | `skill.json` + `prompt.md` | 发布到 SkillHub 需合并为 SKILL.md |
+
+发布 Qoder/Codex/Claude Code 技能时，需在 `<框架>/publish/.staging/` 生成临时 SKILL.md（合并 skill.json 元数据 + prompt.md 正文）。
+
+## 发布流程要点
+
+1. 必须先 `--dry-run`：`skillhub publish <路径> --namespace <ns> --dry-run`
+2. SkillHub 拒绝 `.conf` 文件，需重命名为 `.conf.txt`
+3. 发布后更新 `<框架>/publish/registry.json` 和 CHANGELOG
+4. 修改前必须将当前版本归档到 `<框架>/versions/<名称>/v<版本>/`
+
+## SKILL.md 内容注意事项
+
+- SkillHub 的 YARA 扫描器会对文档中出现的危险命令字面量报警（即使是安全说明中的示例）。需改写措辞，如用"递归强制删除根目录"替代 `rm -rf /`。
+- `description` 字段：OpenClaw 建议 ≤160 字符；Hermes 要求 ≤1024 字符且以 "Use when ..." 开头。
+
+## 提交规范
+
+- 使用英文 commit message，描述性风格
+- 远程仓库：`https://git.solahqb22.cn/solahqb/SkillSpace.git`（凭证已通过 `credential.helper store` 配置）
+
+## 关键文件索引
+
+- `SKILL-REGISTRY.md` — 技能总清单（增删技能时同步更新）
+- `skills/skill-publisher/prompt.md` — 完整发布流程（含格式适配）
+- `meta-skills/create-<框架>-skill/spec.md` — 各框架技能规范
--- a/SKILL-REGISTRY.md
+++ b/SKILL-REGISTRY.md
@ -0,0 +1,115 @@
+# SkillSpace 技能清单
+
+> 最后更新：2026-07-02
+> 
+> 本文档汇总 SkillSpace 中所有技能的完整清单，涵盖生命周期管理技能、框架技能、meta-skills 和外部归档。
+
+---
+
+## 1. 生命周期管理技能
+
+用户通过 **`skill-lifecycle`**（唯一入口）调用，系统自动识别意图并路由到对应子技能。
+
+| # | 技能名称 | 阶段 | 版本 | 职责 | 路径 |
+|---|---------|------|------|------|------|
+| 1 | skill-lifecycle | 总入口 | 0.1.0 | 意图识别 + 路由分发到 8 个子技能 | `skills/skill-lifecycle/` |
+| 2 | skill-discover | 调研 | 0.2.0 | 多平台搜索、可行性分析、调研报告 | `skills/skill-discover/` |
+| 3 | skill-router | 创建 | 0.1.0 | 6 步交互式向导、5 框架路由、文件模板生成 | `skills/skill-router/` |
+| 4 | skill-tester | 测试 | 0.1.0 | 静态检查 + 动态测试引导 + 测试报告 | `skills/skill-tester/` |
+| 5 | skill-auditor | 审计 | 0.1.0 | Prompt 注入扫描、权限审查、合规检查 | `skills/skill-auditor/` |
+| 6 | skill-debugger | 排查 | 0.1.0 | 6 类问题分类、根因定位、修复方案 | `skills/skill-debugger/` |
+| 7 | skill-updater | 更新 | 0.1.0 | SemVer 升级、CHANGELOG 生成、回归提醒 | `skills/skill-updater/` |
+| 8 | skill-publisher | 发布 | 0.2.0 | SkillHub/ClawHub 发布、格式适配、命名空间映射 | `skills/skill-publisher/` |
+| 9 | skill-retire | 归档 | 0.2.0 | 废弃标记、服务端删除、版本归档 | `skills/skill-retire/` |
+
+**阶段流转**：
+
+```
+discover → create → test → audit → publish
+   ↑                   ↑            │
+   └── retire ←────────┴── update ←─┘
+                  debug
+```
+
+---
+
+## 2. 框架技能
+
+各框架目录下实际开发的技能，纳入生命周期管理。
+
+### OpenClaw（命名空间：`sola-openclaw-work`）
+
+| # | 技能名称 | 版本 | 状态 | SkillHub | 路径 |
+|---|---------|------|------|----------|------|
+| 1 | cloud-deploy | 2.0.1 | ✅ 已发布 | `sola-openclaw-work/cloud-deploy` | `openclaw/skills/cloud-deploy/` |
+
+### Claude Code（命名空间：`sola-claude-code-work`）
+
+| # | 技能名称 | 版本 | 状态 | 路径 |
+|---|---------|------|------|------|
+| — | *暂无技能* | — | — | `claude-code/skills/` |
+
+### Codex（命名空间：`sola-codex-work`）
+
+| # | 技能名称 | 版本 | 状态 | 路径 |
+|---|---------|------|------|------|
+| — | *暂无技能* | — | — | `codex/skills/` |
+
+### Qoder（命名空间：`sola-qoder-work`）
+
+| # | 技能名称 | 版本 | 状态 | 路径 |
+|---|---------|------|------|------|
+| — | *暂无技能* | — | — | `qoder/skills/` |
+
+### Hermes Agent（SkillHub 暂不支持）
+
+| # | 技能名称 | 版本 | 状态 | 路径 |
+|---|---------|------|------|------|
+| 1 | dev-pipeline-universal | 1.0.0 | 📦 本地管理 | `hermes-agent/skills/dev-pipeline-universal/` |
+
+---
+
+## 3. Meta-Skills（技能的技能）
+
+各框架的技能创建指南，被 `skill-router` 在创建阶段调用。
+
+| # | 技能名称 | 版本 | 目标框架 | 路径 |
+|---|---------|------|---------|------|
+| 1 | create-qoder-skill | 0.1.0 | Qoder | `meta-skills/create-qoder-skill/` |
+| 2 | create-claude-code-skill | 0.1.0 | Claude Code | `meta-skills/create-claude-code-skill/` |
+| 3 | create-codex-skill | 0.1.0 | Codex | `meta-skills/create-codex-skill/` |
+| 4 | create-openclaw-skill | 0.2.0 | OpenClaw | `meta-skills/create-openclaw-skill/` |
+| 5 | create-hermes-agent-skill | 0.2.0 | Hermes Agent | `meta-skills/create-hermes-agent-skill/` |
+
+> 每个 meta-skill 包含：`skill.json`、`prompt.md`（创建指南）、`spec.md`（规范摘要）、`examples/`（参考示例）、`CHANGELOG.md`
+
+---
+
+## 4. 外部归档（archives/）
+
+从其他地方开发的技能压缩包基础版。**不可变**：严禁修改技能文件，仅允许修改 README.md 和 CHANGELOG.md。
+
+| # | 技能名称 | 版本 | 框架 | 压缩包 | 导入状态 |
+|---|---------|------|------|--------|---------|
+| 1 | cloud-deploy | 2.0 | OpenClaw | `cloud-deploy-2.0.zip` | ✅ 已导入 → v2.0.1 已发布 |
+| 2 | dev-pipeline-universal | 1.0.0 | Hermes Agent | `dev-pipeline-universal-v1.0.0.tar.gz` | ✅ 已导入 → 本地管理 |
+
+---
+
+## 5. 统计概览
+
+| 类别 | 数量 |
+|------|------|
+| 生命周期技能 | 9 |
+| 框架技能 | 2（1 OpenClaw + 1 Hermes） |
+| Meta-Skills | 5 |
+| 外部归档 | 2 |
+| **合计** | **18** |
+
+| 框架 | 技能数 | SkillHub 支持 | 命名空间 |
+|------|--------|--------------|---------|
+| OpenClaw | 1 | ✅ | `sola-openclaw-work` |
+| Claude Code | 0 | ✅ | `sola-claude-code-work` |
+| Codex | 0 | ✅ | `sola-codex-work` |
+| Qoder | 0 | ✅ | `sola-qoder-work` |
+| Hermes Agent | 1 | ❌ | — |