AI Agent Skills Integration

Skill-Only Mode — The fastest way to connect your AI coding agents to Orchestratia. No daemon process, no background service — just hooks and a CLI tool. Supports Claude Code, Gemini CLI, and Codex CLI.

What Is It?

The Orchestratia Skills package integrates your AI coding agents with the Orchestratia hub using three lightweight components:

1. SessionStart hook — Injects task context into the agent's conversation when a session starts
2. PreToolUse hook — Checks approval rules before every tool execution
3. orchestratia CLI — Full command-line tool for task management

No background daemon. No persistent WebSocket. Agents poll the hub via the CLI when they need updates. The hooks run automatically as part of each agent's native hook system.

flowchart LR
    Agents["Claude Code<br/>Gemini CLI<br/>Codex CLI"] -->|"SessionStart<br/>hook"| CTX["Context<br/>Injection"]
    Agents -->|"PreToolUse<br/>hook"| PERM["Permission<br/>Check"]
    Agents -->|"CLI<br/>commands"| CLI["orchestratia<br/>CLI"]
    CLI -->|"REST API"| Hub["Orchestratia<br/>Hub"]

    style Agents fill:#F3F0EA,stroke:#918A80
    style CTX fill:#E6F8FB,stroke:#00B8D9
    style PERM fill:#E6F8FB,stroke:#00B8D9
    style CLI fill:#E6F8FB,stroke:#00B8D9
    style Hub fill:#00B8D9,stroke:#0A7A92,color:#fff

Supported Agents

Each agent gets its own SKILL.md with agent-specific instructions, while the hooks and CLI are shared across all agents.

How Skills Work with the Agent

Skills are automatically installed as part of the Full Agent setup. The agent daemon installs the appropriate SKILL.md and hooks for each detected AI agent on your server.

Skills provide two key capabilities on top of the daemon:

• SessionStart hooks — inject task context when an agent session begins
• PreToolUse hooks — enforce permission rules before tools are executed

Manual Skill Installation

If you need to install or update skills independently (e.g. adding a new agent to an existing server):

1. Generate a Registration Token

1. Go to Servers in the Orchestratia dashboard
2. Click + Add Server
3. Set a label and expiry
4. Copy the token

2. Run the Install Script

# Auto-detect and configure all installed agents
curl -fsSL https://raw.githubusercontent.com/kumarimlab/orchestratia-skills/main/install.sh | bash -s -- TOKEN
 
# Or configure specific agents only
curl -fsSL .../install.sh | bash -s -- TOKEN --agent claude,gemini

The installer auto-detects which AI agents are installed and configures each one. After installation, you'll see a detection report:

Agent Detection:
  ✓ Claude Code  — configured (skill + hooks)
  ✓ Gemini CLI   — configured (skill + hooks)
  ✗ Codex CLI    — not found. Install it, then run: orchestratia setup --agent codex

3. Adding an Agent Later

If you install a new AI agent after Orchestratia:

orchestratia setup --agent gemini    # Configure Gemini CLI
orchestratia setup --agent codex     # Configure Codex CLI
orchestratia setup --agent all       # Configure all detected agents

4. Verify

Open a new session in any configured agent. You should see the Orchestratia context banner:

==========================================================
Orchestratia Agent: my-server / Claude Session (worker)
Project: My Project
No assigned tasks. Waiting for orchestrator.
 
Use /orchestratia for workflow details
==========================================================

Your server will also appear on the dashboard as Online with a "Skill" connection badge.

What Gets Installed

How the Hooks Work

SessionStart: Context Injection

When any AI agent starts a session, the SessionStart hook runs automatically:

1. Checks if this is an Orchestratia-managed environment (ORCHESTRATIA_HUB_URL env var)
2. Calls orchestratia status --json to get server, session, and task info
3. Formats and injects a context banner into the agent's conversation

This gives the agent immediate awareness of its role, assigned tasks, and the project context — without any manual prompting. The same hook script works for all three agents.

PreToolUse: Permission Enforcement

Before every tool invocation, the PreToolUse hook:

1. Reads the tool name and parameters from the agent's hook input
2. Loads cached approval rules from the hub (stored locally for speed)
3. Matches rules in priority order:
   • Allow — tool proceeds without prompting
   • Deny — tool is blocked with a reason
   • Ask — agent shows its normal permission prompt
4. Logs the decision for audit purposes

The hook automatically handles tool name differences across agents (e.g., Claude's Bash vs Gemini's run_shell_command). The entire check takes under 50ms.

Agent-Specific Notes

Claude Code

• Hooks registered in ~/.claude/settings.json
• PreToolUse intercepts all tools (Bash, Edit, Write, Read, WebFetch, etc.)
• Supports /orchestratia slash command for workflow details

Gemini CLI

• Hooks registered in ~/.gemini/settings.json
• Uses BeforeTool event (equivalent to PreToolUse)
• Intercepts all tools (run_shell_command, write_file, read_file, etc.)
• Supports @orchestratia skill invocation
• Also supports gemini skills install from the GitHub repo directly

Codex CLI

• Hooks registered in ~/.codex/hooks.json
• Requires features.codex_hooks = true in ~/.codex/config.toml (auto-set by installer)
• PreToolUse currently intercepts Bash tool calls only (OpenAI limitation)
• File operations governed by Codex's sandbox mode and .codexpolicy rules
• Skill also installed at ~/.agents/skills/orchestratia/ (shared path)

SKILL.md: What Agents Learn

Each agent gets an agent-specific SKILL.md that teaches:

• Role detection — Worker vs Orchestrator based on session name
• Worker workflow — task check → task view → task start → do work → task complete
• Orchestrator workflow — task create → task assign → monitor progress
• Plan mode — Submit execution plans for review before coding
• Task notes — Communicate with humans or other agents
• Help requests — Request human intervention when stuck
• Structured results — Report completion with contract data for downstream tasks
• Dependencies — Understand blocks, input, and related dependency types
• Cross-session commands — Execute commands on other sessions
• File transfers — Send files between sessions
• SSH access grants — Use inter-server SSH tunneling

The CLI commands are identical across all agents — only the agent-specific tips differ.

CLI Quick Reference

The full CLI reference is in the AI Agent Integration Guide. Here are the most common commands:

# Check your identity and connection
orchestratia status --json
 
# Check for assigned tasks
orchestratia task check --json
 
# View task details
orchestratia task view <id> --json
 
# Start working on a task
orchestratia task start <id>
 
# Report completion
orchestratia task complete <id> --result "summary or JSON"
 
# Report failure
orchestratia task fail <id> --error "what went wrong"
 
# Request human help
orchestratia task help <id> --question "..."
 
# Add a note to a task
orchestratia task note <id> --content "progress update"

All commands support --json for machine-readable output. Task IDs accept short prefixes (minimum 4 characters).

Upgrading to Full Agent

When you're ready for live terminal streaming, session sharing, and file transfer, the full agent daemon installer auto-detects and configures all three agents too:

curl -fsSL https://install.orchestratia.com/linux | sudo bash -s -- TOKEN

The full agent includes everything from the skills package plus persistent WebSocket streaming, session management, file transfer, and SSH access grants.

Uninstalling

curl -fsSL https://raw.githubusercontent.com/kumarimlab/orchestratia-skills/main/uninstall.sh | bash

This removes hook scripts, SKILL.md files for all agents, config, and cleans hook entries from all agent settings files.

Source Code

The skills package is open source: github.com/kumarimlab/orchestratia-skills