ai-counsel: Skill for Claude Code

Adapter Factory Skill

This skill teaches how to integrate new AI models into the AI Counsel MCP server by creating adapters. There are two types of adapters:

1. CLI Adapters - For command-line AI tools (e.g., claude, droid, codex)
2. HTTP Adapters - For HTTP API integrations (e.g., Ollama, LM Studio, OpenRouter)

When to Use This Skill

Use this skill when you need to:

• Add support for a new AI model or service to participate in deliberations
• Integrate a command-line AI tool (CLI adapter)
• Integrate an HTTP-based AI API (HTTP adapter)
• Understand the adapter pattern used in AI Counsel
• Debug or modify existing adapters

Architecture Overview

Base Classes

BaseCLIAdapter (adapters/base.py)

• Handles subprocess execution, timeout management, and error handling
• Provides invoke() method that manages the full CLI lifecycle
• Subclasses only implement parse_output() for tool-specific parsing
• Optional: Override _adjust_args_for_context() for deliberation vs. non-deliberation behavior
• Optional: Implement validate_prompt_length() for length limits

BaseHTTPAdapter (adapters/base_http.py)

• Handles HTTP requests, retry logic with exponential backoff, and timeout management
• Uses httpx for async HTTP and tenacity for retry logic
• Retries on 5xx/429/network errors, fails fast on 4xx client errors
• Subclasses implement build_request() and parse_response()
• Supports environment variable substitution for API keys

Factory Pattern

The create_adapter() function in adapters/__init__.py:

• Maintains registries for CLI and HTTP adapters
• Creates appropriate adapter instances from config
• Handles backward compatibility with legacy config formats

---

Creating a CLI Adapter

Follow these 6 steps to add a new command-line AI tool:

Step 1: Create Adapter File

Create adapters/your_cli.py:

"""Your CLI tool adapter."""
from adapters.base import BaseCLIAdapter


class YourCLIAdapter(BaseCLIAdapter):
    """Adapter for your-cli tool."""

    def parse_output(self, raw_output: str) -> str:
        """
        Parse your-cli output to extract model response.

        Args:
            raw_output: Raw stdout from CLI tool

        Returns:
            Parsed model response text
        """
        # Example: Strip headers and extract main response
        lines = raw_output.strip().split("\n")

        # Skip header lines (tool-specific logic)
        start_idx = 0
        for i, line in enumerate(lines):
            if line.strip() and not line.startswith("Loading"):
                start_idx = i
                break

        return "\n".join(lines[start_idx:]).strip()