Recipes & Skills

Skillett uses a cooking metaphor to describe its integration model. There are two layers: recipes (templates) and skills (agent interfaces).

Recipes

A recipe is a pre-built integration template that defines how to connect to an external service. Each recipe specifies:

• Authentication type — OAuth 2.0, API key, Basic Auth, or custom token
• Available endpoints — What actions are available and their parameter schemas
• Required scopes — What permissions are needed from the external service
• Default configuration — Sensible defaults for common use cases

Recipes are shared across the platform. Think of them as the “package” — they define what’s possible with a service.

Example: GitHub recipe

The GitHub recipe defines 55+ endpoints across 6 categories (issues, pull requests, repositories, actions, search, users), uses OAuth 2.0 authentication, and requires scopes like repo, read:user, and workflow.

Cooking (configuring an integration)

“Cooking” a recipe means connecting it to your account:

1. Browse available recipes (on the dashboard or via skillett skills)
2. Run skillett connect github to start the OAuth flow
3. Authorize the requested scopes on GitHub’s consent screen
4. Skillett stores your OAuth tokens (encrypted) and activates the integration

You can re-cook an integration at any time — this updates scopes, refreshes tokens, or reconfigures parameters.

Skills

A skill is a structured agent interface that wraps one or more proxy endpoint calls into a named action. Skills are what agents actually interact with.

Each skill has:

• Name — e.g., create_issue, list_pull, send_email
• Method — HTTP method (GET, POST, PATCH, PUT, DELETE)
• Parameters — Typed, validated inputs with descriptions
• Description — What the skill does (human and agent-readable)
• Example — CLI usage example
• Error codes — What can go wrong and how to fix it

Skill discovery

Skills are discoverable at three levels:

1. skillett skills — List all integrations
2. skillett skills github — List all endpoints for GitHub
3. skillett skills github create_issue — Full documentation for one endpoint

This progressive disclosure lets agents drill down to exactly what they need.

Skill files

Skills are documented as markdown files with YAML frontmatter:

---
name: create_issue
method: POST
path: /repos/{owner}/{repo}/issues
param_mapping:
  repo: owner/repo → {owner}, {repo}
---

# Create Issue

Create an issue in a GitHub repository.

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| repo | string | Yes | Repository in owner/repo format |
| title | string | Yes | Issue title |
| body | string | No | Issue body (markdown) |

## Errors

| Code | Cause | Fix |
|---|---|---|
| 404 | Not Found | Verify repository exists |

The frontmatter is the single source of truth — it defines the HTTP mapping, parameter transformations, and metadata that the proxy layer uses to forward requests.

Lifecycle

Generate → Curate → Seed → Serve

1. Generate — OpenAPI spec → skill-gen tool → skill markdown files
2. Curate — Review and edit generated docs for accuracy
3. Seed — skillett seed <folder> → database (routes + skill_files) + storage
4. Serve — GET /v1/skills/:integration/:endpoint → CLI → Agent