uncaged/nerve
Archived
10
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

fix: update Hermes nerve skill (SKILL.md) for flat workspace and four-tuple pattern #298

New Issue
Closed
opened 2026-04-30 14:10:20 +00:00 by xiaoju · 0 comments
xiaoju commented 2026-04-30 14:10:20 +00:00
Owner
Copy Link
Copy Source

Background

The Hermes nerve skill at packages/cli/skills/hermes/SKILL.md was written before several structural changes and is now stale.

Issues to fix

1. Workspace structure (workflow section)

Currently shows folder-based roles:

└── roles/<role>/
    ├── index.ts
    └── prompt.md

Should be flat single-file roles:

workflows/<name>/
├── index.ts          # default export (wires adapters + config)
├── build.ts          # factory: createXxxWorkflow({adapters, extract})
├── moderator.ts      # moderator function + WorkflowMeta type
└── roles/<role>.ts   # schema + prompt + createXxxRole (one file per role)

Also missing: build.ts and moderator.ts in the file listing.

2. Add createRole four-tuple pattern

Workflow 开发指南 section only shows hand-written role functions. Add the standard pattern:

import { createRole } from "@uncaged/nerve-workflow-utils";

const coder = createRole(adapter, coderPrompt, coderMetaSchema, extract);

Explain the four arguments: adapter (AgentFn), prompt (string or async fn), Zod schema, extract config.

3. Add createLlmAdapter

Mention that pure-LLM roles (no tool use) use createLlmAdapter(provider) from @uncaged/nerve-workflow-utils instead of cursor/hermes adapter.

4. Sense compute signature

  • The LibSQLDatabase import should reference the actual import path used in the project (check packages/daemon/src/sense-runtime.ts for the real type)
  • Remove SenseModule type reference if it does not exist in @uncaged/nerve-core
  • Verify the compute() signature matches what the daemon actually expects

5. Add AGENT.md reference

nerve init now generates AGENT.md at workspace root. Mention it in the workspace structure section and in the "开发新 workflow" pattern.

6. Verb-first workflow naming

Add naming convention: workflow names must be verb-first kebab-case (e.g. solve-issue, extract-knowledge; not knowledge-extraction).

7. Add nerve agent CLI commands

The skill itself is installed via nerve agent inject hermes but the CLI reference section does not list the nerve agent subcommands:

nerve agent inject hermes           # 安装 Hermes nerve skill
nerve agent inject hermes --profile xiaoju  # 指定 profile
nerve agent update                  # 更新所有已安装的 skill
nerve agent remove hermes           # 移除
nerve agent status                  # 查看安装状态

8. CLI_VERSION hardcode (agent.ts)

packages/cli/src/commands/agent.ts line 16: const CLI_VERSION = "0.5.0" is hardcoded. Read from package.json instead:

import { readFileSync } from "node:fs";
const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8"));
const CLI_VERSION = pkg.version;

Or use a build-time constant. This prevents version drift on every release.

9. No per-workflow package.json

Update the "开发新 workflow" pattern — remove cd workflows/<name> && pnpm install && pnpm build. The correct build command is npm run build from workspace root.

Verify

  • pnpm -r run test — all must pass
  • Read through the updated SKILL.md end-to-end for consistency

Constraints

## Background The Hermes nerve skill at `packages/cli/skills/hermes/SKILL.md` was written before several structural changes and is now stale. ## Issues to fix ### 1. Workspace structure (workflow section) Currently shows folder-based roles: ``` └── roles/<role>/ ├── index.ts └── prompt.md ``` Should be flat single-file roles: ``` workflows/<name>/ ├── index.ts # default export (wires adapters + config) ├── build.ts # factory: createXxxWorkflow({adapters, extract}) ├── moderator.ts # moderator function + WorkflowMeta type └── roles/<role>.ts # schema + prompt + createXxxRole (one file per role) ``` Also missing: `build.ts` and `moderator.ts` in the file listing. ### 2. Add createRole four-tuple pattern Workflow 开发指南 section only shows hand-written role functions. Add the standard pattern: ```ts import { createRole } from "@uncaged/nerve-workflow-utils"; const coder = createRole(adapter, coderPrompt, coderMetaSchema, extract); ``` Explain the four arguments: adapter (AgentFn), prompt (string or async fn), Zod schema, extract config. ### 3. Add createLlmAdapter Mention that pure-LLM roles (no tool use) use `createLlmAdapter(provider)` from `@uncaged/nerve-workflow-utils` instead of cursor/hermes adapter. ### 4. Sense compute signature - The `LibSQLDatabase` import should reference the actual import path used in the project (check `packages/daemon/src/sense-runtime.ts` for the real type) - Remove `SenseModule` type reference if it does not exist in `@uncaged/nerve-core` - Verify the `compute()` signature matches what the daemon actually expects ### 5. Add AGENT.md reference `nerve init` now generates `AGENT.md` at workspace root. Mention it in the workspace structure section and in the "开发新 workflow" pattern. ### 6. Verb-first workflow naming Add naming convention: workflow names must be verb-first kebab-case (e.g. `solve-issue`, `extract-knowledge`; not `knowledge-extraction`). ### 7. Add `nerve agent` CLI commands The skill itself is installed via `nerve agent inject hermes` but the CLI reference section does not list the `nerve agent` subcommands: ```bash nerve agent inject hermes # 安装 Hermes nerve skill nerve agent inject hermes --profile xiaoju # 指定 profile nerve agent update # 更新所有已安装的 skill nerve agent remove hermes # 移除 nerve agent status # 查看安装状态 ``` ### 8. CLI_VERSION hardcode (agent.ts) `packages/cli/src/commands/agent.ts` line 16: `const CLI_VERSION = "0.5.0"` is hardcoded. Read from `package.json` instead: ```ts import { readFileSync } from "node:fs"; const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8")); const CLI_VERSION = pkg.version; ``` Or use a build-time constant. This prevents version drift on every release. ### 9. No per-workflow package.json Update the "开发新 workflow" pattern — remove `cd workflows/<name> && pnpm install && pnpm build`. The correct build command is `npm run build` from workspace root. ## Verify - `pnpm -r run test` — all must pass - Read through the updated SKILL.md end-to-end for consistency ## Constraints - Branch: `fix/295-update-hermes-skill` - Commit as: 小橘 <xiaoju@shazhou.work> - Reference: Fixes #<this issue>
This repo is archived. You cannot comment on issues.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/nerve#298
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?