🐋 Orca CLI

A CLI tool for managing AI agent skills, sub-agents, plugins, and MCP servers. While npx skill supports downloading skills, it’s still difficult to narrow down specific skills or resources required for your coding agent.

🚀 Quick Start

# Install dependencies
uv sync

# Help
orca --help

# Initialize your project
orca init

# Cache skill repositories (uses shallow clones for efficiency)
orca cache init

# Search for skills from various sources (with intelligent matching)
orca search npm typescript
orca search github "ai agent"
orca search cache azure  # Uses directory structure and metadata for better results

# Start adding resources
orca add skill azure-ai-projects-py
orca add mcp github

📦 Installation

uv sync

.\build.ps1  # Creates the executable file in the dist directory.

💡 Usage Examples

# Initialize project
orca init

# Set runtime environment (creates .github and runtime reference files)
orca runtime github
orca runtime claude  # Creates .claude/ with references to .github/

# Add resources to configuration (does not copy files yet)
orca add skill azure-ai-projects-py
orca add plugin typescript-validator
orca add subagent code-reviewer
orca add mcp github

# List all resources
orca list

# Remove resources from configuration
orca remove skill my-skill
orca remove mcp github

# Cache management (uses git clone --depth 1 for efficiency)
orca cache init
orca cache add https://github.com/microsoft/skills
orca cache remove https://github.com/microsoft/skills
orca cache list # All available resources
orca cache clean

# Configure LLM for AGENTS.md generation
orca config-llm

# Compile: Copy resources from cache (or install from npm if not found),
# create runtime files, and generate AGENTS.md with compile report
orca compile

🛠️ Commands Reference

Project Setup

• orca init - Initialize .orca directory and create project configuration
• orca runtime <github|gemini|claude> - Set runtime environment

Resource Management

• orca add <type> <name> - Add skill, plugin, subagent, or MCP to configuration
• orca remove <type> <name> - Remove resource from configuration
• orca list [type] - List all resources or filter by type
• orca compile - Copy resources to .github/, create runtime files, and generate AGENTS.md

Cache Management

• orca cache init - Clone all configured repositories (shallow clones)
• orca cache add <url> - Add and clone GitHub repository to cache
• orca cache remove <url> - Remove repository from cache and delete files
• orca cache clean - Remove all cached repositories to free disk space
• orca cache list - List all available resources

Search & Discovery

• orca search npm <query> - Search npm registry for AI agent skills (supports npx usage)
• orca search github <query> - Search GitHub repositories for AI agent skills
• orca search cache <query> - Search locally cached repositories for skills

Configuration & Compilation

• orca config-llm - Configure LLM settings (OpenAI, Azure OpenAI, auth method)
• orca compile - Copy resources from cache to .github/ (or install from npm if not found), create .vscode/mcp.json, generate AGENTS.md using LLM, and produce COMPILE_REPORT.md
• orca think <description> - Auto-detect resources based on project description (file path or text)

Note: add and remove commands only update configuration. Run orca compile to materialize resources.

Features

✨ Smart Caching - Shallow git clones reduce cache size by ~90%
✨ Glob/Grep/Read Discovery - Core resource discovery using pattern matching, YAML parsing, and file extraction
✨ Intelligent Search - Directory structure understanding and metadata extraction for better context
✨ Relevance Scoring - Ranks results by query relevance using name, description, path, and tag matching
✨ NPM Fallback - Auto-installs from npm registry if resource not found in cache during compile
✨ Compile Reports - Generates detailed COMPILE_REPORT.md showing what was copied, installed, or missing
✨ Multi-Source Search - Find skills from npm, GitHub, and local cache
✨ Single Source of Truth - All resources in .github/, runtime references avoid duplication
✨ LLM Integration - Azure AD authentication supported (no API keys needed), api_version removed per latest Azure OpenAI spec
✨ Context-Aware Display - Enhanced search results with directory hierarchy and tag information
✨ Extensible - Command Pattern architecture for easy customization

References

• npx skills

---

📁 Test Data - Sample Project

The sample/ directory contains a fully configured demonstration project showing Orca CLI in action:

Directory Structure

sample/
├── sample.yml             # Orca configuration file
├── AGENTS.md              # LLM-generated agent documentation
├── COMPILE_REPORT.md      # Detailed compilation report
├── main.py                # Echo API server implementation
├── test_cli.ps1           # Comprehensive CLI test suite
├── .github/               # Source of truth for all resources in `_results.zip`
│   ├── skills/            # Azure Cosmos DB, Azure Identity skills
│   ├── plugins/           # Deep-wiki plugin with commands & agents
│   └── subagents/         # Planner & backend agents
├── .claude/               # Claude runtime (references to .github/) in `_results.zip`
├── .gemini/               # Gemini runtime (references to .github/) in `_results.zip`
├── .orca/                 # Cache and global configuration in `_results.zip`
└── .vscode/               # MCP server configuration in `_results.zip`
    └── mcp.json

Included Resources

• Skills: azure-cosmos-py, azure-identity-py
• Plugins: deep-wiki (with 10+ commands and sub-skills)
• Subagents: planner, backend
• MCP Servers: io.github.github/github-mcp-server

Running the Test Suite

Execute the comprehensive test suite to see Orca CLI in action:

cd sample
.\test_cli.ps1