| name | Ankh Development |
| description | Exact techniques, shortcuts, and references for AI agents developing ankh (Hermes with per-folder .agent/ scoping) |
| license | MIT |
| metadata | {"author":"Abruptive LLC","version":"1.0.0"} |
Ankh Development Skill
Techniques and shortcuts for developing ankh. For global repo facts and preferences, see AGENTS.md.
Quick Start
bun install
bun bootstrap
Add ~/.agent/extensions/ankh/bin to PATH. Run hermes ankh or ankh for usage.
Version Upgrade
1. Update pinned version
Edit src/vendor.json (source of truth):
"source": {
"type": "git",
"url": "https://github.com/NousResearch/hermes-agent",
"branch": "v2026.3.12",
"version": "v2026.3.12"
}
- Set
version and branch to the desired Hermes tag (e.g. v2026.3.13).
2. Fresh clone and reapply patches
Patches are applied against the cloned Hermes source. After a version bump, patches may fail:
FRESH_CACHE=1 bash src/scripts/build/install.sh
If a patch fails, install.sh will exit with an error. Fix the patch in src/patches/core/<name>.patch and retry.
3. Patch resolution order
The apply order is defined in src/scripts/build/install.sh (the for patch_name in ... loop). Post-patch hooks: directory runs identity.py; banner runs banner.py.
4. Verify after upgrade
bun bootstrap
bun run test:e2e:repo
bun run test:e2e:tarball
Build, Deploy, Test
| Command | Purpose |
|---|
bun run install | Clone Hermes, apply patches → .build/cache/<version>/ |
bun run build | Create venv, bundle patched source → .build/ |
bun run deploy | Copy to ~/.agent/extensions/ankh/runtime, create wrappers in ~/.agent/extensions/ankh/bin |
bun run test | Validate build, deploy, scoping, uninstall flows |
bun bootstrap | install → build → deploy |
bun run reset | Remove .build |
Shortcuts
- Full cycle:
bun bootstrap
- Re-patch only (no re-clone):
bun run install (uses existing cache if hash matches)
- Fresh patch run:
FRESH_CACHE=1 bun run install
- Override paths (for CI or isolation):
CACHE_DIR, BUILD_DIR, HOME, VERSION
Patch System
Before working on patches, read src/patches/config.json. It lists all patches with descriptions. Use it as the source of truth for what each patch does; do not hard-code patch names or descriptions in this skill.
Layout
src/patches/
├── config.json # Patch metadata (descriptions, enabled flags) – read this first
└── core/
└── <name>.patch # One file per patch; names match config.json core keys
Apply order is in src/scripts/build/install.sh. terminal.patch exists but is not in the install loop; it may be legacy or for future use.
Creating or editing a patch
- Read
src/patches/config.json to understand existing patches.
- Clone Hermes into
.build/cache/<version>/ (via bun run install).
- Edit files under
.build/cache/<version>/ directly.
- Generate a patch:
cd .build/cache/<version> && git diff > ../../../src/patches/core/<name>.patch
- Add
<name> to the for patch_name in ... loop in src/scripts/build/install.sh if new.
- Add an entry to
core in src/patches/config.json (sorted alphabetically) with enabled and description.
- Optionally add a post-patch hook in
run_patch_hook() in install.sh.
- Run
bun run install to verify the patch applies.
Patch hash caching
Install records a hash per patch in .build/cache/<version>/.patches_applied_<name>. If the patch file hash matches, it skips re-application. Use FRESH_CACHE=1 to force a clean re-apply.
Source and References
Scripts Reference
| Script | Role |
|---|
src/scripts/build/install.sh | Clone Hermes, apply patches (version from vendor.json) |
src/scripts/build/build.sh | Venv, pip install, bundle source, create hermes entrypoint |
src/scripts/build/deploy.sh | Copy to ~/.agent/extensions/ankh, write ankh/hermes/ankh-hermes wrappers |
src/scripts/test/test.sh | Test orchestrator (runs e2e-repo, e2e-tarball) |
src/scripts/test/assertions.sh | Build/deploy/scoping/uninstall/tarball assertions |
src/scripts/cli/cli.sh | Shared CLI for install, setup, uninstall |
src/scripts/patch/identity.py | Injects get_agent_identity() after directory.patch |
src/scripts/patch/banner.py | Injects Ankh banner logic after banner.patch |
src/scripts/test/e2e-repo.sh | Full install→build→deploy→test in isolated temp dir |
src/scripts/test/e2e-tarball.sh | npm pack → install → ankh setup → test in isolated temp dir |
bin/ankh sets AGENT_ANKH_PKG_ROOT and execs cli.sh. Deployed wrapper at ~/.agent/extensions/ankh/bin/ankh does the same with VENDOR_DIR from deploy time.
Ensuring Everything Works
- Local:
bun bootstrap – must pass.
- Repo E2E:
bun run test:e2e:repo – clean clone flow in isolated HOME/cache/build.
- Tarball E2E:
bun run test:e2e:tarball – npm pack, global install, ankh setup, test.
Tarball tests enforce: only ankh in package.json bin; no hermes/ankh-hermes bins; no example state.db, .hub, auth.json, etc. in the tarball.
Examples and Defaults
- Examples:
examples/docs-explorer, web-researcher, ascii-designer, diagram-maker, plan-writer – each has .agent/config.yaml, .agent/agent.jsonc, local skills.
- Defaults:
src/resources/defaults/ – config, .env.example; examples inherit via .agent/agent.jsonc or convention.
- Validation:
cd examples/<profile> && hermes config to verify scoped config.
Conventions
- Prefer
ankh and hermes; avoid ankh-hermes except as alias.
- Strip nested
.git from cloned vendor; only package root keeps .git.
- Session DB path:
.agent/storage/state.db.
- Mintlify themes: venus, quill, or prism; favicon required.
- Banner: preserve native Hermes visual fidelity; concise scoped agent info only.
