This manual documents best practices for integrating a CLI tool with modern coding-agent ecosystems, based on:
- reference implementation patterns.
- a companion state service integration pattern for MCP and lifecycle hooks.
- official platform docs for Claude Code/Desktop, ChatGPT, Codex, Gemini, MCP, VS Code customization surfaces (skills, hooks, MCP, plugins), and Context7.
- Maintainers building a new CLI that should be agent-compatible from day one.
- Platform integrators maintaining hooks, instruction files, and skills across tools.
- Security and infra reviewers validating trust boundaries around tool execution.
Choose your starting guide by host and setup goal:
| Goal | Start here |
|---|---|
| Claude Code project integration with hooks and MCP | frameworks/claude-code.md |
| Claude Desktop local MCP setup | frameworks/claude-desktop.md |
| Codex + skill-oriented workflow | frameworks/codex.md |
| Gemini CLI/API integration | frameworks/gemini.md |
| Pi agent integration | frameworks/pi.md |
| VS Code MCP host setup | frameworks/vscode.md |
| Cross-host architecture first (before framework specifics) | topics/architecture-patterns.md |
If unsure, run this order first: references/new-cli-checklist.md → topics/instructions-and-skills.md → one framework guide.
- Platform-specific setup and installation flows.
- Instruction layering (AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, skill files).
- Skills marketplace discovery and skill intake governance.
- Skill authoring lifecycle: quickstart, SKILL.md contract, scripts, and versioning.
- Trigger-quality and output-quality skill evaluation loops.
- Hook lifecycle and guardrails.
- MCP server design and transport choices.
- Security and approvals strategy.
- Observability and integration testing patterns.
- Copy-paste snippets and project bootstrap checklist.
Keep these concepts separate during implementation:
- Installable skill package: end-user/agent-facing bundle (for example
<tool>-skill/withSKILL.md). - Internal contract metadata: validation/readiness descriptors used by sync checks.
Do not use internal metadata identifiers as installable skill package names.
- Claude Code
- Claude Desktop
- ChatGPT Desktop
- Codex
- Gemini CLI and API
- Pi
- Hermes Agent
- OpenCode
- OpenClaw
- Cursor
- Factory Droid
- Trae and Trae-CN
- VS Code
- Integration Architecture Patterns
- MCP Server Design
- MCP Bundles (MCPB)
- Hooks and Lifecycle Control
- Instruction Layers and Skills
- Agent Skills Specification
- AGENTS.md Maintenance and Sync Rules
- Skills Marketplace Integration
- Security and Approvals
- Observability and Testing
- Source and Evidence Matrix
- References
- New CLI Integration Checklist
- Required Skills Matrix
- Snippets Cookbook
- Compatibility Matrix
- Install Idempotency Guide
- Transport and Auth Matrix
- Framework Weakness Backlog
- Docs Maintenance and Changelog
- Anthropic Agent Skills Best Practices
- Anthropic Agent Skills Overview
- Anthropic Skills Guide (API)
- Claude Desktop Local MCP Servers
- Claude Custom Skills
- Skills in ChatGPT
- ChatGPT Developer mode
- Agent Skills Quickstart
- Agent Skills Best Practices
- Optimizing Skill Descriptions
- Evaluating Skills
- Using Scripts in Skills
- Agent Skills Specification
- OpenAI Codex Skills
- Anthropic skill-creator SKILL.md
- MCPB Repository
- MCPB Manifest Spec
- MCPB CLI Docs
- OpenClaw Skills
- OpenClaw Creating Skills
- OpenClaw Skills Config
- OpenClaw Slash Commands
- OpenClaw ClawHub
- Hermes Adding Tools
- Hermes Adding Providers
- Hermes Adding Platform Adapters
- Hermes Memory Provider Plugins
- Hermes Context Engine Plugins
- Hermes Creating Skills
- Hermes MCP Feature Guide
Key skill docs to start with:
- Instruction Layers and Skills for skill authoring, triggering, scripts, and versioning.
- Observability and Testing for trigger and output eval loops.
- Skills Marketplace Integration for intake, hardening, and promotion gates.
The recommended integration stack for a CLI tool has four layers:
- Runtime interface layer: CLI commands, config paths, install/uninstall commands.
- Instruction layer: persistent files that influence agent behavior (AGENTS.md and platform-specific variants).
- Lifecycle layer: hooks that fire before and after tool execution and at stop/compaction boundaries.
- Context exchange layer: MCP server for discoverable tools and structured argument schemas.
- Deterministic installation and idempotent reinstall behavior.
- Clear boundaries between policy, execution, and transport.
- Minimal surprise for users switching between agent frameworks.
- Explicit fallback behavior for frameworks with partial hook support.
- Testable integration contracts, not only happy-path docs.
This is v1 of the manual and is intentionally implementation-heavy. If you are starting from scratch, use the checklist first, then implement one framework end-to-end before expanding to others.