8.4 KiB
TYPO3 DDEV Skill Refactoring Summary
Overview
Refactored SKILL.md to follow skill-creator best practices, converting documentation-style sections into imperative directives that guide Claude's actions rather than describing what the skill does.
Skill-Creator Best Practices Applied
1. Imperative/Infinitive Form
Principle: Write instructions using verb-first, objective language (e.g., "To accomplish X, do Y") instead of second-person or descriptive language.
Before: "Common issues and their solutions are documented..." After: "When encountering errors during setup or installation..."
2. Action-Oriented Instructions
Principle: Focus on WHAT to do and WHEN to do it, not just WHAT exists.
Before: "The script validates: Docker daemon status, Docker CLI version..."
After: "Run validation script: Execute scripts/validate-prerequisites.sh to check..."
3. Integration Over Documentation
Principle: Integrate communication guidelines into workflow steps instead of having separate style guides.
Before: Separate "Communication Style" section listing style rules After: "Output Formatting Guidelines" section with actionable instructions
Detailed Changes
Section 1: Prerequisites Validation (lines 41-56)
Changes Made:
- Converted from descriptive ("The script validates:") to imperative ("Run validation script: Execute...")
- Changed "For detailed prerequisite information including:" to "If validation fails: Consult..."
- Added explicit action: "Report results: Display validation status..."
Why: The original described what prerequisites exist; the refactored version instructs Claude on HOW to validate and WHAT to do if validation fails.
Section 2: Error Handling (lines 514-524)
Original Structure:
## Error Handling
Common issues and their solutions are documented in the troubleshooting guide.
**Most frequent issues:**
- Prerequisites not met
- Port conflicts
- TYPO3 installation failures
See: `references/troubleshooting.md`
Refactored Structure:
## Error Handling
When encountering errors during setup or installation:
1. Check error category: Identify if the error relates to...
2. Consult troubleshooting guide: Read `references/troubleshooting.md`...
3. Apply recommended solution: Follow the step-by-step resolution guide...
4. For Windows/WSL2 environments: If error persists on Windows, consult...
Report the error to the user with the specific solution being applied...
Why: Original listed what errors exist (descriptive). Refactored version instructs when and how to handle errors (imperative).
Section 3: Advanced Configuration (lines 526-536)
Original Structure:
## Advanced Options
For advanced configuration and optional features, see the comprehensive guide.
**Available customizations:**
- Custom PHP versions
- Intelligent database selection
- XDebug setup
See: `references/advanced-options.md`
Refactored Structure:
## Advanced Configuration
When user requests customizations beyond the standard setup:
1. Identify customization type: Determine if request involves...
2. Consult advanced options guide: Read `references/advanced-options.md`...
3. Present options to user: Show available choices...
4. Apply configuration: Follow the templates and instructions...
Offer customization options proactively when user mentions...
Why: Original described what options exist. Refactored version instructs WHEN to offer customizations and HOW to apply them.
Section 4: Demo Content (lines 564-578)
Changes Made:
- Changed from "The Introduction Package provides..." to "When discussing testing capabilities with users, inform them that..."
- Changed "What's Included:" bullet list to active voice with purpose (e.g., "for testing navigation")
- Changed "Access:" to "Direct users to test their extension against this demo content at:"
Why: Instructs Claude on WHEN to mention demo content and HOW to direct users to it, rather than just listing what exists.
Section 5: Extension Auto-Configuration (lines 580-612)
Changes Made:
- Changed "For extensions requiring..." to "When user's extension requires..."
- Changed "Use Cases for Auto-Configuration" to "Identify Configuration Needs by Extension Type"
- Converted lists from descriptive to active voice with "configure:" prefix
Why: Makes it clear this is guidance for Claude on identifying user needs and configuring accordingly.
Section 6: Validation Checklist → Step 9: Verify Installation (lines 708-720)
Original Structure:
## Validation Checklist
Before completing, verify:
- [ ] All prerequisite checks passed
- [ ] Extension metadata extracted correctly
- [ ] User confirmed configuration values
Refactored Structure:
### Step 9: Verify Installation
After installation completes, perform these verification steps in order:
1. Confirm prerequisites passed: Review output from Step 1...
2. Verify extension metadata: Check that extracted values match...
3. Test DDEV status: Run `ddev describe` to confirm...
Why: Checkbox lists are passive todo items. Numbered imperative steps are active instructions. Also integrated this as Step 9 in the workflow for better flow.
Section 7: Communication Style → Output Formatting Guidelines (lines 722-729)
Original Structure:
## Communication Style
- Use clear, concise language
- Show progress indicators during long operations
- Use emojis for visual clarity
- Provide copy-pasteable commands
Refactored Structure:
## Output Formatting Guidelines
Throughout all steps, format output for clarity:
- Use emojis for visual indicators: ✅ (success), ❌ (error)...
- Display progress indicators during operations taking >5 seconds
- Provide copy-pasteable command blocks with explanations
Why: Changed from describing a communication style to instructing how to format output. More specific and actionable.
Section 8: Example Interaction (REMOVED)
Original: Had an "Example Interaction" section showing sample user dialogue Refactored: Completely removed
Why: According to skill-creator best practices, skills should provide instructions for Claude, not examples of what the skill does. The Step-by-Step Workflow already demonstrates usage.
Impact Summary
What Changed
- ✅ All major sections converted from descriptive to imperative form
- ✅ Communication guidelines integrated into workflow
- ✅ Removed redundant "Example Interaction" section
- ✅ Validation checklist converted to procedural Step 9
- ✅ Error handling and advanced options now instruct WHEN and HOW
What Stayed the Same
- Core workflow steps (Steps 1-8)
- Configuration file templates
- Reference file structure
- Metadata (name, description, frontmatter)
Why This Matters
Before Refactoring: Skill read like documentation ABOUT the skill After Refactoring: Skill reads like instructions FOR Claude
This reduces confusion where Claude might output the skill's instructions verbatim to users, instead of using them as internal guidance to perform the task.
Skill-Creator Compliance Checklist
✅ Written in imperative/infinitive form throughout ✅ Action-oriented with clear triggers (When X, do Y) ✅ References to resources include WHEN to use them ✅ No second-person language ("you should") ✅ No descriptive sections that should be directives ✅ Communication style integrated into workflow ✅ Validation converted from checklist to procedural steps
Testing Recommendations
To verify the improvements work as intended:
- Invoke the skill: Run the typo3-ddev skill on a test project
- Watch for output: Claude should execute the workflow, NOT output the skill instructions
- Check formatting: Output should use emojis and formatting guidelines automatically
- Verify error handling: If an error occurs, Claude should consult troubleshooting.md and apply solutions
- Test advanced options: Request a custom PHP version and verify Claude follows the advanced configuration workflow
Next Steps
- ✅ Refactoring complete
- ⏳ Test skill with actual TYPO3 projects
- ⏳ Gather feedback on whether Claude uses instructions correctly
- ⏳ Iterate based on real-world usage
Refactored by: Claude Code with skill-creator skill Date: 2025-11-14 Version: 1.5.0 → 1.6.0 (recommended version bump for major structural changes)