Plan-Based Skill Builder

Quick Start

When building a skill from a plan document:

• Analyze the plan document structure and purpose

• Extract workflows, checklists, and key instructions

• Identify trigger scenarios and use cases

• Create a structured SKILL.md following best practices

• 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

# 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.