universal-command

What This Skill Does

The universal-command package acts as a foundational architecture for building and deploying AI agent tools within the Supernal ecosystem. It solves the fragmentation problem in modern development where the same functional business logic must be rewritten or refactored for different access layers—specifically CLI, API, and MCP (Model Context Protocol). By defining a command structure once using this universal interface, the developer ensures that the input validation, logic handler, and response formatting remain consistent across all distribution channels. This eliminates interface drift and significantly reduces the maintenance overhead for agents and tools.

Installation

To integrate this into your development workflow, use the OpenClaw CLI to install the dependency directly into your skill project:

clawhub install openclaw/skills/skills/ianderrington/universal-command

Alternatively, for standard Node.js projects:

npm install @supernal/universal-command

Use Cases

This skill is essential for platform engineers and developers creating multi-modal AI agents. Primary use cases include:

• Developing unified SDKs where the same command logic drives a terminal-based CLI tool and an MCP server for AI context.
• Building microservices where internal API routes must share validation schemas with external agent tools.
• Maintaining complex backend operations that require consistent authorization and performance characteristics (like cache control) regardless of how the command is invoked.
• Managing large registries of tools that need to be dynamically registered or exposed to LLMs via the Model Context Protocol.

Example Prompts

1. "Initialize a new universal command for a user management system that handles creating, listing, and deleting records using the @supernal/universal-command pattern."
2. "Refactor my existing API route for generating reports to use the UniversalCommand structure so it can also be triggered via the MCP interface."
3. "Set up a CommandRegistry for my CLI tool that automatically maps all defined universal-command handlers to the corresponding CLI subcommands and MCP tool declarations."

Tips & Limitations

• Tip: Always define your input schemas with strict TypeScript types to leverage full autocompletion across your API and CLI implementations.
• Tip: Use the optional cli, api, and mcp blocks within the configuration object to fine-tune interface-specific behavior like streaming or custom authentication scopes without polluting your core handler logic.
• Limitation: This package assumes your environment is Node.js-based. It is not intended for client-side browser logic unless wrapped in a suitable server-side proxy.
• Critical: Never implement custom logic to bridge CLI or API layers if a UniversalCommand can be used; this package is the standardized approach for Supernal compatibility.