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.