247 lines
8.4 KiB
Markdown
247 lines
8.4 KiB
Markdown
# 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**:
|
|
```markdown
|
|
## 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**:
|
|
```markdown
|
|
## 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**:
|
|
```markdown
|
|
## 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**:
|
|
```markdown
|
|
## 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**:
|
|
```markdown
|
|
## Validation Checklist
|
|
|
|
Before completing, verify:
|
|
|
|
- [ ] All prerequisite checks passed
|
|
- [ ] Extension metadata extracted correctly
|
|
- [ ] User confirmed configuration values
|
|
```
|
|
|
|
**Refactored Structure**:
|
|
```markdown
|
|
### 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**:
|
|
```markdown
|
|
## Communication Style
|
|
|
|
- Use clear, concise language
|
|
- Show progress indicators during long operations
|
|
- Use emojis for visual clarity
|
|
- Provide copy-pasteable commands
|
|
```
|
|
|
|
**Refactored Structure**:
|
|
```markdown
|
|
## 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
|
|
1. ✅ All major sections converted from descriptive to imperative form
|
|
2. ✅ Communication guidelines integrated into workflow
|
|
3. ✅ Removed redundant "Example Interaction" section
|
|
4. ✅ Validation checklist converted to procedural Step 9
|
|
5. ✅ 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:
|
|
|
|
1. **Invoke the skill**: Run the typo3-ddev skill on a test project
|
|
2. **Watch for output**: Claude should execute the workflow, NOT output the skill instructions
|
|
3. **Check formatting**: Output should use emojis and formatting guidelines automatically
|
|
4. **Verify error handling**: If an error occurs, Claude should consult troubleshooting.md and apply solutions
|
|
5. **Test advanced options**: Request a custom PHP version and verify Claude follows the advanced configuration workflow
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Refactoring complete
|
|
2. ⏳ Test skill with actual TYPO3 projects
|
|
3. ⏳ Gather feedback on whether Claude uses instructions correctly
|
|
4. ⏳ 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)
|