How Skillett Works

Skillett is a unified skills layer that sits between AI agents and external services. Instead of agents calling APIs directly, they use the Skillett CLI — and Skillett handles authentication, credential management, and request proxying.

Architecture

Agent (Claude, Cursor, Windsurf)
  → skillett CLI
    → Skillett API (Fastify)
      → Integration Proxy Layer
        → External APIs (GitHub, Gmail, Google Calendar, etc.)

The agent never touches OAuth tokens or API credentials. Everything flows through the CLI, which talks to the Skillett API, which proxies to upstream services.

Key design decisions

CLI-first, not API-first

Agents interact through the CLI (skillett run, skillett skills), not raw HTTP. This keeps the interface simple — agents call shell commands and get JSON back. The CLI wraps the REST API, so direct HTTP access is available for advanced use cases.

Proxy model

Agents never call external APIs directly. All requests go through Skillett’s proxy layer, which:

1. Validates the API key
2. Loads the user’s OAuth credentials (encrypted, stored server-side)
3. Injects the authentication token into the upstream request
4. Forwards the request to the external service
5. Returns the response as structured JSON
6. Automatically refreshes expired tokens on 401 responses

Skills are documentation, not code

Skills are structured markdown files that describe what an endpoint does, what parameters it accepts, and what it returns. They’re not code — they’re documentation that agents can read to understand available capabilities.

Device authorization for CLI login

The CLI uses RFC 8628 device authorization to authenticate. This works in any terminal environment — the user opens a browser, enters a code, and the CLI picks up the authorization automatically.

Data flow for a skill execution

When an agent runs skillett run github create_issue --repo acme/app --title "Bug":

1. CLI parses flags into JSON params
2. CLI sends POST /v1/github/create_issue with {"params": {"repo": "acme/app", "title": "Bug"}}
3. API validates the Bearer token (API key)
4. API checks the user has GitHub connected
5. API checks plan limits (daily API calls)
6. Proxy loads encrypted OAuth credentials from the database
7. Proxy maps params to GitHub’s API format
8. Proxy sends POST https://api.github.com/repos/acme/app/issues with the OAuth token
9. Proxy returns GitHub’s response to the CLI
10. CLI outputs JSON to stdout

Tip

If the OAuth token has expired, the proxy automatically refreshes it and retries — the agent never sees the token management.

Database overview

Table	Purpose
profiles	User accounts
api_keys	API credentials (hashed, never stored in plaintext)
connections	Integration connections per user
credentials	OAuth tokens (encrypted at rest)
integrations	Integration definitions and metadata
routes	API endpoint definitions
skill_calls	Execution audit log
skill_files	Skill documentation content
device_codes	Pending device authorization codes