kugetsu/skills/kugetsu-helpers/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
kugetsu-helpers	Helper tools for Hermes to interact with kugetsu. Provides routing, delegation, and status functions.	MIT	Requires Hermes agent, kugetsu CLI, opencode sessions.	author version shoko 1.0

kugetsu-helpers - Hermes Tools for Kugetsu

Provides tools/functions for Hermes to route messages and delegate to the PM Agent.

Overview

This skill enables Hermes (as Chat Agent) to interact with kugetsu-managed opencode sessions.

Tools

kugetsu_get_pm_session

Gets the PM Agent session ID from kugetsu index.

kugetsu_get_pm_session

Returns: PM agent session ID string, or empty if not initialized

Example:

PM_SESSION=$(kugetsu_get_pm_session)
echo "PM Agent: $PM_SESSION"

kugetsu_delegate_to_pm

Delegates a task to the PM Agent via opencode.

kugetsu_delegate_to_pm "<task message>"

Arguments:

• task message: The task to delegate (e.g., "fix issue #5")

Returns: PM Agent response (may be multi-line)

Example:

kugetsu_delegate_to_pm "User wants to fix issue #5 in github.com/shoko/kugetsu"

kugetsu_check_status

Checks kugetsu initialization status.

kugetsu_check_status

Returns: Status string indicating:

• "ok" - kugetsu initialized, PM agent running
• "kugetsu_not_initialized" - Run kugetsu init first
• "pm_agent_missing" - PM agent not found

kugetsu_list_sessions

Lists all kugetsu-managed sessions.

kugetsu_list_sessions

Returns: Formatted list of sessions

kugetsu_create_dev_session

Creates a Dev Agent session for an issue.

kugetsu_create_dev_session "<issue-ref>" "<task>"

Arguments:

• issue-ref: Issue reference (e.g., "github.com/shoko/kugetsu#5")
• task: Task description for the dev agent

Returns: Session creation status

Implementation

These tools are implemented as shell functions that Hermes can call via terminal().

Direct Implementation (Recommended)

Add to Hermes SOUL.md as custom tools:

You have access to kugetsu via terminal commands:

- kugetsu_get_pm_session: Get PM agent session ID
- kugetsu_delegate_to_pm <task>: Delegate to PM agent
- kugetsu_check_status: Check kugetsu status

Tool Definition Format

Hermes tools should call these functions via terminal():

{
  "name": "kugetsu_delegate",
  "description": "Delegate a task to the PM Agent",
  "parameters": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "Task to delegate to PM Agent"
      }
    },
    "required": ["task"]
  }
}

Usage in Hermes

SOUL.md Integration

Add to your SOUL.md:

You can interact with kugetsu to route tasks:

1. Get PM agent session: terminal(command="kugetsu_get_pm_session")
2. Delegate to PM: terminal(command="kugetsu_delegate_to_pm 'fix issue #5'")
3. Check status: terminal(command="kugetsu_check_status")

Routing Logic

User message → Hermes
    │
    ├─ Small talk → respond directly
    │
    └─ Task request → terminal(kugetsu_delegate_to_pm "<task>")
            │
            └─ PM Agent response → relay to user

Error Handling

Error	Cause	Resolution
"kugetsu not initialized"	Run kugetsu init	Inform user
"pm_agent_missing"	PM agent not created	Run kugetsu init
"session not found"	opencode session expired	May need reinit

Files

• scripts/kugetsu-helpers.sh - Shell implementations
• SKILL.md - This documentation