Plan-Based Skill Builder

Quick Start

When building a skill from a plan document:

1. Analyze the plan document structure and purpose
2. Extract workflows, checklists, and key instructions
3. Identify trigger scenarios and use cases
4. Create a structured SKILL.md following best practices
5. Generate supporting files if needed (reference.md, examples.md)

Plan Document Types

Restart Plans

• Focus on restart procedures, verification steps, health checks
• Extract restart workflows, validation commands, troubleshooting steps
• Create skills for restart operations, system recovery, health monitoring

Deployment Plans

• Focus on deployment steps, configuration, validation
• Extract deployment workflows, configuration templates, rollback procedures
• Create skills for deployment operations, configuration management

Prioritization Plans

• Focus on ranking, scoring, decision-making frameworks
• Extract scoring rubrics, ranking algorithms, decision criteria
• Create skills for prioritization, ranking, selection workflows

Retest Plans

• Focus on testing procedures, validation steps, success criteria
• Extract test workflows, validation commands, acceptance criteria
• Create skills for testing, validation, quality assurance

Migration Plans

• Focus on migration steps, data transformation, validation
• Extract migration workflows, transformation rules, verification steps
• Create skills for migration operations, data transformation

Skill Creation Workflow

Step 1: Analyze Plan Document

Read the plan document and identify:

Purpose & Scope:

• What is the main goal of this plan?
• What domain/area does it cover?
• What problems does it solve?

Key Workflows:

• What are the main steps or procedures?
• Are there checklists or sequential processes?
• What decision points exist?

Trigger Scenarios:

• When would someone need this skill?
• What keywords or situations trigger its use?
• What related tasks would benefit from this?

Key Instructions:

• What specific commands or procedures are documented?
• What patterns or templates are provided?
• What validation or verification steps exist?

Supporting Information:

• Are there examples or reference materials?
• Are there scripts or utilities mentioned?
• Are there integration points with other systems?

Step 2: Extract Skill Components

Name:

• Use lowercase, hyphens, max 64 chars
• Reflect the plan’s purpose (e.g., restart-operations, deployment-workflow)
• Be specific and descriptive

Description:

• Write in third person
• Include WHAT (capabilities) and WHEN (trigger scenarios)
• Include key terms for discovery
• Max 1024 chars

Instructions:

• Convert plan steps into actionable instructions
• Preserve workflows and checklists
• Include command examples and code snippets
• Add validation steps and error handling

Examples:

• Extract concrete examples from the plan
• Include command-line examples
• Show expected outputs or results

Integration Points:

• Identify related skills or systems
• Document dependencies
• Reference related workflows

Step 3: Structure the Skill

Follow the standard SKILL.md structure:

---
name: skill-name
description: [Third-person description with triggers]
---

# Skill Name

## Quick Start
[Essential instructions]

## Workflow
[Step-by-step process]

## Key Components
[Important concepts, commands, patterns]

## Examples
[Concrete examples]

## Integration Points
[Related skills, systems, workflows]

## Troubleshooting
[Common issues and solutions]

Step 4: Create Supporting Files (If Needed)

reference.md:

• Detailed API documentation
• Complete command reference
• Advanced configurations

examples.md:

• Extended examples
• Use case scenarios
• Edge cases

scripts/ (if needed):

• Utility scripts mentioned in plan
• Validation scripts
• Helper tools

Plan Analysis Patterns

Restart Plan Pattern

Common Sections:

• Restart procedures (stop → wait → start)
• Health checks and verification
• Troubleshooting steps
• Rollback procedures

Skill Extraction:

## Restart Workflow

1. Stop services: [commands]
2. Wait for cleanup: [duration]
3. Start services: [commands]
4. Verify health: [checks]
5. Validate functionality: [tests]

Deployment Plan Pattern

Common Sections:

• Pre-deployment checks
• Deployment steps
• Post-deployment validation
• Rollback procedures

Skill Extraction:

## Deployment Process

