Toolkit Authoring Guide¶

This guide walks you through creating custom toolkits for your Contio-powered offering. Whether you're building meeting workflows for your own platform or enabling your customers to extend their experience, this guide covers the complete authoring process.

Two Distribution Models¶

Before you begin authoring, decide how your toolkit will be distributed:

Partner-Administered Toolkits¶

When you install a toolkit via the Partner Admin API (POST /v1/partner/admin/toolkits), you retain control over the entities. You can push updates, fix prompts, and add new templates—all changes propagate to your customers' workspaces automatically.

Use this model when:

• The toolkit is core to your product offering
• You need to maintain consistency across all customer workspaces
• You want to push updates without customer intervention

Customer-Administered Toolkits¶

When your customers import a toolkit via the Contio Settings UI, they own the resulting entities. They can customize prompts, add shortcuts, and modify next steps freely.

Use this model when:

• You're providing a starter kit that customers will tailor
• Your customers have unique meeting formats
• Customization is a key value proposition

See Ownership & Distribution for detailed governance implications.

Planning Your Toolkit¶

1. Define the Meeting Lifecycle¶

Start by mapping the meeting types your toolkit supports:

What meetings? → What happens during? → What happens after?

Example — Recruiting Interview Suite:

2. Identify Entity Types¶

Once you've mapped the lifecycle, identify which entities you need:

3. Sketch the Reference Graph¶

Entities reference each other. Before writing JSON, sketch the relationships:

Template: "Sales Discovery"
    ├── Next Step: "Meeting Summary"
    │       └── Action Button: "Email Summary"
    │       └── Action Button: "Copy to Clipboard"
    └── Next Step: "Follow-up Email Draft"
            └── Action Button: "Open Email Client"

Writing the Manifest¶

Manifest Structure¶

Every toolkit uses a wrapper containing provenance metadata and the manifest content:

{
  "name": "My Toolkit",
  "slug": "my-toolkit",
  "version": "1.0.0",
  "license": "LicenseRef-MyCompany",
  "license_url": "https://mycompany.com/toolkit-license",
  "manifest": {
    "schema_version": "1",
    "toolkit_prompt": "You are a helpful assistant for...",
    "templates": [...],
    "next_steps": [...],
    "action_buttons": [...],
    "shortcuts": [...],
    "canvas_templates": [...]
  }
}

Entity IDs and References¶

Use $id to declare entities and $ref to link them:

{
  "next_steps": [
    {
      "spec": {
        "$id": "ns-summary",
        "name": "Meeting Summary",
        "type": "ai",
        "ai_prompt": "Summarize this meeting..."
      },
      "action_buttons": [
        { "action_button": { "$ref": "ab-email" }, "sort_order": 1 }
      ]
    }
  ],
  "action_buttons": [
    {
      "spec": {
        "$id": "ab-email",
        "name": "Email Summary",
        "delivery_mechanism": "email",
        "content_format": "rich_text"
      }
    }
  ]
}

When installed, these local identifiers resolve to database UUIDs.

Entity Deep Dive¶

Meeting Templates¶

Templates define the structure users see when creating meetings:

{
  "templates": [
    {
      "spec": {
        "$id": "standup",
        "name": "Daily Standup",
        "title": "Daily Standup",
        "slug": "daily-standup",
        "description": "15-minute team sync",
        "meeting_duration_seconds": 900,
        "agenda_items": [
          {
            "item_type": "DISCUSSION",
            "title": "Yesterday's Progress",
            "time_allocation_minutes": 5,
            "sequence": "1"
          },
          {
            "item_type": "DISCUSSION",
            "title": "Today's Plan",
            "time_allocation_minutes": 5,
            "sequence": "2"
          },
          {
            "item_type": "DISCUSSION",
            "title": "Blockers",
            "time_allocation_minutes": 5,
            "sequence": "3"
          }
        ]
      },
      "next_steps": [
        { "next_step": { "$ref": "ns-summary" }, "sort_order": 1, "autopilot": true }
      ]
    }
  ]
}

Key fields:

See Manifest Format Reference for the complete field list.

Always set title. name labels the template in the picker; title names the meeting. If you omit title, applying the template never sets a meeting title — an untitled meeting stays untitled, and a meeting that already has a title keeps it. The template's name is not used as a fallback there. This is the single most common toolkit authoring mistake.

Next Steps (AI Prompts)¶

Next steps generate content from meeting transcripts:

{
  "next_steps": [
    {
      "spec": {
        "$id": "ns-summary",
        "name": "Meeting Summary",
        "type": "ai",
        "ai_prompt": "Create a concise summary including:\n\n**Key Discussion Points**\n- ...\n\n**Decisions Made**\n- ...\n\n**Action Items**\n| Owner | Task | Due Date |\n|-------|------|----------|",
        "icon_name": "scroll-text",
        "color": "#1E40AF"
      },
      "action_buttons": [
        { "action_button": { "$ref": "ab-email" }, "sort_order": 1 },
        { "action_button": { "$ref": "ab-copy" }, "sort_order": 2 }
      ]
    }
  ]
}

Prompt writing tips:

• Be specific about output format (tables, bullet lists, sections)
• State what to include and what to exclude
• Use domain-specific terminology your users expect
• Keep prompts under 2,000 characters

Shortcuts¶

Shortcuts provide quick in-meeting actions:

{
  "shortcuts": [
    {
      "spec": {
        "$id": "sc-blocker",
        "name": "🚧 Blocker",
        "description": "Flag a blocker that needs attention",
        "icon": "bolt",
        "color": "#DC2626",
        "prompt": "**🚧 BLOCKER**\n**Issue**: [describe the blocker]\n**Owner**: [who is blocked]\n**Needed**: [what would unblock this]",
        "surfaces": [
          { "surface": "MEETING_RUN", "position": 1 }
        ]
      }
    }
  ]
}

Surface options: HOME, MEETING_PREPARE, MEETING_RUN, MEETING_REVIEW, CANVAS

Testing Your Toolkit¶

1. Validate JSON Syntax¶

cat my-toolkit.json | python3 -m json.tool > /dev/null && echo "Valid JSON"

2. Test in a Development Workspace¶

For partner-administered toolkits:

// Create the toolkit
const toolkit = await sdk.admin.createToolkit(manifest);

// Install on a test workspace
await sdk.admin.installToolkit(toolkit.id, {
  workspace_id: 'ws_test123'
});

For customer-administered toolkits:

1. Go to Settings → Toolkits in a test workspace
2. Click Import Toolkit
3. Upload your JSON file
4. Verify entities appear correctly

3. Run Through Meeting Lifecycle¶

1. Create a meeting using your template
2. Test all shortcuts during the meeting
3. Complete the meeting and verify next steps execute
4. Confirm action buttons deliver content correctly

Best Practices¶

Naming Conventions¶

Versioning Strategy¶

Use semantic versioning for your toolkit:

Customization-Friendly Design¶

If you expect customers to customize your toolkit:

• Use clear, descriptive $id values
• Add usage_guidance fields explaining when to use each entity
• Include comments in prompts (via markdown) explaining customization points
• Provide a customization guide alongside your toolkit

Production Examples¶

Study these complete, production-ready toolkits for inspiration:

Each example includes a downloadable JSON manifest and detailed documentation.

See Also¶

• Manifest Format Reference — Complete field documentation
• Reference Patterns — Advanced $ref and $id patterns
• Entity Lifecycle — Runtime usage via Partner API
• Ownership & Distribution — Governance and distribution strategies
• JSON Schema — Machine-readable schema