ai-skills-api/SETUP.md

Setup Guide: AI Skills API

This guide covers exactly how to deploy the AI Skills API on your home server (helm) and set up new agent projects.

Prerequisites

• Docker & Docker Compose installed on helm
• Access to helm from your development machine (SSH or local)
• Optional: Claude Desktop with MCP support

Server Setup (One-Time)

Deploy the AI Skills API service on your home server.

1. Clone the Repository

# On helm (or accessible to docker)
cd /opt
git clone ssh://git@helm:222/helm/ai-skills-api.git
cd ai-skills-api

2. Build and Start Services

# Build and start all services (API + Ollama + MCP)
docker compose up -d --build

# Check it's running
docker compose ps
# Should show: api, ollama, mcp (all "Up")

3. Verify Deployment

# Health check (from helm)
curl http://localhost:8675/health

# Expected response: {"status":"healthy"}

4. Configure Optional Settings

Edit config.yaml (creates defaults if missing):

port: 8675
rag:
  max_skills: 3
  max_conventions: 2
  max_snippets: 2
compression:
  enabled: true
  strategy: "extractive"  # or "ollama" for phi-3-mini
auth:
  enabled: false  # set to true to require API key
  api_key: "your-secret-key-here"

Restart after changes:

docker compose restart

5. (Optional) Enable API Authentication

If you want auth across your network:

1. Edit config.yaml:

   auth:
     enabled: true
     api_key: "generate-a-strong-random-key"
   

2. Restart:

   docker compose restart
   

3. Test:

   curl http://helm:8675/health  # Should work (no auth)
   curl http://helm:8675/skills  # Should fail 401 if auth enabled
   curl -H "X-API-Key: your-secret-key-here" http://helm:8675/skills  # Should work
   

Note: API is accessible only on your home network (helm:8675). No public exposure by default.

Access from Other Machines

Your agents running on other machines can access the API at http://helm:8675.

# From any machine on your network
curl http://helm:8675/health

If DNS isn't set up, use helm directly (should resolve via local network or hosts file).

MCP Server for Claude Desktop / OpenCode

The stack includes an MCP server that exposes your skills to Claude Desktop or OpenCode via the Model Context Protocol.

What's Running

• MCP Server: SSE mode on http://helm:3000
• Automatically proxies requests to the Skills API (http://api:8080 internally)
• Same Docker network, no extra configuration needed

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "skills": {
      "url": "http://helm:3000"
    }
  }
}

Restart Claude. You should see skills server connected with tools like search_skills, get_context, etc.

Configure OpenCode

See OPENCODE-MCP.md for detailed instructions. In short:

# Run the setup script from the agentic-templates repo:
cd ~/projects/agentic-templates
./setup-opencode-mcp.sh

# Or manually create ~/.config/opencode/mcp.json:
{
  "mcpServers": {
    "skills": {
      "url": "http://helm:3000"
    }
  }
}

Test MCP Connection

# Should hang (SSE stream) if connected
curl http://helm:3000/sse

# With API key if auth enabled:
curl -H "X-API-Key: your-key" http://helm:3000/sse

Project Setup (Per Project/Session)

For each new project or AI agent, you'll create an integration that uses the API.

Option A: Use the Template Repository (Recommended)

We maintain a template repo for quick starts.

1. Clone the Template

cd ~/projects  # or wherever you keep projects
git clone git.bouncypixel.com:helm/agentic-templates.git my-agent
cd my-agent

Or clone directly via SSH:

git clone ssh://git@helm:222/helm/agentic-templates.git my-agent

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Edit .env if needed:

API_URL=http://helm:8675
API_KEY=  # Only if auth enabled
PROJECT=/path/to/your/project  # Optional, for context scoping

3. Run Your Agent

# Using Docker Compose (recommended)
docker compose up -d

# Or run directly
pip install -r requirements.txt
python agent.py

The agent will automatically:

• Fetch relevant skills/conventions via RAG
• Store decisions in memory
• Compress conversation when it grows large

Option B: Manual Integration

If you want to integrate into an existing project:

1. Install the Python dependency:

pip install httpx

2. Copy the integration pattern from template/agent.py (the get_context, compress_messages, store_memory functions).

3. Add these calls to your agent's workflow:

   • Before each LLM call: context = await get_context(query, project)
   • Inject context into system prompt
   • After each response: await store_memory(project, key, content)
   • When conversation > 10 messages: compressed = await compress_messages(conversation)

See USAGE.md for detailed integration patterns.

Seeding Skills and Conventions

The API comes with a seed script that adds useful skills.

Run the Seed Script

cd /opt/ai-skills-api
python examples/seed-data.py

This adds:

• D&D campaign management skills
• Infrastructure/Docker skills
• Code review skills
• General best practices

Add Custom Skills

Via API:

curl -X POST http://helm:8675/skills \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-skill",
    "name": "My Custom Skill",
    "category": "custom",
    "content": "Specific instructions for your agent...",
    "tags": ["keyword1", "keyword2"]
  }'

Via MCP (Claude Desktop):

Use the skills/create_skill tool directly in Claude.

Via Python:

import httpx

resp = httpx.post(
    "http://helm:8675/skills",
    json={
        "id": "unique-skill-id",
        "name": "Skill Name",
        "category": "category",
        "content": "Full skill instructions...",
        "tags": ["tag1", "tag2"]
    }
)

Add Project Conventions

Conventions are project-specific (tied to a project path or identifier):

curl -X POST http://helm:8675/conventions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project Conventions",
    "project": "/home/user/myproject",
    "content": "Project-specific coding standards, workflows, etc."
  }'

Testing Your Setup

1. Test RAG Context

curl "http://helm:8675/context/rag?query=docker compose&project=test"

Should return JSON with skills, conventions, snippets arrays.

2. Test Compression

curl -X POST http://helm:8675/compress \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hi there! How can I help?"},
      {"role": "user", "content": "Tell me about Docker."},
      {"role": "assistant", "content": "Docker is a containerization platform..."}
    ]
  }'

Should return compressed messages and tokens_saved.

3. Test Memory

curl -X POST http://helm:8675/memory \
  -H "Content-Type: application/json" \
  -d '{
    "project": "test",
    "key": "decision-123",
    "content": "We decided to use FastAPI for this project"
  }'

curl "http://helm:8675/memory?project=test"

4. Test from Agent Template

cd ~/projects/my-agent
docker compose up -d
docker compose logs -f agent  # Watch the agent start and interact

Troubleshooting

Service Won't Start

# Check logs
docker compose logs ai-skills-api

# Common issues:
# - Port 8675 already in use: change port in docker-compose.yml
# - Permissions: ensure /opt/ai-skills-api is readable

Ollama Not Pulling Model

The entrypoint script auto-pulls phi3:mini if compression strategy is ollama. To force:

docker compose exec ai-skills-api ollama pull phi3:mini

Can't Connect from Other Machines

• Ensure helm is reachable on the network (ping helm)
• Check Docker network: docker network ls (should have ai-skills-api_default)
• API is bound to 0.0.0.0:8675 inside container - accessible from host and other containers

Auth Errors

• If you get 401, either disable auth in config.yaml or set API_KEY in your agent's .env
• Verify: curl -H "X-API-Key: your-key" http://helm:8675/skills

High RAG Latency (>10ms)

• First request after startup will be slower (warming cache)
• Subsequent queries should be <5ms
• If still slow, check embedding model load: docker compose logs ai-skills-api

Next Steps

• Read USAGE.md for detailed integration patterns and best practices
• Use the template repo for all new agent projects
• Add project-specific skills and conventions as you work
• Monitor logs for token savings