# Okf Ify Agent Setup

> Wires an existing OKF knowledge base into a new coding agent (Claude Code, OpenCode, oh-my-pi, or Hermes) without re-scaffolding the KB. Detects the knowledge base location, asks which agent(s) to configure, and installs the agent-specific hooks, config, and extensions parameterized by the project name and KB path.

- Skill: `geoffjay/okf-ify-agent-setup` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add geoffjay/okf-ify-agent-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/geoffjay/okf-ify-agent-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: geoffjay (https://skillmd.com/u/geoffjay)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/geoffjay/okf-ify-agent-setup

---


# okf-ify-agent-setup

Configure an existing OKF knowledge base for a new agent type. This skill assumes the knowledge base already exists (created by `okf-ify` or manually) and only installs the agent-specific wiring.

## When to Use This Skill

Use this skill when the user:

- Says `/okf-ify-agent-setup` or "okf-ify-agent-setup"
- Wants to "add a new agent" to an existing knowledge base
- Wants to "configure the KB for Claude Code" (or opencode, or oh-my-pi, or hermes) when the KB already exists
- Already has a knowledge base and is adopting a new coding agent

## Workflow

### Step 1: Detect the Knowledge Base

Scan for `index.md` with OKF frontmatter in common locations:

1. `docs/knowledgebase/index.md` (the default).
2. `docs/kb/index.md`.
3. `knowledgebase/index.md`.
4. `kb/index.md`.

If found, confirm the location with the user. If not found, ask the user for the path to the existing knowledge base directory (it must contain an `index.md`).

### Step 2: Determine the Project Name

Derive the project name from:
1. `package.json` `name` field (if it exists).
2. `Cargo.toml` `[package] name` field (if it exists).
3. `go.mod` module name (if it exists).
4. The basename of the project root directory.

### Step 3: Ask Which Agent(s) to Configure

> Which agent(s) should be configured to use this knowledge base?
> Select one or more: claude-code, opencode, oh-my-pi, hermes

Detection rules (pre-select agents whose config directories already exist):
- `.claude/` directory exists → suggest claude-code.
- `.opencode/` directory exists → suggest opencode.
- `~/.hermes/` directory exists (Hermes config home) → suggest hermes.

Skip agents that are already configured (check for existing hooks/config referencing the KB).

### Step 4: Install Agent Configuration

Read the template files from the `okf-ify` skill's `templates/` directory (the same templates used during initial scaffolding). If those templates are not accessible, the templates are also available in this skill's `templates/` directory.

**Placeholders:** All templates use `{{PROJECT_NAME}}`, `{{KB_LOCATION}}`, `{{KB_PATH}}`, `{{PROJECT_SLUG}}`, and `{{PROJECT_ROOT}}` (the absolute project-root path, used by the Hermes templates). Substitute them before writing files.

#### Claude Code

1. Create `.claude/hooks/kb-inject.py` from `templates/claude-kb-inject.py.tmpl`. Make it executable.
2. Create `.claude/hooks/kb-reminder.py` from `templates/claude-kb-reminder.py.tmpl`. Make it executable.
3. Update `.claude/settings.json`:
   - If the file exists, read it and merge the hook entries from `templates/claude-settings-fragment.json.tmpl` into the `hooks` object (merge by event name, appending to existing arrays, avoiding duplicates).
   - If the file does not exist, create it from the fragment template.

#### OpenCode

1. Update `.opencode/opencode.jsonc`:
   - If the file exists, add `"{{KB_LOCATION}}/index.md"` to the `instructions` array (if not already present). Preserve comments and existing structure.
   - If the file does not exist, create it from `templates/opencode-config-fragment.jsonc.tmpl`.

#### oh-my-pi (omp)

1. Create `.omp/extensions/kb-hooks.ts` from `templates/omp-extension.ts.tmpl`. If the file already exists, confirm overwrite.

#### Hermes

1. Create `~/.hermes/agent-hooks/{{PROJECT_SLUG}}-kb-hooks.py` from `templates/hermes-kb-hooks.py.tmpl`. Make it executable. If the file already exists, confirm overwrite.
2. Merge the `hooks:` entries from `templates/hermes-config-fragment.yaml.tmpl` into `~/.hermes/config.yaml`:
   - If the file exists, read it and append the entries to the `pre_llm_call`, `post_tool_call`, and `pre_verify` lists (create the lists if absent), avoiding duplicates.
   - If the file does not exist, create it from the fragment template.
   - Hermes has no project-level config (entries in `~/.hermes/config.yaml` are user-global), so the script template embeds the absolute project root (`{{PROJECT_ROOT}}`) and no-ops when the payload `cwd` is outside it.
   - Hermes prompts for consent on first use of each `(event, command)` pair (bypass with `--accept-hooks`, `HERMES_ACCEPT_HOOKS=1`, or `hooks_auto_accept: true`) — mention this in the report.

### Step 5: Update the KB Index

Update `{{KB_LOCATION}}/index.md` to mention the newly configured agent in the "For agents (policy)" section. Add a line describing how the agent is wired (e.g., "oh-my-pi via the `.omp/extensions/kb-hooks.ts` extension", "hermes via shell hooks registered in `~/.hermes/config.yaml`").

Also add an entry to `{{KB_LOCATION}}/log.md`:

```
## {{DATE}}
* **Agent setup**: Configured the knowledge base for {{AGENT_NAME}} via `npx skills use geoffjay/okf-ify --skill okf-ify-agent-setup`.
```

### Step 6: Report

Print a summary:
- The agent(s) configured.
- The files created/updated.
- A note that the `TRIGGERS` lists in reminder hooks are empty (for newly added agents) and should be filled with project-specific path patterns.
- For hermes: a note that Hermes prompts for consent on first use of each `(event, command)` pair (or to run once with `--accept-hooks` / `HERMES_ACCEPT_HOOKS=1` / `hooks_auto_accept: true`).

## Templates

This skill shares the same template files as `okf-ify`. The templates are in `templates/` next to this SKILL.md:

- `claude-kb-inject.py.tmpl` — SessionStart hook (Python).
- `claude-kb-reminder.py.tmpl` — PostToolUse + Stop hooks (Python).
- `claude-settings-fragment.json.tmpl` — `.claude/settings.json` hook registrations.
- `omp-extension.ts.tmpl` — `.omp/extensions/kb-hooks.ts` extension (TypeScript).
- `hermes-kb-hooks.py.tmpl` — pre_llm_call + post_tool_call + pre_verify shell hooks (Python).
- `hermes-config-fragment.yaml.tmpl` — `~/.hermes/config.yaml` hook registrations.

## Non-Goals

- This skill does **not** create or re-scaffold the knowledge base. Use `okf-ify` for that.
- This skill does **not** remove agent configurations. To remove an agent, manually delete its hooks/config and remove the KB reference.
- This skill does **not** populate the `TRIGGERS` list. The user fills in project-specific path patterns after setup.