6.5 KiB
Version-control Insights - November 16, 2025
Auto-generated lessons learned from Claude Code Explanatory insights.
Session: 79b654b6-10f8-4c3c-92e1-a3535644366c Generated: 2025-11-16 09:57:31
valid YAML between --- delimiters
2. Required fields - name and description must be present and valid
3. Name format - Lowercase kebab-case, max 64 chars
4. Description format - Max 1024 chars, contains action verbs
By validating these before even attempting to load the skill, we catch 90%+ of skill loading issues early.
Skill Discovery and Validation
Skill Discovery and Validation
Claude Code skills are discovered by reading the frontmatter of SKILL.md files. The key validation points are:
- YAML syntax - Must be valid YAML between
---delimiters - Required fields -
nameanddescriptionmust be present and valid - Name format - Lowercase kebab-case, max 64 chars
- Description format - Max 1024 chars, contains action verbs
By validating these before even attempting to load the skill, we catch 90%+ of skill loading issues early.
Skill Discovery and Validation
Skill Discovery and Validation
Claude Code skills are discovered by reading the frontmatter of SKILL.md files. The key validation points are:
- YAML syntax - Must be valid YAML between
---delimiters - Required fields -
nameanddescriptionmust be present and valid - Name format - Lowercase kebab-case, max 64 chars
- Description format - Max 1024 chars, contains action verbs
By validating these before even attempting to load the skill, we catch 90%+ of skill loading issues early.
Skill as Documentation Pattern
Skill as Documentation Pattern
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
- Flexibility: I can adapt instructions to context rather than rigidly executing code
- Maintainability: Plain markdown is easier to update than code
- Clarity: Users can read SKILL.md to understand exactly what will happen
- Extensibility: Easy to add new phases, patterns, or validations
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
Skill as Documentation Pattern
Skill as Documentation Pattern
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
- Flexibility: I can adapt instructions to context rather than rigidly executing code
- Maintainability: Plain markdown is easier to update than code
- Clarity: Users can read SKILL.md to understand exactly what will happen
- Extensibility: Easy to add new phases, patterns, or validations
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
Skill as Documentation Pattern
Skill as Documentation Pattern
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
- Flexibility: I can adapt instructions to context rather than rigidly executing code
- Maintainability: Plain markdown is easier to update than code
- Clarity: Users can read SKILL.md to understand exactly what will happen
- Extensibility: Easy to add new phases, patterns, or validations
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
Skill as Documentation Pattern
Skill as Documentation Pattern
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
- Flexibility: I can adapt instructions to context rather than rigidly executing code
- Maintainability: Plain markdown is easier to update than code
- Clarity: Users can read SKILL.md to understand exactly what will happen
- Extensibility: Easy to add new phases, patterns, or validations
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
Skill as Documentation Pattern
Skill as Documentation Pattern
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
- Flexibility: I can adapt instructions to context rather than rigidly executing code
- Maintainability: Plain markdown is easier to update than code
- Clarity: Users can read SKILL.md to understand exactly what will happen
- Extensibility: Easy to add new phases, patterns, or validations
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
Skill as Documentation Pattern
Skill as Documentation Pattern
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
- Flexibility: I can adapt instructions to context rather than rigidly executing code
- Maintainability: Plain markdown is easier to update than code
- Clarity: Users can read SKILL.md to understand exactly what will happen
- Extensibility: Easy to add new phases, patterns, or validations
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.