### Pre-Deployment
- [ ] Checklist item 1
- [ ] Checklist item 2

### Deployment
1. Step 1: [command]
2. Step 2: [command]

### Post-Deployment
- Verify: [check]
- Validate: [test]

Prioritization Plan Pattern

Common Sections:

• Scoring framework
• Ranking algorithm
• Decision criteria
• Action recommendations

Skill Extraction:

## Scoring Framework

### Factor 1: [Name]
- **5**: [Criteria]
- **4**: [Criteria]
- **3**: [Criteria]

### Ranking Process
1. Score each item
2. Calculate composite
3. Rank by score
4. Categorize by action

Example: Building from Restart Plan

Input Plan Document:

# System Restart Plan

## Restart Procedure
1. Stop API: `kill -TERM <PID>`
2. Wait 10 seconds
3. Start API: `make start-paper`
4. Verify: `curl :8000/ready`

Generated Skill:

---
name: system-restart
description: Restart trading systems with proper sequencing and health verification. Use when restarting APIs, services, or when system recovery is needed.
---

# System Restart

## Quick Start

Restart sequence:
1. Stop services gracefully
2. Wait for cleanup
3. Start services
4. Verify health

## Restart Workflow

### Step 1: Stop Services
```bash
# Find and stop API
lsof -nP -iTCP:8000 | awk '/LISTEN/ {print $2}' | xargs kill -TERM

Step 2: Wait for Cleanup

sleep 10  # Allow graceful shutdown

Step 3: Start Services

make start-paper  # or make live

Step 4: Verify Health

curl :8000/ready | jq  # Should return 200
curl :8000/metrics | grep '^trader_is_leader'  # Should be 1

## Best Practices

### 1. Preserve Plan Structure
- Keep workflows intact
- Maintain checklists
- Preserve command sequences

### 2. Enhance with Context
- Add error handling not in plan
- Include troubleshooting steps
- Add validation checks

### 3. Make It Discoverable
- Include trigger keywords in description
- Add related terms
- Reference common use cases

### 4. Keep It Concise
- Extract essential information
- Remove redundant explanations
- Focus on actionable content

### 5. Add Integration Points
- Reference related skills
- Link to documentation
- Connect to related workflows

## Common Extraction Patterns

### Commands → Instructions
```markdown
# Plan:
```bash
make start-paper

Skill:

Start System

make start-paper

Wait 10 seconds, then verify with curl :8000/ready

### Checklists → Workflows
```markdown
# Plan:
- [ ] Step 1
- [ ] Step 2

# Skill:
## Deployment Checklist
1. Step 1: [details]
2. Step 2: [details]

Procedures → Step-by-Step

# Plan:
1. Do X
2. Then Y
3. Finally Z

# Skill:
## Procedure
### Step 1: Do X
[Details and commands]

### Step 2: Then Y
[Details and commands]

### Step 3: Finally Z
[Details and commands]

Validation Checklist

After creating a skill from a plan, verify:

• Skill name is lowercase, hyphenated, max 64 chars
• Description is third-person, includes triggers
• Description includes WHAT and WHEN
• Instructions are actionable and clear
• Workflows preserve plan structure
• Examples are concrete and useful
• Integration points are documented
• SKILL.md is under 500 lines
• Supporting files are one level deep
• Commands are tested and accurate

Related Resources

• Skill creation guide: create-skill skill
• Plan documents: *PLAN*.md files in root
• Existing skills: .cursor/skills/ directory
• Agent files: .cursor/agents/ directory

Troubleshooting

Plan Too Vague

• Look for implicit workflows
• Extract common patterns
• Add general guidance

Plan Too Specific

• Generalize to broader use cases
• Extract reusable patterns
• Add configuration options

Missing Information

• Infer from context
• Add placeholder sections
• Document assumptions

Conflicting Information

• Use most recent or authoritative source
• Document conflicts
• Provide alternatives

Always create skills that are discoverable, actionable, and aligned with the plan’s intent while following Cursor skill best practices.