beam-ai-team/create-master-skill

---

[!] CRITICAL EXECUTION REQUIREMENTS [!]

WORKFLOW: Build FIRST, Research SECOND, Build THIRD

MANDATORY STEPS (DO NOT SKIP):

1. [OK] Create TodoWrite with ALL phases
2. [OK] Ask integration name (e.g., "airtable", "slack", "github")
3. [OK] RUN plan-project skill to create planning build
4. [OK] PHASE 1: Web Research - comprehensive API/integration research
5. [OK] PHASE 2: Architecture Design - define master skill structure
6. [OK] PHASE 3: Build - create master skill from templates
7. [OK] PHASE 4: Validate - test and document

ANTI-PATTERN (DO NOT DO THIS): [ERROR] Skip project creation [ERROR] Start building without research [ERROR] Create master skill without understanding the integration [ERROR] Copy from notion-master without adapting [ERROR] Skip validation phase

CORRECT PATTERN (DO THIS): [OK] Ask integration → Create build → Research → Design → Build → Validate

Create Master Skill

Build production-ready master skills (shared resource libraries) for any integration.

Safety Contract

Before creating a planning build, writing master-skill files, copying templates, or running validation scripts, show the integration name, target project path, target skill path, files to create or edit, research sources, and overwrite risk. Require explicit user approval in the current turn before writing files or publishing/sharing the skill. Research, architecture planning, and in-chat design review do not require approval.

Purpose

Master skills solve the duplication problem: When 3+ skills share common content (setup, API docs, error handling), extract it into a master skill that all can reference.

Key Insight from notion-master:

• 3 Notion skills had 950 lines of duplicated content
• After extraction: 60% context reduction (950 → 370 lines)
• Single source of truth for setup, API, errors, schemas

---

Quick Start

User says: "create master skill for Airtable"

AI does:

1. Creates planning build: {ID}-airtable-master-skill
2. Runs comprehensive web research on Airtable API
3. Designs architecture based on research
4. Builds master skill from templates
5. Validates and documents

---

Workflow

Phase 0: Initiation

[*] CREATE MASTER SKILL

What integration do you want to create a master skill for?
Examples: airtable, slack, github, linear, google-sheets, stripe

Integration name: ___________

After user provides name:

1. Validate name (lowercase, hyphenated)
2. Check if {integration}-master already exists
3. Create planning build using plan-project skill

---

Phase 1: Web Research (CRITICAL)

Purpose: Gather comprehensive information before building anything.

Run these searches:

## Research Tasks

1. **API Documentation**
   - Search: "{integration} API documentation official"
   - Capture: Base URLs, authentication, rate limits

2. **API Reference**
   - Search: "{integration} API endpoints reference"
   - Capture: Key endpoints, request/response formats

3. **Authentication Patterns**
   - Search: "{integration} API authentication OAuth API key"
   - Capture: Auth methods, token handling, refresh patterns

4. **Common Operations**
   - Search: "{integration} API CRUD operations examples"
   - Capture: Create, read, update, delete patterns

5. **Error Handling**
   - Search: "{integration} API error codes troubleshooting"
   - Capture: Error codes, messages, recovery patterns

6. **Rate Limits**
   - Search: "{integration} API rate limits throttling"
   - Capture: Limits, backoff strategies, best practices

7. **SDK/Libraries**
   - Search: "{integration} Python SDK library"
   - Capture: Official SDK, popular libraries, installation

8. **Best Practices**
   - Search: "{integration} API best practices integration"
   - Capture: Patterns, anti-patterns, optimization tips

Save research to: 03-projects/{ID}-{integration}-master-skill/02-resources/research.md

---

Phase 2: Architecture Design

Based on research, design the master skill structure:

1. Identify Child Skills - What specific skills will use this master?

   • Query/search operations
   • Import/export operations
   • Management operations
   • Automation/workflow operations

2. Define Shared Resources

   • What setup steps are common?
   • What API patterns are reused?
   • What errors occur across all operations?
   • What schemas/types need documentation?

3. Plan Scripts

   • Configuration validation script
   • Resource discovery script
   • Common utility functions
   • Rate limiting (if needed)

Document architecture in: 03-projects/{ID}-{integration}-master-skill/01-planning/plan.md

---

Phase 3: Build Master Skill

Use templates from: create-master-skill/templates/

1. Create folder structure:

   skills/{integration}-master/
   ├── SKILL.md
   ├── references/
   │   ├── setup-guide.md
   │   ├── api-reference.md
   │   ├── error-handling.md
   │   └── [domain-specific].md
   ├── scripts/
   │   ├── check_{integration}_config.py
   │   ├── discover_resources.py
   │   └── [operation scripts].py
   └── tests/
       ├── README.md
       └── run_tests.py
   

2. Populate from templates (adapting to research)

3. Fill in integration-specific content

---

Phase 4: Validate

1. Run config check: python scripts/check_{integration}_config.py
2. Test discovery: python scripts/discover_resources.py
3. Verify documentation completeness
4. Create at least one child skill that uses the master

---

Resources

templates/

SKILL.md.template - Master skill declaration template

setup-guide.md.template - Setup wizard template

api-reference.md.template - API documentation template

error-handling.md.template - Error handling template

check_config.py.template - Config validation script template

references/

master-skill-patterns.md - Architecture patterns from notion-master

research-checklist.md - Comprehensive research checklist

---

Example: Creating Airtable Master Skill

User: "create master skill for airtable"

AI: "I'll help you create an Airtable master skill. First, let me create
     a planning build to organize this work."

     → Runs plan-project skill
     → Creates: 04-airtable-master-skill build

AI: "Build created. Now I'll research the Airtable API comprehensively."

     → Runs 8 web searches
     → Saves findings to research.md

AI: "Research complete. Based on findings, I recommend these child skills:
     - airtable-connect (query any base/table)
     - airtable-sync (import/export records)
     - airtable-automate (trigger-based workflows)

     The master skill will provide:
     - Setup guide (API key, base IDs)
     - API reference (REST endpoints, field types)
     - Error handling (rate limits, validation errors)
     - Scripts (config check, base discovery)

     Shall I proceed with building?"

User: "Yes"

AI: → Creates skills/integrations/airtable/airtable-master/
    → Populates from templates
    → Adapts content based on research
    → Validates setup

---

Success Criteria

A master skill is complete when:

• [ ] SKILL.md clearly says "DO NOT load directly"
• [ ] setup-guide.md covers first-time setup end-to-end
• [ ] api-reference.md documents key operations
• [ ] error-handling.md covers common errors with solutions
• [ ] check_config.py validates all required configuration
• [ ] At least one child skill successfully references it
• [ ] Context reduction achieved (measure before/after)

---

Why This Design?

Why Build First?

• Complex work deserves proper planning
• Research findings need a home
• Progress tracked via project tasks
• Validates the approach before building

Why Research First?

• Every integration is different
• API patterns vary significantly
• Prevents wrong assumptions
• Ensures comprehensive coverage

Why Templates?

• Consistent structure across master skills
• Proven patterns from notion-master
• Reduces cognitive load
• Accelerates development

---

Version: 1.0 Created: 2025-12-11 Based on: notion-master architecture analysis