Claude Agent Skill

Overview

The GaiterGuard agent skill is a pre-packaged integration guide that teaches Claude how to interact with the gateway. It includes:

Complete protocol documentation (POST /proxy, polling, execute)
Polling script templates (Python and bash)
Request flow patterns and error handling
Risk scoring reference

With this skill installed, Claude can autonomously handle the full approval workflow without manual prompting.

Installation

Locate the skill directory

The skill is bundled in the GaiterGuard repository:

ls ~/workspace/source/skill/gaiterguard-gateway/

Contents:

skill/gaiterguard-gateway/
├── SKILL.md              # Main skill instructions
└── references/
    └── polling-script.md  # Polling script templates

Copy to Claude skills directory

Install the skill globally for Claude:

mkdir -p ~/.claude/skills
cp -r ~/workspace/source/skill/gaiterguard-gateway ~/.claude/skills/

If you’re using a different AI framework, adapt the installation path to your platform’s skill/tool directory.

Verify installation

The skill should now be available in Claude’s skill registry. You can verify by asking:

Do you have the gaiterguard-gateway skill installed?

Skill Contents

SKILL.md

The main skill file (~/workspace/source/skill/gaiterguard-gateway/SKILL.md:1) contains:

Environment variables required (GATEWAY_URL, AGENT_KEY)
Authentication header format
Workflow overview (submit → poll → execute)
Step-by-step protocol:
- POST /proxy request format
- 428 response handling
- GET /status polling loop
- POST /proxy/execute execution
Error code reference (401, 403, 404, 409, 410, 428, 502, 504)
Intent writing guidelines (good vs. bad examples)
Risk score baseline by HTTP method

Polling Script Template

The skill includes a complete polling script template (~/workspace/source/skill/gaiterguard-gateway/references/polling-script.md:1) with:

#!/usr/bin/env python3
import time, json, requests

GATEWAY_URL = "PLACEHOLDER_GATEWAY_URL"
AGENT_KEY   = "PLACEHOLDER_AGENT_KEY"
ACTION_ID   = "PLACEHOLDER_ACTION_ID"

ORIGINAL_REQUEST = {
    "targetUrl":      "PLACEHOLDER_TARGET_URL",
    "method":         "PLACEHOLDER_METHOD",
    "intent":         "PLACEHOLDER_INTENT",
    "riskScore":      0.0,
    "riskExplanation": "PLACEHOLDER_RISK_EXPLANATION",
}

POLL_INTERVAL = 8
MAX_POLLS     = 75

def poll():
    for attempt in range(MAX_POLLS):
        status_code, body = request("GET", f"/status/{ACTION_ID}")
        state = body.get("status")

        if state == "PENDING":
            time.sleep(POLL_INTERVAL)
            continue

        if state == "APPROVED":
            exec_code, exec_body = request("POST", f"/proxy/execute/{ACTION_ID}")
            return {
                "outcome": "executed",
                "status": exec_code,
                "body": exec_body,
                "original_request": ORIGINAL_REQUEST,
            }

        if state == "DENIED":
            return {"outcome": "denied", "original_request": ORIGINAL_REQUEST}

        if state == "EXPIRED":
            return {"outcome": "expired", "original_request": ORIGINAL_REQUEST}

        # ... (EXECUTED case)

    return {"outcome": "timeout", "original_request": ORIGINAL_REQUEST}

#!/usr/bin/env bash
GATEWAY_URL="PLACEHOLDER_GATEWAY_URL"
AGENT_KEY="PLACEHOLDER_AGENT_KEY"
ACTION_ID="PLACEHOLDER_ACTION_ID"

ORIGINAL_TARGET_URL="PLACEHOLDER_TARGET_URL"
ORIGINAL_METHOD="PLACEHOLDER_METHOD"
ORIGINAL_INTENT="PLACEHOLDER_INTENT"

poll() {
  while true; do
    RESPONSE=$(curl -s -H "Agent-Key: $AGENT_KEY" \
      "$GATEWAY_URL/status/$ACTION_ID")
    STATE=$(echo "$RESPONSE" | jq -r '.status')

    case "$STATE" in
      PENDING)  echo "Pending..."; sleep 8 ;;
      APPROVED)
        echo "Approved — executing"
        RESULT=$(curl -s -X POST -H "Agent-Key: $AGENT_KEY" \
          "$GATEWAY_URL/proxy/execute/$ACTION_ID")
        echo "$RESULT"
        exit 0
        ;;
      DENIED)   echo "Denied"; exit 1 ;;
      EXPIRED)  echo "Expired"; exit 1 ;;
      EXECUTED) echo "Already executed"; exit 0 ;;
    esac
  done
}

poll

Key features:

Polls every 8 seconds for up to 75 attempts (~10 minutes)
Stores original request context (URL, method, intent, risk score)
Handles all status states (PENDING, APPROVED, DENIED, EXPIRED, EXECUTED)
Re-invokes agent with full context after execution

Using the Skill

