Quickstart

## Fastest way to get started

The quickest path is three steps: scaffold a plugin with the generator, start the MCP server, and let your AI assistant help you build it.

**1. Generate a scaffold**

```bash
cableknit generate
```

This creates a new `.sweater` bundle folder with all the required files — `plugin.json`, sample skills, automations, tools, and docs.

**2. Start the MCP server**

```bash
cableknit mcp
```

This starts a Model Context Protocol server over stdio that gives AI editors (Claude Code, Cursor, Windsurf, Copilot) deep knowledge of CableKnit schemas, validation, and platform capabilities.

**3. Build with your AI assistant**

Open a new session in your AI editor inside the generated bundle folder. The MCP server gives the assistant full context on CableKnit — ask it to help you design automations, write skills, configure triggers, and validate your bundle.

---

## Step-by-step walkthrough

This guide walks you through creating a minimal plugin, pushing it to your sandbox, and watching an automation run end to end.

## What you'll build

A simple vendor notification plugin that:
1. Receives an inbound email
2. Uses AI to assess the email content
3. Creates a Decision for a team member to review
4. Sends a confirmation notification when the decision is made

## Step 1: Set up your sandbox

When your publisher account is approved, CableKnit creates a sandbox company for you automatically. Log into the [Developer Portal](https://cableknit.ai/developer) and confirm your sandbox is ready under **Sandbox**.

## Step 2: Create your bundle

Create a folder called `vendor-notifications.sweater` with this structure:

```
vendor-notifications.sweater/
  plugin.json
  skills/
    vendor-intake.json
  automations/
    vendor-review.json
  docs/
    getting-started.md
```

## Step 3: Write plugin.json

```json
{
  "name": "Vendor Notifications",
  "slug": "vendor-notifications",
  "version": "1.0.0",
  "description": "Triage incoming vendor emails and route them for human review.",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "industry": "professional_services",
  "tier": "starter",
  "visibility": "private",
  "pricing": {
    "model": "monthly",
    "price_cents": 2900
  },
  "nav": {
    "show_in_nav": false
  }
}
```

<Note>
Set `visibility` to `private` while developing. Private plugins skip the review process and can be installed directly in your sandbox.
</Note>

## Step 4: Write your skill

```json
{
  "name": "Vendor Intake",
  "slug": "vendor-intake",
  "description": "Handles vendor-related inquiries and email triage.",
  "system_prompt": "You are a vendor relations assistant. You help operations teams manage incoming vendor communications, extract key information from emails, and route inquiries to the right people. Be concise and structured in your assessments.",
  "trigger_description": "Use this skill when a user asks about vendor communications, supplier emails, or vendor onboarding.",
  "action_type": "chat",
  "position": 1
}
```

## Step 5: Write your automation

```json
{
  "name": "Vendor Email Review",
  "slug": "vendor-email-review",
  "description": "Triages incoming vendor emails and routes them for human review.",
  "trigger_type": "inbound_email",
  "trigger_config": {},
  "priority": "normal",
  "case_reference_prefix": "VND",
  "position": 1,
  "workflow_definition": {
    "states": [
      {
        "name": "assess",
        "type": "initial",
        "entry_action": {
          "type": "ai_assess",
          "system_prompt": "You are reviewing an incoming vendor email. Extract the vendor name, the nature of their request (invoice, inquiry, complaint, onboarding), urgency level (low/normal/high), and a one-sentence summary. Respond as JSON.",
          "output_key": "assessment",
          "output_schema": {
            "vendor_name": "string",
            "request_type": "string",
            "urgency": "string",
            "summary": "string"
          }
        }
      },
      {
        "name": "request_review",
        "entry_action": {
          "type": "request_decision",
          "title": "Vendor Email: ",
          "description": "",
          "decision_options": [
            { "key": "respond", "label": "Respond to vendor" },
            { "key": "escalate", "label": "Escalate to manager" },
            { "key": "archive", "label": "Archive — no action needed" }
          ],
          "assigned_role": "manager",
          "priority": "normal",
          "expires_in": 48
        }
      },
      {
        "name": "confirmed",
        "entry_action": {
          "type": "notify",
          "channels": ["in_app"],
          "title": "Vendor email processed",
          "body": " — decision recorded."
        }
      },
      {
        "name": "completed",
        "type": "terminal",
        "terminal_status": "completed"
      }
    ],
    "transitions": [
      {
        "from_state": "assess",
        "to_state": "request_review",
        "priority": 1,
        "condition": { "type": "automatic" }
      },
      {
        "from_state": "request_review",
        "to_state": "confirmed",
        "priority": 1,
        "condition": { "type": "decision_outcome", "matches": "respond" }
      },
      {
        "from_state": "request_review",
        "to_state": "confirmed",
        "priority": 2,
        "condition": { "type": "decision_outcome", "matches": "escalate" }
      },
      {
        "from_state": "request_review",
        "to_state": "completed",
        "priority": 3,
        "condition": { "type": "fallback" }
      },
      {
        "from_state": "confirmed",
        "to_state": "completed",
        "priority": 1,
        "condition": { "type": "automatic" }
      }
    ]
  }
}
```

## Step 6: Write your doc

```markdown
---
title: Getting Started
slug: getting-started
category: setup
position: 1
---

# Getting Started with Vendor Notifications

This plugin automatically triages incoming vendor emails and routes them to your team for review.

## How it works

1. Send vendor emails to your CableKnit inbound address
2. The AI extracts key information and creates a review task
3. Your team reviews and decides the next action from the Decision Queue
```

## Step 7: Push to sandbox

Push your bundle to the sandbox using the CLI:

```bash
cableknit push
```

If there are validation errors, fix them and re-push. The CLI shows file-level error details.

## Step 8: Trigger a test run

In the Developer Portal under **Sandbox → Runs**, click **Trigger Run**. Select your automation and provide a test payload:

```json
{
  "from": "vendor@example.com",
  "subject": "Invoice #1234 - Please Review",
  "body": "Hi, we wanted to follow up on invoice #1234 submitted last week. Please let us know if you need anything."
}
```

## Step 9: Resolve the decision

Go to **Sandbox → Decisions**. You'll see the decision your automation created with the AI's assessment. Click **Resolve** and select an outcome.

Watch the run complete in **Sandbox → Runs**.

## Next steps

- Run `cableknit mcp install` to give your AI editor full CableKnit knowledge — see [AI Editor Integration](/cli#ai-editor-integration-mcp)
- Read [Skills](/skills) to understand how to write effective system prompts
- Read [Automations](/automations) for the full workflow definition reference
- Read [Artifacts](/artifacts) to learn how your automation can produce documents and reports

Fastest way to get started

The quickest path is three steps: scaffold a plugin with the generator, start the MCP server, and let your AI assistant help you build it.

1. Generate a scaffold

cableknit generate

This creates a new .sweater bundle folder with all the required files — plugin.json, sample skills, automations, tools, and docs.

2. Start the MCP server

cableknit mcp

This starts a Model Context Protocol server over stdio that gives AI editors (Claude Code, Cursor, Windsurf, Copilot) deep knowledge of CableKnit schemas, validation, and platform capabilities.

3. Build with your AI assistant

Step-by-step walkthrough

This guide walks you through creating a minimal plugin, pushing it to your sandbox, and watching an automation run end to end.

What you’ll build

A simple vendor notification plugin that:

Receives an inbound email
Uses AI to assess the email content
Creates a Decision for a team member to review
Sends a confirmation notification when the decision is made

Step 1: Set up your sandbox

When your publisher account is approved, CableKnit creates a sandbox company for you automatically. Log into the Developer Portal and confirm your sandbox is ready under Sandbox.

Step 2: Create your bundle

Create a folder called vendor-notifications.sweater with this structure:

vendor-notifications.sweater/
  plugin.json
  skills/
    vendor-intake.json
  automations/
    vendor-review.json
  docs/
    getting-started.md

Step 3: Write plugin.json

{
  "name": "Vendor Notifications",
  "slug": "vendor-notifications",
  "version": "1.0.0",
  "description": "Triage incoming vendor emails and route them for human review.",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "industry": "professional_services",
  "tier": "starter",
  "visibility": "private",
  "pricing": {
    "model": "monthly",
    "price_cents": 2900
  },
  "nav": {
    "show_in_nav": false
  }
}

Set `visibility` to `private` while developing. Private plugins skip the review process and can be installed directly in your sandbox.

Step 4: Write your skill

{
  "name": "Vendor Intake",
  "slug": "vendor-intake",
  "description": "Handles vendor-related inquiries and email triage.",
  "system_prompt": "You are a vendor relations assistant. You help operations teams manage incoming vendor communications, extract key information from emails, and route inquiries to the right people. Be concise and structured in your assessments.",
  "trigger_description": "Use this skill when a user asks about vendor communications, supplier emails, or vendor onboarding.",
  "action_type": "chat",
  "position": 1
}

Step 5: Write your automation

{
  "name": "Vendor Email Review",
  "slug": "vendor-email-review",
  "description": "Triages incoming vendor emails and routes them for human review.",
  "trigger_type": "inbound_email",
  "trigger_config": {},
  "priority": "normal",
  "case_reference_prefix": "VND",
  "position": 1,
  "workflow_definition": {
    "states": [
      {
        "name": "assess",
        "type": "initial",
        "entry_action": {
          "type": "ai_assess",
          "system_prompt": "You are reviewing an incoming vendor email. Extract the vendor name, the nature of their request (invoice, inquiry, complaint, onboarding), urgency level (low/normal/high), and a one-sentence summary. Respond as JSON.",
          "output_key": "assessment",
          "output_schema": {
            "vendor_name": "string",
            "request_type": "string",
            "urgency": "string",
            "summary": "string"
          }
        }
      },
      {
        "name": "request_review",
        "entry_action": {
          "type": "request_decision",
          "title": "Vendor Email: ",
          "description": "",
          "decision_options": [
            { "key": "respond", "label": "Respond to vendor" },
            { "key": "escalate", "label": "Escalate to manager" },
            { "key": "archive", "label": "Archive — no action needed" }
          ],
          "assigned_role": "manager",
          "priority": "normal",
          "expires_in": 48
        }
      },
      {
        "name": "confirmed",
        "entry_action": {
          "type": "notify",
          "channels": ["in_app"],
          "title": "Vendor email processed",
          "body": " — decision recorded."
        }
      },
      {
        "name": "completed",
        "type": "terminal",
        "terminal_status": "completed"
      }
    ],
    "transitions": [
      {
        "from_state": "assess",
        "to_state": "request_review",
        "priority": 1,
        "condition": { "type": "automatic" }
      },
      {
        "from_state": "request_review",
        "to_state": "confirmed",
        "priority": 1,
        "condition": { "type": "decision_outcome", "matches": "respond" }
      },
      {
        "from_state": "request_review",
        "to_state": "confirmed",
        "priority": 2,
        "condition": { "type": "decision_outcome", "matches": "escalate" }
      },
      {
        "from_state": "request_review",
        "to_state": "completed",
        "priority": 3,
        "condition": { "type": "fallback" }
      },
      {
        "from_state": "confirmed",
        "to_state": "completed",
        "priority": 1,
        "condition": { "type": "automatic" }
      }
    ]
  }
}

Step 6: Write your doc

---
title: Getting Started
slug: getting-started
category: setup
position: 1
---

# Getting Started with Vendor Notifications

This plugin automatically triages incoming vendor emails and routes them to your team for review.

## How it works

1. Send vendor emails to your CableKnit inbound address
2. The AI extracts key information and creates a review task
3. Your team reviews and decides the next action from the Decision Queue

Step 7: Push to sandbox

Push your bundle to the sandbox using the CLI:

cableknit push

If there are validation errors, fix them and re-push. The CLI shows file-level error details.

Step 8: Trigger a test run

In the Developer Portal under Sandbox → Runs, click Trigger Run. Select your automation and provide a test payload:

{
  "from": "vendor@example.com",
  "subject": "Invoice #1234 - Please Review",
  "body": "Hi, we wanted to follow up on invoice #1234 submitted last week. Please let us know if you need anything."
}

Step 9: Resolve the decision

Go to Sandbox → Decisions. You’ll see the decision your automation created with the AI’s assessment. Click Resolve and select an outcome.

Watch the run complete in Sandbox → Runs.

Next steps

Run cableknit mcp install to give your AI editor full CableKnit knowledge — see AI Editor Integration
Read Skills to understand how to write effective system prompts
Read Automations for the full workflow definition reference
Read Artifacts to learn how your automation can produce documents and reports