kesslerio / attio-skill-generator

Skill Content

---
name: attio-skill-generator
description: Generate use-case-specific Attio workflow skills from templates. Use when creating new skills for lead qualification, deal management, customer onboarding, or custom Attio workflows.
license: Apache-2.0 (see LICENSE.txt for attribution)
---

# Attio Skill Generator

A meta-skill that generates customized Attio workflow skills tailored to your workspace.

## When to Use This Skill

Use this skill when you want to:

- Create a **lead qualification** skill for your workspace
- Generate a **deal management** workflow skill
- Build a **customer onboarding** skill
- Create **custom Attio workflow** skills

## Available Use Cases

| Use Case              | Primary Object | Related Objects   | Description                          |
| --------------------- | -------------- | ----------------- | ------------------------------------ |
| `lead-qualification`  | companies      | people            | Qualify and score inbound leads      |
| `deal-management`     | deals          | companies, people | Manage deals through pipeline stages |
| `customer-onboarding` | companies      | people, deals     | Structured onboarding workflows      |

## Generation Process

### Step 1: Gather Workspace Schema (Targeted)

**You (Claude) must discover the workspace schema** for the **specific use-case**. The Python scripts are sandboxed and cannot access APIs or MCP tools.

**IMPORTANT: Gather data for the PRIMARY OBJECT only.** Do not gather full schemas for all objects.

**Determine what to gather based on use-case:**

| Use Case              | Gather Attributes For | Gather Lists?         |
| --------------------- | --------------------- | --------------------- |
| `lead-qualification`  | companies             | NO (unless requested) |
| `deal-management`     | deals                 | NO (unless requested) |
| `customer-onboarding` | companies             | NO (unless requested) |

**FIRST: Check for attio-workspace-schema skill**

Before using MCP tools, check if the `attio-workspace-schema` skill is installed by looking for its resource files.

**Option A: Use attio-workspace-schema skill (PREFERRED - faster, no API calls)**

If `attio-workspace-schema` skill exists:

1. Read ONLY the primary object's resource file:
   - `deal-management` → read `resources/deals-attributes.md`
   - `lead-qualification` → read `resources/companies-attributes.md`
   - `customer-onboarding` → read `resources/companies-attributes.md`
2. Extract attributes and select/status options for that object
3. Build JSON schema structure

**Option B: Query MCP tools (FALLBACK - only if no schema skill)**

If `attio-workspace-schema` skill is NOT available:

```
1. Call records_discover_attributes for the PRIMARY OBJECT ONLY
   - deal-management → records_discover_attributes for "deals"
   - lead-qualification → records_discover_attributes for "companies"
   - customer-onboarding → records_discover_attributes for "companies"

2. For select/status fields on the primary object, call records_get_attribute_options
```

**Do NOT call get-lists** unless the user specifically asks for list-related functionality. Lists are organizational containers, not essential to core workflows like deal management or lead qualification.

**Do NOT gather:**

- Full attribute schemas for secondary/related objects (companies, people for deal-management)
- Lists (unless user explicitly requests list functionality)

**Note on related objects:** Deal management involves linked companies and people, but these relationships are handled through record-reference fields on the deals object. You don't need full attribute lists for related objects.

### Step 2: Build Schema JSON

Structure the discovered data as JSON for the generator. **This structure is CRITICAL for correct output.**

**⚠️ REQUIRED FIELDS for each attribute:**

- `api_slug` - The API field name (required)
- `type` - Field type: text, status, select, number, date, etc. (required)
- `is_required` - Boolean, true if field is required (optional, defaults to false)
- `is_multiselect` - Boolean, true if field accepts multiple values (optional, defaults to false)
- `options` - Array of option objects for status/select fields (REQUIRED for status/select types!)

**⚠️ OPTIONS ARE CRITICAL:** For `status` and `select` type fields, you MUST include the `options` array with the actual option titles from the workspace. Without this, the generated skill won't show pipeline stages or dropdown values!

```json
{
  "objects": {
    "deals": {
      "display_name": "Deals",
      "attributes": [
        {
          "api_slug": "name",
          "display_name": "Deal Name",
          "type": "text",
          "is_required": true,
          "is_multiselect": false
        },
        {
          "api_slug": "stage",
          "display_name": "Deal Stage",
          "type": "status",
          "is_required": true,
          "is_multiselect": false,
          "options": [
            { "title": "MQL" },
            { "title": "Demo Request" },
            { "title": "Discovery Call" },
            { "title": "Demo Booked" },
            { "title": "Negotiations" },
            { "title": "Won 🎉" },
            { "title": "Lost" }
          ]
        },
        {
          "api_slug": "primary_interest",
          "display_name": "Primary Interest",
          "type": "select",
          "is_multiselect": false,
          "options": [
            { "title": "GLP-1 / medical weight loss" },
            { "title": "Body contouring / aesthetics" },
            { "title": "Replacing existing device" }
          ]
        },
        {
          "api_slug": "lost_reason",
          "display_name": "Lost Reason",
          "type": "select",
          "is_multiselect": true,
          "options": [
            { "title": "Pricing/Cost" },
            { "title": "Competitor" },
            { "title": "Timing Not Right" }
          ]
        },
        {
          "api_slug": "associated_people",
          "display_name": "Associated People",
          "type": "record-reference",
          "is_multiselect": true
        },
        {
          "api_slug": "associated_company",
          "display_name": "Company",
          "type": "record-reference",
          "is_multiselect": false
        }
      ]
    }
  },
  "lists": []
}
```

