From 1bcf196779f2b92101485eea4b4781e004894841 Mon Sep 17 00:00:00 2001 From: sinohqb Date: Thu, 2 Jul 2026 01:48:17 +0800 Subject: [PATCH] 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 --- AGENTS.md | 58 +++++++++++++++++++++++ SKILL-REGISTRY.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 173 insertions(+) create mode 100644 AGENTS.md create mode 100644 SKILL-REGISTRY.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b621932 --- /dev/null +++ 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 --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` — 各框架技能规范 diff --git a/SKILL-REGISTRY.md b/SKILL-REGISTRY.md new file mode 100644 index 0000000..4fba46e --- /dev/null +++ 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 | ❌ | — |