Claude Code Skills Integration

Skill-Only Mode — The fastest way to connect Claude Code to Orchestratia. No daemon process, no background service — just hooks and a CLI tool. Perfect for quick setups, evaluations, or environments where running a daemon isn't practical.

What Is It?

The Orchestratia Skills package integrates Claude Code with the Orchestratia hub using three lightweight components:

1. SessionStart hook — Injects task context into Claude'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. Claude Code polls the hub via the CLI when it needs updates. The hooks run automatically as part of Claude Code's normal hook system.

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

    style CC fill:#F3F0EA,stroke:#918A80
    style CTX fill:#F0F9F7,stroke:#2A9D88
    style PERM fill:#F0F9F7,stroke:#2A9D88
    style CLI fill:#F0F9F7,stroke:#2A9D88
    style Hub fill:#2A9D88,stroke:#186B5D,color:#fff

Skill-Only vs Full Agent

When to use Skill-Only:

• Quick evaluation of the platform
• Environments where background daemons are restricted
• Single-developer setups where live streaming isn't needed
• Claude Code–specific workflows

When to upgrade to Full Agent:

• You need live terminal streaming in the dashboard
• Multiple team members need to watch agent output
• You want file transfer, SSH grants, or session sharing
• You need real-time push (instant task assignment, not polling)

Installation

1. Generate a Registration Token

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

2. Run the Install Script

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

This single command:

• Installs the orchestratia CLI via pip
• Downloads hook scripts to /opt/orchestratia-skills/hooks/
• Installs the SKILL.md to ~/.claude/skills/orchestratia/
• Configures hooks in ~/.claude/settings.json
• Registers with the hub and stores the API key

3. Verify

Open a new Claude Code session. 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 Claude Code 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 Claude's conversation

This gives Claude immediate awareness of its role, assigned tasks, and the project context — without any manual prompting.

PreToolUse: Permission Enforcement

Before every tool invocation (Bash, Edit, Read, WebFetch, etc.), the PreToolUse hook:

1. Reads the tool name and parameters from Claude Code'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 — Claude Code shows its normal permission prompt
4. Logs the decision for audit purposes

The entire check takes under 50ms. Rules are cached locally and refreshed when the hub broadcasts updates.

SKILL.md: What Claude Learns

The SKILL.md file is placed in Claude Code's skills directory, so Claude automatically reads it. It 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

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:

1. Uninstall skills: curl -fsSL https://raw.githubusercontent.com/kumarimlab/orchestratia-skills/main/uninstall.sh | bash
2. Generate a new registration token (choose Agent tier)
3. Install the full daemon:

curl -fsSL https://raw.githubusercontent.com/kumarimlab/orchestratia-agent/main/scripts/install-linux.sh | sudo bash -s -- TOKEN

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

Uninstalling

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

This removes hook scripts, SKILL.md, config, and cleans the hook entries from ~/.claude/settings.json. The orchestratia CLI pip package is left installed — run pip3 uninstall orchestratia-agent to remove it.

Source Code

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