━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ CRITICAL EXECUTION REQUIREMENTS ⚠️

WORKFLOW: Project FIRST, Research SECOND, Build THIRD

MANDATORY STEPS (DO NOT SKIP):

• ✅ Create TodoWrite with ALL phases

• ✅ Ask integration name (e.g., "airtable", "slack", "github")

• ✅ RUN create-project skill to create planning project

• ✅ PHASE 1: Web Research - comprehensive API/integration research

• ✅ PHASE 2: Architecture Design - define master skill structure

• ✅ PHASE 3: Build - create master skill from templates

• ✅ PHASE 4: Validate - test and document

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

CORRECT PATTERN (DO THIS): ✅ Ask integration → Create project → Research → Design → Build → Validate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Create Master Skill

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

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:

• Creates planning project: {ID}-airtable-master-skill

• Runs comprehensive web research on Airtable API

• Designs architecture based on research

• Builds master skill from templates

• 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:

• Validate name (lowercase, hyphenated)

• Check if {integration}-master already exists

• Create planning project using create-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: 02-projects/{ID}-{integration}-master-skill/02-resources/research.md

Phase 2: Architecture Design

Based on research, design the master skill structure:

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

• Query/search operations

• Import/export operations

• Management operations

• Automation/workflow operations

Define Shared Resources

• What setup steps are common?

• What API patterns are reused?

• What errors occur across all operations?

• What schemas/types need documentation?

Plan Scripts

• Configuration validation script

• Resource discovery script

• Common utility functions

• Rate limiting (if needed)

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

Phase 3: Build Master Skill

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

Create folder structure:

00-system/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

Populate from templates (adapting to research)

Fill in integration-specific content

Phase 4: Validate

• Run config check: python scripts/check_{integration}_config.py

• Test discovery: python scripts/discover_resources.py

• Verify documentation completeness

• 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 project to organize this work."

 → Runs create-project skill
 → Creates: 04-airtable-master-skill project

AI: "Project 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 00-system/skills/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 Project 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