AGENTS.md

Guide for AI coding agents working with or installing from hermes-kit.

What this repo is

Hermes Agent plugins, Hermes-oriented skills, and docs (patched Hermes fork, Feishu customizations, memory method). Human overview: README.md.

Install per host

Details: docs/install.md.

Layout

.
├── plugins/<name>/          GENERATED. Hermes plugins: plugin.yaml + __init__.py with register(ctx)
├── skills/<name>/SKILL.md   GENERATED. Flat, one level deep (the Hermes tap only scans that)
├── docs/                    Hand-written docs, English + .zh-CN.md pairs
│   ├── adr/                 Architecture decision records
│   ├── assets/              README diagrams (light/dark, en/zh)
│   ├── templates/           Fictional MEMORY/USER/SOUL examples
│   └── <guide>.md           GENERATED guides (listed in .export-manifest.json)
├── .claude-plugin/marketplace.json
├── .gitleaks.toml           Generic privacy rules for CI (no personal words)
├── .privacy-allow           Known false positives for the pre-export scan
├── scripts/check-doc-pairs.mjs
├── CONTEXT.md               Glossary (EN + 中文 in one file)
├── AGENTS.md / CLAUDE.md / llms.txt
└── LICENSE

Generated content: do not hand-edit

skills/ and plugins/ are produced by an export script from a private source repo (see ADR 0001). Each export replaces them in one commit. Edits made here directly are lost on the next export.

To change a skill or plugin: open an issue or a PR against this repo. The maintainer applies the change in the source and re-exports.

The guides under docs/ that appear in .export-manifest.json are generated the same way. All other docs, CI, and root files are hand-written and can be edited here.

Naming rules

• Skill directory name = name in SKILL.md frontmatter: lowercase a-z0-9-, at most 64 characters.
• SKILL.md frontmatter: name, description (at most 1024 characters), optional license: MIT.
• Plugin directory name = name in plugin.yaml. plugin.yaml has name, version, description.
• A skill may say "if references/local-*.md exists, read it". local-* files are never published; users create their own.
• No personal or company data in any file: no real chat or user IDs, emails, hostnames, home-directory paths, or people's names.

Bilingual docs

• English is authoritative. Every README.md and docs/**/*.md has a .zh-CN.md pair next to it.
• First line of each: English | [简体中文](x.zh-CN.md) or [English](x.md) | 简体中文.
• Exempt: AGENTS.md, CLAUDE.md, CONTEXT.md (bilingual in one file), llms.txt, LICENSE, docs/templates/, skills/, plugins/.
• When you change an English page, update its pair in the same change.

Validation

node scripts/check-doc-pairs.mjs                         # every doc has its .zh-CN.md pair
python3 -m json.tool .claude-plugin/marketplace.json     # marketplace JSON is valid
gitleaks detect --source . --config .gitleaks.toml       # privacy scan, same as CI
hermes plugins doctor plugins/<name>                     # plugin contract check (needs Hermes)

CI runs the pair check (docs-pair-check.yml) and gitleaks (privacy-scan.yml) on every push and PR.

Docs index