sinohqb 1bcf196779 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

2.8 KiB

Raw Permalink Blame History

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 正文）。

发布流程要点

必须先 --dry-run：skillhub publish <路径> --namespace <ns> --dry-run
SkillHub 拒绝 .conf 文件，需重命名为 .conf.txt
发布后更新 <框架>/publish/registry.json 和 CHANGELOG
修改前必须将当前版本归档到 <框架>/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 — 各框架技能规范

2.8 KiB Raw Permalink Blame History Unescape Escape