Frontmatter validation checklist #89
Conversation
ADHD-friendly visual organizational tools (mind maps, task breakdowns, decision trees, timelines, kanban boards) designed for neurodivergent thinking patterns. **v3.1 Accessibility Enhancements:** - Colorblind-safe mode: Pattern-based differentiation for all color vision types (protanopia, deuteranopia, tritanopia, achromatopsia) - Monochrome mode: Pure B&W optimized for printing and e-ink displays - Mode combination system: Base mode (neurodivergent/neurotypical) + optional accessibility mode - WCAG 2.1 AA/AAA compliance (Use of Color 1.4.1, Contrast Minimum 1.4.3, Enhanced 1.4.6) **Features:** - Compassionate, validating language that reduces shame and perfectionism - Realistic time estimates with 1.5-2x buffer for ADHD time blindness - 3-10 minute micro-steps to combat task initiation paralysis - Energy-aware planning (spoon theory integration) - Calming color palettes (blues/greens) that reduce sensory overload - Information density management (3-5 chunks per section) - 22 Mermaid diagram types with ADHD-optimized selection guide **Accessibility Coverage:** - ~8% of males with color vision deficiency - ~0.5% of females with color vision deficiency - Users with complete color blindness - B&W printing scenarios - E-ink display users (Kindle, reMarkable) **Testing:** Tested extensively with real-world ADHD use cases (decluttering workflows, project planning, task breakdowns). Pattern-based modes verified with colorblind simulation tools. Examples provided for all three visual modes (regular, colorblind-safe, monochrome). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Addresses CodeRabbit review feedback for PR obra#88. **Changes:** - Converted 110 bold text "headers" (**Header**) to proper Markdown headings (#### Header) - Improves semantic structure and document outline - Enhances accessibility for screen readers - Follows Markdown best practices (DRY-PRINCIPLE-202303) **Impact:** - Better document navigation - Proper heading hierarchy (##/###/####) - WCAG accessibility compliance - Screen reader compatibility All bold standalone lines converted to #### level headings under their parent ### sections. Co-Authored-By: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
… common errors
## Problem
Skills frequently fail validation due to invalid frontmatter keys. Common mistakes:
- Using 'created', 'version', 'updated' at top level (should be in metadata)
- Missing required fields (name, description)
- Exceeding character limits
## Solution
Added comprehensive "Frontmatter Validation Checklist" section (lines 563-633) with:
### Allowed Top-Level Keys
- Required: name, description
- Optional: license, allowed-tools, metadata
### Common Mistakes Documentation
Side-by-side comparison showing:
- ❌ WRONG: created: 2025-11-05 (top level)
- ✅ CORRECT: metadata: { created: 2025-11-05 }
### Quick Reference Table
9-row table showing proper placement for all common fields
### Validation Command
Bash one-liner to verify frontmatter before distribution
### Red Flags
- Any custom keys at top level
- Missing required fields
- Exceeds 1024 char limit
## Impact
Prevents recurring validation errors when:
- Creating new skills
- Bundling for distribution
- Contributing to marketplace
## Testing
Validated against 31 existing skills with frontmatter issues
All documented patterns prevent known validation failures
Fixes: Recurring frontmatter validation errors
See: https://github.com/obra/superpowers/issues/[TBD]
WalkthroughIntroduces a comprehensive neurodivergent-visual-org skill version 3.1 with documentation for a mode-aware Mermaid diagram system supporting neurodivergent accessibility needs. Adds extensive reference documentation covering accountability, current-state tracking, decision-making, focus regulation, habit-building, project mapping, task breakdowns, and time-boxing patterns. Also updates writing-skills documentation with frontmatter validation requirements. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Large cohorts of homogeneous, repetitive documentation patterns (8 reference documents with similar structure—Mermaid diagrams, language guidelines, pattern descriptions). While the scope is broad, the changes follow consistent templates and all are documentation-only with no code logic or functional changes. Areas requiring minor attention:
Poem
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skills/writing-skills/SKILL.md (1)
94-96: Update lines 94–102 to match the expanded frontmatter spec; clarify or improve the validation command.Lines 94–95 state "Only two fields supported:
nameanddescription", but the new Frontmatter Validation Checklist (lines 567–576) documents five allowed top-level keys:name,description,license,allowed-tools, andmetadata. Align the early guidance with the new spec.Additionally, the validation command at lines 625–630 is misleading. The grep command only displays the frontmatter; the comment claims it "verify[ies] frontmatter passes validation" but performs no actual validation. Either improve the command to validate the spec or clarify its purpose.
🧹 Nitpick comments (1)
skills/neurodivergent-visual-org/README.md (1)
155-165: Replace emphasis with proper heading syntax for subsections.Lines 155, 161, and 165 use bold text (
**...**) where markdown headings would be more semantically correct. This violates MD036 (no-emphasis-as-heading).-**Diagram won't render** +### Diagram won't renderSimilar replacements needed at lines 161 (
**Colors not working**) and 165 (**Events missing in timeline**).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (12)
skills/neurodivergent-visual-org/README.md(1 hunks)skills/neurodivergent-visual-org/SKILL.md(1 hunks)skills/neurodivergent-visual-org/examples/v3.1-accessibility-modes-examples.md(1 hunks)skills/neurodivergent-visual-org/references/accountability-support.md(1 hunks)skills/neurodivergent-visual-org/references/current-state-boards.md(1 hunks)skills/neurodivergent-visual-org/references/decision-tools.md(1 hunks)skills/neurodivergent-visual-org/references/focus-regulation.md(1 hunks)skills/neurodivergent-visual-org/references/habit-building.md(1 hunks)skills/neurodivergent-visual-org/references/project-maps.md(1 hunks)skills/neurodivergent-visual-org/references/task-breakdowns.md(1 hunks)skills/neurodivergent-visual-org/references/time-boxing.md(1 hunks)skills/writing-skills/SKILL.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
skills/neurodivergent-visual-org/references/habit-building.md
[style] ~22-~22: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...tern: Tiny Habit Builder Use when user wants to start a new habit but struggles with co...
(REP_WANT_TO_VB)
skills/neurodivergent-visual-org/references/time-boxing.md
[style] ~278-~278: To elevate your writing, try using more formal phrasing here.
Context: ...do 8 hours" - "Breaks are for later" - "Keep pushing through" - "Everyone else can focus lon...
(CONTINUE_TO_VB)
skills/neurodivergent-visual-org/references/focus-regulation.md
[style] ~179-~179: In this context, ‘focus’ is usually used with the preposition “on”.
Context: ...eeds:** - Background noise (can't focus in silence) - Fidgeting (helps concentrati...
(FOCUS_IN)
skills/neurodivergent-visual-org/SKILL.md
[style] ~459-~459: ‘making a decision’ might be wordy. Consider a shorter alternative.
Context: ...something complex into steps - Is stuck making a decision or mentions analysis paralysis - Asks "...
(EN_WORDINESS_PREMIUM_MAKING_A_DECISION)
[style] ~467-~467: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...racking or spoon theory visualization - Wants to understand system states or process flo...
(REP_WANT_TO_VB)
[style] ~1064-~1064: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...me? - What's the time frame (if any)? - What's your current energy level? - Have you...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~1087-~1087: Ensure spelling is correct
Context: ...th 3 sections - Medium complexity → Mindmap (3 levels), Quadrant chart (≤10 points)...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~1429-~1429: ‘Gestalt’ is a technical term that is used in psychology. To make your text as clear as possible to all readers, do not use this foreign term.
Context: ...s Law (5±2 chunks, adjusted for ADHD) - Gestalt principles (proximity, similarity) - Ni...
(GESTALT)
skills/neurodivergent-visual-org/examples/v3.1-accessibility-modes-examples.md
[style] ~112-~112: This wording could be more concise.
Context: ...eed to remember what they mean) - Still printable in color or B&W Weaknesses: - Slightly more...
(ADJECTIVE_IN_ATTRIBUTE)
🪛 markdownlint-cli2 (0.18.1)
skills/neurodivergent-visual-org/README.md
74-74: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
155-155: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
161-161: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
165-165: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (23)
skills/writing-skills/SKILL.md (2)
563-633: Frontmatter Validation Checklist section is well-structured overall.The before/after examples (lines 580–603) and quick reference table (lines 605–617) clearly teach the correct structure. Red flags (lines 628–631) are actionable. However, the section depends on the contradictions noted above being resolved. Once the frontmatter spec and validation command are fixed, this section will be strong.
646-649: GREEN phase integration is sound; validate against updated spec.Lines 646–649 correctly reference the Frontmatter Validation Checklist and list specific checks (allowed keys, metadata placement, size limit). Once the spec contradiction and validation command are resolved, these checklist items will properly guide skill creators.
skills/neurodivergent-visual-org/references/project-maps.md (2)
1-4: LGTM on metadata and frontmatter.The YAML frontmatter with created/updated timestamps is correctly formatted and consistent with PR context (2025-11-02).
5-264: Well-structured pattern documentation with clear guidance.The five project mapping patterns (Project Phases Map, Dependency Map, Overwhelm-to-Action Breakdown, Parallel Workstreams, MVP) are logically organized, progressively building from structured to flexible approaches. Mermaid diagrams use consistent color coding and styling throughout. Language Guidelines provide neurodivergent-affirming phrasing.
skills/neurodivergent-visual-org/references/time-boxing.md (2)
278-280: Minor language style suggestion at line 278.The LanguageTool hint flags "focus" phrasing. Line 278 ("Break Structure" don't list) reads:
"Keep pushing through". However, the context and neurodivergent-affirming tone of the don't-list are appropriate as written. This is a stylistic preference rather than a clarity issue, and the informal, compassionate tone fits the guidance purpose.
1-289: LGTM: Well-balanced time-boxing patterns with ADHD adaptations.Six distinct patterns (Pomodoro, time-blocked day, focus session prep, energy mapping, work sprint planning, break structure) provide comprehensive guidance. The Gantt chart example (lines 66–89) is realistic and includes mandatory breaks. Language guidelines emphasize flexibility and self-compassion.
skills/neurodivergent-visual-org/references/task-breakdowns.md (1)
1-145: LGTM: Well-designed task breakdown patterns with realistic time estimates.Three complementary patterns address sequential (Gantt), conditional (flowchart), and energy-aware (subgraph) task decomposition. The "Clean Messy Bedroom" example (lines 23–40) demonstrates realistic micro-step sizing (3–10 minutes per task). Time Estimate Guidelines section (lines 134–145) appropriately emphasizes generosity in estimates to reduce procrastination.
skills/neurodivergent-visual-org/references/current-state-boards.md (1)
1-260: LGTM: Strong current-state tracking patterns with practical capacity limits.Six patterns provide flexible tracking approaches for different contexts (Kanban, priority matrix, context-based, time-boxed, overwhelm triage, completion visibility). The Capacity Guidelines section (lines 260–266) is a valuable addition: concrete limits (2–3 active items, 4–6 hours focused work, 60–70% time planning) provide essential context for sustainable productivity.
skills/neurodivergent-visual-org/references/focus-regulation.md (1)
1-349: LGTM: Comprehensive regulation toolkit with strong ADHD grounding.Seven regulation patterns progress from pre-task preparation through recovery, addressing the full dysregulation spectrum. The Sensory Regulation Toolkit (lines 142–176) appropriately validates ADHD sensory profiles ("your needs ≠ stereotypes"). The Regulation Principles for ADHD section (lines 316–332) provides neuroscientific context. Building Your Regulation Practice (lines 334–343) encourages personalization and tracking.
skills/neurodivergent-visual-org/references/decision-tools.md (1)
1-191: LGTM: Practical decision-support patterns with anti-perfectionism focus.Four patterns—from simple decision trees to weighted matrices and elimination logic—address decision paralysis at varying complexity levels. The Anti-Perfectionism Reminders section (lines 184–191) is a valuable complement to Language Guidelines, reinforcing that decisions are reversible and "good enough" is acceptable. The social anxiety example (social event decision tree, lines 24–47) grounds the guidance in realistic ADHD scenarios.
skills/neurodivergent-visual-org/references/habit-building.md (2)
1-332: LGTM: Comprehensive habit-building framework with realistic ADHD adaptations.Six patterns—from shrinking targets to recovery protocols—provide end-to-end habit-building support. The Tiny Habit Builder pattern (lines 20–67) correctly prioritizes activation energy reduction as the primary barrier for ADHD. The Habit Recovery Protocol (lines 226–266) normalizes restarts with compassionate language ("That's life. This is normal. Not a failure."). The Momentum Tracker uses binary tracking (✅/❌, line 220 stats) which is appropriate for ADHD dopamine-driven motivation. The Habit Science for ADHD section provides evidence-based grounding.
334-335: Minor: Verify section title consistency.Line 334 title reads "Building Your Regulation Practice" but given the file context (habit-building patterns), this should likely be "Building Your Habit Practice" to maintain consistency with the file's scope and align with Language Guidelines/Habit Science sections. The content (lines 336–349) addresses habit-building specifically.
Suggest updating line 334–335 to:
-## Building Your Regulation Practice +## Building Your Habit PracticeLikely an incorrect or invalid review comment.
skills/neurodivergent-visual-org/references/accountability-support.md (1)
1-343: LGTM: Comprehensive accountability framework progressing to crisis support.Six accountability patterns progress from body doubling through crisis protocols. The Body Doubling Session Plan (lines 20–53) correctly explains the mechanism and differentiates it from collaboration. The When to Reach Out Decision Tree (lines 112–145) appropriately sets a "30 min to 2 hours" threshold before seeking help, recognizing ADHD tendency for extended rumination. The Crisis Support Protocol (lines 244–277) provides clear escalation logic (Yellow/Orange/Red) with emergency resources (988). Building Support Capacity (lines 306–343) encourages incremental onboarding rather than all-at-once system building.
skills/neurodivergent-visual-org/README.md (1)
1-4: Frontmatter missing required fields per validation checklist.The PR adds frontmatter validation requiring
nameanddescriptionfields. This file should either follow the new validation rules or be explicitly exempted as an example file.
- Does this README file need validated frontmatter, or is it exempt as a non-skill documentation file?
- If required, add:
name: neurodivergent-visual-org-readmeand an appropriate description.skills/neurodivergent-visual-org/examples/v3.1-accessibility-modes-examples.md (2)
1-7: Frontmatter missing required fields per validation checklist.Similar to README.md, this file's frontmatter lacks the required
nameanddescriptionfields defined in the new frontmatter validation rules. Clarify whether documentation/example files are exempt from validation.
- Is this an example file exempt from frontmatter validation requirements?
- If not, add:
name: neurodivergent-visual-org-examplesand a description.
1-422: Comprehensive accessibility mode examples — excellent documentation.The examples clearly demonstrate three visual encoding modes with detailed strengths/weaknesses, practical guidance, and WCAG compliance notes. The combination of Regular, Colorblind-Safe, and Monochrome modes with consistent Mermaid syntax is well-executed and provides valuable reference material.
skills/neurodivergent-visual-org/SKILL.md (7)
14-330: Comprehensive mode system documentation with clear implementation details.The four-mode framework (Neurodivergent, Neurotypical, Colorblind-Safe, Monochrome) is well-documented with:
- Clear mode selection methods (auto-detect, explicit request, config file)
- Detection algorithm with practical pseudocode (lines 96-166)
- Detailed accessibility mode specs with Mermaid examples (lines 168-327)
- Configuration file schema with sane defaults (lines 330-406)
The documentation is thorough and supports both immediate use and future customization. The backward compatibility notes (lines 87-92) are reassuring.
438-545: Exceptional research foundation and design principles.The skill clearly articulates the neuroscience basis for visual tools in ADHD (working memory constraints, P1 deficits, time perception), cites specific cognitive load theory, and grounds design decisions in evidence. The color psychology section (lines 487-504) and information density guidance (lines 506-524) provide actionable constraints that prevent overwhelm.
608-901: Excellent diagram selection guide and detailed syntax documentation.The comprehensive Mermaid guide covers:
- 22 diagram types organized by cognitive need (not task type) — excellent mental model
- Detailed syntax for priority types (flowcharts, mindmaps, timelines, quadrants, pie, state, sankey, journey)
- Clear best practices, limitations, and anti-patterns for each type
- Real gotchas documented (icons break GitHub rendering, timeline events before sections ignored, etc.)
This is exemplary technical documentation for a visual tool skill.
1056-1246: Workflow guidance and mode-switching instructions are clear and user-centric.The step-by-step workflow (understand need → select diagram → apply principles → generate → provide context) is practical and includes listening for key phrases that signal specific cognitive blocks. Mode-switching documentation (lines 1209-1246) empowers users to adapt diagrams mid-conversation.
1299-1403: Scenario-based examples demonstrate skill application effectively.Six detailed scenarios (task initiation paralysis, decision paralysis, overwhelm, time blindness, habit building, energy management) show the skill's breadth. Each includes the user's problem, Claude's recognition, chosen diagram type, principles applied, and next steps — a strong pattern for documentation.
1513-1544: Approve version history and quick reference card.The version history clearly documents feature evolution and current status. The quick reference card is concise and actionable — a useful summary for rapid skill selection.
1442-1510: Remove the unverified claim about Mermaid 11.12.1's br tag encoding fix.The release notes for Mermaid 11.12.1 (released 2025-10-27) mention only a dagre-d3-es dependency update for security. No br tag encoding fix is documented. Additionally, GitHub issue #6652 reporting br tag rendering failures in Safari v17.6 remains open with updates after the v11.12.1 release, contradicting any such fix.
The URL encoding guidance using Python's
urllib.parse.quote()is practical and appropriate; remove the specific version-dependent claim about Mermaid 11.12.1.Likely an incorrect or invalid review comment.
|
|
||
| ## Package Contents | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language identifier to fenced code block.
Line 74 has a fenced code block without a language specifier. This is flagged by markdownlint.
-```
+```yaml🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
74-74: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In skills/neurodivergent-visual-org/README.md around line 74, the fenced code
block is missing a language identifier which triggers markdownlint; update the
opening fence to include the appropriate language (e.g., yaml) so it reads as a
fenced code block with a language specifier.
| --- | ||
| name: neurodivergent-visual-org | ||
| description: Create visual organizational tools (mind maps, task breakdowns, decision trees, kanban boards, project timelines) designed for neurodivergent thinking patterns. Use when users feel overwhelmed, need to break down tasks, navigate decisions, see dependencies, or track current state. Emphasizes compassionate language, realistic time estimates, energy-aware planning, and anti-perfectionism. v3.1 adds colorblind-safe and monochrome accessibility modes. | ||
| metadata: | ||
| version: 3.1 | ||
| mermaid_version: 11.12.1 | ||
| created: 2025-11-03T00:28 | ||
| updated: 2025-11-04T17:45 | ||
| changes_v3.1: Added colorblind-safe and monochrome accessibility modes | ||
| created: 2025-11-03T00:28 | ||
| updated: 2025-11-04T20:12 | ||
| --- |
There was a problem hiding this comment.
Fix frontmatter structure: remove top-level created/updated fields.
The frontmatter violates the validation rules stated in the PR objectives. It has both:
metadata: {created, updated, ...}(lines 4-9) — correct placement- Top-level
createdandupdated(lines 10-11) — should be insidemetadatablock
Additionally, the timestamps conflict:
- Lines 7-8:
2025-11-03T00:28and2025-11-04T17:45 - Lines 10-11:
2025-11-03T00:28and2025-11-04T20:12
Apply this diff to consolidate into the correct structure:
---
name: neurodivergent-visual-org
description: Create visual organizational tools (mind maps, task breakdowns, decision trees, kanban boards, project timelines) designed for neurodivergent thinking patterns. Use when users feel overwhelmed, need to break down tasks, navigate decisions, see dependencies, or track current state. Emphasizes compassionate language, realistic time estimates, energy-aware planning, and anti-perfectionism. v3.1 adds colorblind-safe and monochrome accessibility modes.
metadata:
version: 3.1
mermaid_version: 11.12.1
created: 2025-11-03T00:28
updated: 2025-11-04T20:12
changes_v3.1: Added colorblind-safe and monochrome accessibility modes
-created: 2025-11-03T00:28
-updated: 2025-11-04T20:12
---Then verify which updated timestamp is canonical (17:45 or 20:12) and use that in the metadata block.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| name: neurodivergent-visual-org | |
| description: Create visual organizational tools (mind maps, task breakdowns, decision trees, kanban boards, project timelines) designed for neurodivergent thinking patterns. Use when users feel overwhelmed, need to break down tasks, navigate decisions, see dependencies, or track current state. Emphasizes compassionate language, realistic time estimates, energy-aware planning, and anti-perfectionism. v3.1 adds colorblind-safe and monochrome accessibility modes. | |
| metadata: | |
| version: 3.1 | |
| mermaid_version: 11.12.1 | |
| created: 2025-11-03T00:28 | |
| updated: 2025-11-04T17:45 | |
| changes_v3.1: Added colorblind-safe and monochrome accessibility modes | |
| created: 2025-11-03T00:28 | |
| updated: 2025-11-04T20:12 | |
| --- | |
| --- | |
| name: neurodivergent-visual-org | |
| description: Create visual organizational tools (mind maps, task breakdowns, decision trees, kanban boards, project timelines) designed for neurodivergent thinking patterns. Use when users feel overwhelmed, need to break down tasks, navigate decisions, see dependencies, or track current state. Emphasizes compassionate language, realistic time estimates, energy-aware planning, and anti-perfectionism. v3.1 adds colorblind-safe and monochrome accessibility modes. | |
| metadata: | |
| version: 3.1 | |
| mermaid_version: 11.12.1 | |
| created: 2025-11-03T00:28 | |
| updated: 2025-11-04T20:12 | |
| changes_v3.1: Added colorblind-safe and monochrome accessibility modes | |
| --- |
🤖 Prompt for AI Agents
In skills/neurodivergent-visual-org/SKILL.md around lines 1 to 12, the
frontmatter incorrectly includes duplicate top-level created/updated fields;
remove the top-level created and updated entries (lines 10-11) so only the
metadata block contains timestamp fields, and ensure metadata.created and
metadata.updated remain (or are updated) in the metadata block; reconcile the
conflicting updated timestamps by checking the authoritative source (commit
history or PR intent) and set metadata.updated to the canonical timestamp
(either 2025-11-04T17:45 or 2025-11-04T20:12) before saving.
| ### Validation Command | ||
|
|
||
| Before creating skill ZIP, verify frontmatter passes validation: | ||
|
|
||
| ```bash | ||
| # Check frontmatter has only allowed top-level keys | ||
| grep -A 20 "^---$" SKILL.md | head -n -1 | tail -n +2 | ||
| ``` | ||
|
|
||
| **Red flags:** | ||
| - Any key besides name, description, license, allowed-tools, metadata at top level | ||
| - Missing name or description | ||
| - Total frontmatter exceeds 1024 characters | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
Validation command doesn't actually validate frontmatter.
The grep command (line 625) displays frontmatter content but performs no validation. The comment claims it "verifies frontmatter passes validation", yet no checks run against allowed keys, required fields, or size limits. Agents will copy this command and get no actionable feedback.
Provide a working validation script (or one-liner) that:
- Extracts YAML frontmatter from SKILL.md
- Checks for only allowed top-level keys (name, description, license, allowed-tools, metadata)
- Confirms
nameanddescriptionare present - Validates total frontmatter ≤1024 characters
- Exits nonzero on failure with clear error messages
Example (Python/Bash):
#!/bin/bash
# Extract frontmatter
FM=$(sed -n '/^---$/,/^---$/p' SKILL.md | sed '1d;$d')
# Check allowed keys (name, description, license, allowed-tools, metadata)
INVALID=$(echo "$FM" | grep -o '^[a-zA-Z-]*:' | sed 's/:$//' | grep -vE '^(name|description|license|allowed-tools|metadata)$' | head -1)
if [ -n "$INVALID" ]; then
echo "Error: Invalid top-level key '$INVALID'" >&2
exit 1
fi
# Check required fields
if ! echo "$FM" | grep -q '^name:'; then
echo "Error: Missing required field 'name'" >&2
exit 1
fi
if ! echo "$FM" | grep -q '^description:'; then
echo "Error: Missing required field 'description'" >&2
exit 1
fi
# Check size
if [ $(echo "$FM" | wc -c) -gt 1024 ]; then
echo "Error: Frontmatter exceeds 1024 characters" >&2
exit 1
fi
echo "✓ Frontmatter valid"is not applicable; we need codebase context.
🏁 Script executed:
#!/bin/bash
# 1. Inspect the actual file content at the specified lines
echo "=== File content at lines 619-632 ==="
sed -n '619,632p' skills/writing-skills/SKILL.md
echo ""
echo "=== Search for existing YAML/frontmatter validation in codebase ==="
# Look for validation scripts, Python YAML parsing, or frontmatter checks
rg -n -C3 -i 'frontmatter|yaml.*validat|validat.*frontmatter' --type=py --type=sh --type=js
echo ""
echo "=== Search for validation-related files or scripts ==="
fd -e py -e sh -e js | grep -i 'validat\|check\|lint'Length of output: 236
🏁 Script executed:
#!/bin/bash
# Find all SKILL.md files in the repository
echo "=== Locating SKILL.md files ==="
fd -name "SKILL.md" -o -name "*.md" | grep -i skill | head -20
echo ""
echo "=== Repository structure at root ==="
ls -la | head -20
echo ""
echo "=== Search for any directory containing 'writing-skills' or 'skills' ==="
fd -type d -name "*skills*" -o -name "*skill*" | head -20Length of output: 1465
🏁 Script executed:
#!/bin/bash
# List skills directory to find writing-skills
echo "=== Contents of skills directory ==="
ls -la skills/
echo ""
echo "=== Check for writing-skills/SKILL.md ==="
ls -la skills/writing-skills/ 2>/dev/null | head -10
echo ""
echo "=== Extract lines 619-632 from SKILL.md ==="
sed -n '619,632p' skills/writing-skills/SKILL.md 2>/dev/null
echo ""
echo "=== Search for validation/YAML code patterns ==="
rg -n 'frontmatter|yaml|validat' skills/ --type py --type sh --type js -C2Length of output: 2619
🏁 Script executed:
#!/bin/bash
# Extract and inspect the actual frontmatter from SKILL.md
echo "=== Extract frontmatter from skills/writing-skills/SKILL.md ==="
sed -n '/^---$/,/^---$/p' skills/writing-skills/SKILL.md | head -30
echo ""
echo "=== Count frontmatter characters ==="
FM=$(sed -n '/^---$/,/^---$/p' skills/writing-skills/SKILL.md | sed '1d;$d')
echo "Frontmatter line count: $(echo "$FM" | wc -l)"
echo "Frontmatter byte count: $(echo "$FM" | wc -c)"
echo ""
echo "=== Search for CI/validation workflows ==="
find . -name "*.yml" -o -name "*.yaml" | xargs grep -l "validat\|skill\|frontmatter" 2>/dev/null
echo ""
echo "=== Search for Python/shell validation scripts anywhere ==="
fd -e py -e sh 2>/dev/null | xargs grep -l "validat" 2>/dev/null | head -10Length of output: 986
Replace non-functional validation command with working script that actually validates frontmatter.
The current grep command (line 625) only displays frontmatter content without performing any checks. Documentation claims it "verifies frontmatter passes validation", but no validation runs.
Replace lines 625-626 with a functional validation script that extracts frontmatter and checks:
- Only allowed top-level keys (name, description, license, allowed-tools, metadata)
- Required fields
nameanddescriptionpresent - Total frontmatter ≤1024 characters
- Exits nonzero on failure with clear errors
Example bash one-liner:
FM=$(sed -n '/^---$/,/^---$/p' SKILL.md | sed '1d;$d') && \
grep -qE '^(name|description):' <<< "$FM" && \
! grep -qE '^[^:]+:' <<< "$FM" | grep -vE '^(name|description|license|allowed-tools|metadata):' && \
[ $(echo "$FM" | wc -c) -le 1024 ] && echo "✓ Frontmatter valid" || echo "✗ Frontmatter invalid" >&2Or provide a full script (shell or Python) with specific error messages for each validation failure.
|
Hi - could you give me the real problem you're running into that this PR solves? Also, it looks like you merged in significant other changes unrelated to what's being addressed here. |
|
Sorry man I may have hit an issue due to an obsidian plugin and created
this thinking it was more common than it really is for the frontmatter to
be rejected in superpowers registration after installation locally…
It happened to me twice but I apologize for not scrutinizing the code more
closely if it is doing random stuff; if not useful I apologize: this is due
to the Obsidian plugin:
*In skills/neurodivergent-visual-org/SKILL.md around lines 1 to 12, the
frontmatter incorrectly includes duplicate top-level created/updated
fields; remove the top-level created and updated entries (lines 10-11) so
only the metadata block contains timestamp fields, and ensure
metadata.created and metadata.updated remain (or are updated) in the
metadata block; reconcile the conflicting updated timestamps by checking
the authoritative source (commit history or PR intent) and set
metadata.updated to the canonical timestamp (either 2025-11-04T17:45 or
2025-11-04T20:12) before saving.Cheers,Jack*
…On Thu, Nov 6, 2025 at 12:51 PM Jesse Vincent ***@***.***> wrote:
*obra* left a comment (obra/superpowers#89)
<#89 (comment)>
Hi - could you give me the real problem you're running into that this PR
solves?
Also, it looks like you merged in significant other changes unrelated to
what's being addressed here.
—
Reply to this email directly, view it on GitHub
<#89 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AALXIPCAWIZE6ATGHUZM2M333OYDZAVCNFSM6AAAAACLF2EE7OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIOJZGM2DGMRXGQ>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
2 participants
PR: Add Frontmatter Validation Checklist to writing-skills
GitHub PR Details
Target Repository:
https://github.com/obra/superpowersBase Branch:
mainHead Branch:
JackReis:frontmatter-validation-checklistTitle:
feat(writing-skills): add frontmatter validation checklist to prevent common errorsBranch URL: https://github.com/JackReis/superpowers/tree/frontmatter-validation-checklist
PR Creation URL: main...JackReis:superpowers:frontmatter-validation-checklist
PR Description
Problem
Skills frequently fail Claude Code validation due to invalid frontmatter keys. Based on testing with 31+ skills, common mistakes include:
created,version,updatedat top level (should be inmetadatablock)name,description)Real-world examples of this issue:
Solution
Added comprehensive Frontmatter Validation Checklist section to
writing-skillsskill (lines 563-633).Key Features
1. Allowed Top-Level Keys Documentation
name,descriptionlicense,allowed-tools,metadata2. Common Mistakes with Before/After Examples
Side-by-side comparison showing wrong vs. correct patterns:
created: 2025-11-05(top level)metadata: { created: 2025-11-05 }version: 1.0.0(top level)metadata: { version: 1.0.0 }author: "Name"(top level)metadata: { author: "Name" }3. Quick Reference Table
9-row table showing proper placement for all common fields:
namename: my-skilldescriptiondescription: Does Xcreatedmetadata:metadata: { created: 2025-11-05 }updatedmetadata:metadata: { updated: 2025-11-05 }versionmetadata:metadata: { version: 1.0.0 }authormetadata:metadata: { author: "Name" }tagsmetadata:metadata: { tags: [tag1, tag2] }licenselicense: MITallowed-toolsallowed-tools: [Read, Write]4. Validation Command
Bash one-liner to verify frontmatter structure before creating skill ZIPs:
5. Red Flag Checklist
name,description,license,allowed-tools,metadataat top levelnameordescriptionIntegration
Updated the "Skill Creation Checklist" GREEN phase to cross-reference the new validation section:
Impact
Prevents recurring validation errors during:
Improves developer experience by:
Testing
Motivation
This issue surfaced repeatedly during skill development, with the same validation errors occurring across multiple skills. The
writing-skillsskill is the ideal location for this documentation since it guides all skill creation.Current upstream documentation only mentions:
But doesn't document:
license,allowed-tools,metadata)version,created,updatedThis PR fills that gap with field-tested guidance from production skill development.
Files Changed
skills/writing-skills/SKILL.md(+76 lines)Commit
Commit SHA:
38fe413Commit Message:
How to Review
Quick review:
Thorough review:
Related Issues
If there's an existing issue tracking skill frontmatter validation problems, please reference it here.
Alternatively, this PR can serve as the canonical documentation for the correct frontmatter schema.
Maintainer Notes
This is a documentation-only change - no code modifications, no behavior changes, just comprehensive guidance that was missing from the current
writing-skillsskill.The validation checklist is designed to be:
Merge impact: Minimal - adds 76 lines of documentation to help skill authors avoid validation errors.
Future Enhancements (Outside Scope)
After this PR is merged, potential follow-ups could include:
validate-skill-frontmatter.shin repo toolsgenerate-skill-frontmatter --type=standardThese are intentionally NOT included in this PR to keep the change focused on documentation.
Summary by CodeRabbit
New Features
Documentation