# 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` — 各框架技能规范