Trigger Phrases

The skill activates when Claude detects:

“call an API through the gateway”
“proxy a request via GaiterGuard”
“use Agent-Key”
“POST /proxy”
Approval polling workflows
Any task requiring external API calls through the gateway

Example Usage

Autonomous workflow
Manual invocation
Error recovery

User:

Charge customer cus_123 for $50 using the Stripe API through the gateway.
Use Agent-Key: agt_a1b2c3...
Gateway URL: http://localhost:3000

Claude (with skill):

Constructs POST /proxy request with proper headers
Includes clear intent: “Charge customer $50.00 for service upgrade”
Generates unique Idempotency-Key
Submits request
If 428 returned:
- Writes polling script with placeholders filled in
- Executes script
- Waits for approval
- Executes approved request
- Returns result with original request context

User:

I got a 428 response from the gateway with action_id: 550e8400-...
The original request was DELETE /users/123.
Help me poll for approval.

Claude (with skill):

Recognizes 428 scenario
Retrieves polling script template from skill references
Fills in placeholders (gateway URL, agent key, action ID, original request)
Writes and executes polling script
Monitors status until terminal state
If approved, executes via POST /proxy/execute/:actionId
Returns full result with original request context

User:

The gateway returned 403 Forbidden when I tried to call the Stripe API.

Claude (with skill):

Consults error code reference in skill
Identifies 403 as “Agent not scoped to service”

Provides actionable guidance:

The 403 error means your agent is not scoped to the Stripe service.

To fix:
Log into the GaiterGuard dashboard
Navigate to Agents → [Your Agent]
Click Edit → Service Scope
Grant access to the Stripe service
Retry your request

Skill Metadata

From ~/workspace/source/skill/gaiterguard-gateway/SKILL.md:1-10:

---
name: gaiterguard-gateway
description: >
  Complete integration guide for AI agents making HTTP requests through the GaiterGuard API gateway.
  Use this skill whenever an agent needs to proxy requests to external/registered services via GaiterGuard.
  Covers Agent-Key authentication, constructing POST /proxy requests, handling risk-blocked 428 responses
  with a procedural polling loop, executing approved requests, and all response shapes.
  Trigger on: "call an API through the gateway", "proxy a request via GaiterGuard", "use Agent-Key",
  "POST /proxy", approval polling workflows, or any task requiring external API calls through the gateway.
---

Environment Variables

The skill requires two environment variables to be provided by the user:

string

required

Base URL of the GaiterGuard gateway instanceExample:

export GATEWAY_URL=http://localhost:3000

string

required

The agent’s API key (obtained from dashboard)Example:

export AGENT_KEY=agt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

Claude will prompt for these values if not set when the skill is triggered.

Benefits

Zero manual prompting

Claude automatically constructs proper requests, headers, and polling loops without needing step-by-step instructions each session.

Error handling

Built-in reference for all error codes (401, 403, 404, 409, 410, 428, 502, 504) with actionable recovery steps.

Context preservation

Polling scripts store and pass back original request context (URL, method, intent, risk score) so the agent can resume tasks correctly.

Copy-paste templates

Ready-to-run polling scripts in Python and bash with all placeholders filled in dynamically.

Customizing the Skill

You can modify the skill for your use case:

Edit SKILL.md

Update ~/.claude/skills/gaiterguard-gateway/SKILL.md to:

Change default polling interval (line 38: POLL_INTERVAL = 8)
Adjust max polls (line 39: MAX_POLLS = 75)
Add custom error handling
Include organization-specific rules

Modify polling scripts

Edit references/polling-script.md to:

Use your preferred HTTP library
Change logging format
Add Slack/email notifications on approval
Customize agent re-invocation command

Reload skill

Claude automatically picks up changes on next invocation. No restart required.

Skill Reference

Full skill documentation: ~/workspace/source/skill/gaiterguard-gateway/SKILL.md:1 Polling templates: ~/workspace/source/skill/gaiterguard-gateway/references/polling-script.md:1

Get Started

Core Concepts

Guides

Overview

Installation

Skill Contents

SKILL.md

Polling Script Template

Using the Skill

Trigger Phrases

Example Usage

Skill Metadata

Environment Variables

Benefits

Zero manual prompting

Error handling

Context preservation

Copy-paste templates

Customizing the Skill

Skill Reference

Next Steps

Agent Integration

Configuration

​Overview

​Installation

​Skill Contents

​SKILL.md

​Polling Script Template

​Using the Skill

​Trigger Phrases

​Example Usage

​Skill Metadata

​Environment Variables

​Benefits

Zero manual prompting

Error handling

Context preservation

Copy-paste templates

​Customizing the Skill

​Skill Reference

​Next Steps

Agent Integration

Configuration

Overview

Installation

Skill Contents

SKILL.md

Polling Script Template

Using the Skill

Trigger Phrases

Example Usage

Skill Metadata

Environment Variables

Benefits

Customizing the Skill

Skill Reference

Next Steps