**Key points:**

- `lists` array is empty by default. Only populate if user requests list functionality.
- For `status`/`select` fields, copy the EXACT option titles from the workspace schema
- Set `is_multiselect: true` for fields that accept multiple values (check the Multi column in schema)

### Step 3: Run the Generator

Execute the generator script with the workspace schema.

**Recommended: Use file-based input** (avoids shell escaping issues with large JSON):

```bash
# Save schema to file first
echo '<JSON from Step 2>' > workspace-schema.json

# Run generator with file input
python scripts/generator.py \
  --use-case lead-qualification \
  --name acme-lead-qualification \
  --workspace-schema-file workspace-schema.json \
  --output ./generated-skills
```

**Alternative: Inline JSON** (only for small schemas):

```bash
python scripts/generator.py \
  --use-case lead-qualification \
  --name acme-lead-qualification \
  --workspace-schema '{"objects": {...}}' \
  --output ./generated-skills
```

**Parameters:**

- `--use-case`: One of `lead-qualification`, `deal-management`, `customer-onboarding`
- `--name`: Skill name (hyphen-case, max 64 chars)
- `--workspace-schema-file`: Path to JSON file with workspace data (recommended)
- `--workspace-schema`: JSON string with workspace data (alternative for small schemas)
- `--output`: Output directory (default: `./generated-skills`)

### Step 4: Preview Generated Skill

Show the user the generated SKILL.md content for review:

```bash
cat ./generated-skills/acme-lead-qualification/SKILL.md
```

Allow the user to request modifications before packaging.

### Step 5: Validate and Package

Validate the generated skill:

```bash
python scripts/quick_validate.py ./generated-skills/acme-lead-qualification
```

Package as a .skill file:

```bash
python scripts/package_skill.py ./generated-skills/acme-lead-qualification
```

### Step 6: Return to User

Provide the user with:

1. Preview of generated skill contents
2. Path to the `.skill` ZIP file
3. Instructions for importing into Claude

## Scripts Reference

| Script              | Purpose                          | Input                  |
| ------------------- | -------------------------------- | ---------------------- |
| `generator.py`      | Generate skill from templates    | JSON schema + use-case |
| `init_skill.py`     | Initialize empty skill structure | Skill name             |
| `package_skill.py`  | Validate and create ZIP          | Skill directory path   |
| `quick_validate.py` | Validate SKILL.md frontmatter    | Skill directory path   |

## Example Interaction

**User:** "Use attio-skill-generator to create a Deal Management skill for my workspace"

**Claude:**

1. I'll generate a Deal Management skill. Let me check for attio-workspace-schema skill...
   - [If schema skill exists: reads `resources/deals-attributes.md`]
   - [If no schema skill: calls `records_discover_attributes` for **deals only**]
   - [Does NOT call `get-lists` - lists are not needed for deal management]
2. Building workspace schema JSON with deals attributes only...
3. Running generator:
   ```bash
   python scripts/generator.py --use-case deal-management --name my-deal-management --workspace-schema-file schema.json
   ```
4. Here's the generated skill preview:
   [Shows SKILL.md content with deal stages and attributes]
5. Does this look correct? I can modify it before packaging.
6. Packaging skill...
   ```bash
   python scripts/package_skill.py ./generated-skills/my-deal-management
   ```
7. Your skill is ready: `./my-deal-management.skill`

**Note:** The skill includes record-reference fields (associated_company, contacts) that link to companies and people, but without documenting those objects' full schemas. Lists are not included unless explicitly requested.

## Template Customization

Templates are in `resources/templates/`. You can customize:

- `SKILL.template.md` - Main skill metadata and structure
- `workflows.template.md` - Workflow step patterns
- `tool-reference.template.md` - MCP tool reference
- `examples.template.md` - Example interactions

Use-case configurations are in `resources/use-cases/`:

- `lead-qualification.yaml`
- `deal-management.yaml`
- `customer-onboarding.yaml`

## Dependencies

The generator requires these Python packages:

- `chevron` - Handlebars-compatible templating
- `pyyaml` - YAML parsing

Install if needed: `pip install chevron pyyaml`

## Validation Checklist

Before packaging, verify the generated skill:

- [ ] All object slugs exist in the user's workspace
- [ ] All list IDs are valid UUIDs from the workspace
- [ ] Attribute slugs match the workspace schema
- [ ] Select/status options use exact titles from workspace
- [ ] No hardcoded values from other workspaces
- [ ] Skill name is hyphen-case, max 64 characters
- [ ] Description is max 1024 characters

See [resources/validation-checklist.md](resources/validation-checklist.md) for detailed checklist.

## Attribution

This skill extends [anthropics/skills/skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator).
Licensed under Apache License 2.0. See LICENSE.txt for full terms.

**Modifications from original:**

- Added Attio workspace schema integration
- Added use-case specific template rendering
- Added preview system for generated skills
- Adapted for MCP tool workflow