Create implementation plans with bite-sized tasks, exact file paths, and complete code examples. Use when you have a spec or requirements for a multi-step task.

2026-03-1571

duckduckgo-search

Abruptive/Ankh.md

Free web search via DuckDuckGo when Firecrawl is unavailable. No API key needed. Use ddgs CLI or Python library to find URLs, then web_extract for content.

2026-03-1571

source-digest

Abruptive/Ankh.md

Summarize multiple sources into concise decision-ready findings.

2026-03-1571

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:

# Force a clean cache for the new version
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

Resource	Location
Hermes upstream	https://github.com/NousResearch/hermes-agent
Hermes docs	https://hermes-agent.nousresearch.com/docs/
Hermes config reference	https://hermes-agent.nousresearch.com/docs/user-guide/configuration
Vendor manifest (version, paths, source)	`src/vendor.json`
Patched Hermes source	`.build/cache/<version>/` (after install)
Build output	`.build/` (venv + bundled source)
Deployed runtime	`~/.agent/extensions/ankh/runtime`
Runtime help (shipped with deploy)	`src/resources/console/help.md`
Defaults (mirrors ~/.hermes)	`src/resources/defaults/` (config.yaml, .env.example)
Patch metadata	`src/patches/config.json`

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.