1bcf196779
- 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
59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# 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` — 各框架技能规范
|