skill-builder

1. File Structure Checks:

# Check SKILL.md exists
[ -f "$SKILLS_PATH/$SKILL_NAME/SKILL.md" ] && echo "✅ SKILL.md exists" || echo "❌ SKILL.md missing"

# Check directory name matches YAML name
YAML_NAME=$(head -20 "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | grep "^name:" | cut -d: -f2 | tr -d ' ')
[ "$YAML_NAME" = "$SKILL_NAME" ] && echo "✅ Name matches directory" || echo "⚠️  Name mismatch"

2. YAML Frontmatter Validation:

# Extract and validate YAML
head -20 "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | python3 -c "
import yaml, sys
try:
    doc = yaml.safe_load(sys.stdin)
    print('✅ YAML syntax valid')

    # Check required fields
    if 'name' in doc:
        print(f'✅ Name field present: {doc[\"name\"]}')
        if len(doc['name']) <= 64:
            print(f'✅ Name length OK: {len(doc[\"name\"])} chars')
        else:
            print(f'⚠️  Name too long: {len(doc[\"name\"])} chars (max 64)')
    else:
        print('❌ Name field missing')

    if 'description' in doc:
        print(f'✅ Description field present: {len(doc[\"description\"])} chars')
        if len(doc['description']) <= 1024:
            print(f'✅ Description length OK')
        else:
            print(f'⚠️  Description too long: {len(doc[\"description\"])} chars (max 1024)')
    else:
        print('❌ Description field missing')

except yaml.YAMLError as e:
    print(f'❌ YAML parse error: {e}')
"

3. Line Count Check:

LINE_COUNT=$(wc -l < "$SKILLS_PATH/$SKILL_NAME/SKILL.md")
echo "SKILL.md line count: $LINE_COUNT"
if [ $LINE_COUNT -lt 500 ]; then
    echo "✅ Line count under 500 limit ($LINE_COUNT lines, $(( (500 - LINE_COUNT) )) remaining)"
else
    echo "⚠️  Line count exceeds 500 limit ($LINE_COUNT lines, $(( (LINE_COUNT - 500) )) over)"
fi

4. XML Structure Checks:

# Check for markdown headings
HEADING_COUNT=$(grep -c '^#' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" || echo 0)
if [ $HEADING_COUNT -eq 0 ]; then
    echo "✅ No markdown headings found"
else
    echo "⚠️  Found $HEADING_COUNT markdown headings - should use XML tags instead"
    grep -n '^#' "$SKILLS_PATH/$SKILL_NAME/SKILL.md"
fi

# Check required tags
for TAG in "objective" "quick_start" "success_criteria"; do
    if grep -q "<$TAG>" "$SKILLS_PATH/$SKILL_NAME/SKILL.md"; then
        echo "✅ Required tag <$TAG> present"
    else
        if [ "$TAG" = "success_criteria" ]; then
            if grep -q "<when_successful>" "$SKILLS_PATH/$SKILL_NAME/SKILL.md"; then
                echo "✅ Alternative tag <when_successful> present"
            else
                echo "❌ Missing required tag: <$TAG> or <when_successful>"
            fi
        else
            echo "❌ Missing required tag: <$TAG>"
        fi
    fi
done

# List all XML tags found
echo "XML tags found:"
grep -oE '<[a-z_]+>' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | sort | uniq -c | sort -rn

5. Progressive Disclosure Check:

if [ $LINE_COUNT -gt 300 ]; then
    if [ -d "$SKILLS_PATH/$SKILL_NAME/references" ]; then
        REF_COUNT=$(find "$SKILLS_PATH/$SKILL_NAME/references" -name "*.md" | wc -l)
        echo "✅ Progressive disclosure: $REF_COUNT reference files created"
    else
        echo "⚠️  SKILL.md is $LINE_COUNT lines but no reference files found - consider splitting"
    fi
fi

6. Reference Link Validation:

# Check all reference links exist
grep -oE '\[.*\]\([^)]+\.md\)' "$SKILLS_PATH/$SKILL_NAME/SKILL.md" | while read link; do
    FILE=$(echo "$link" | sed 's/.*(\(.*\))/\1/')
    if [ -f "$SKILLS_PATH/$SKILL_NAME/$FILE" ]; then
        echo "✅ Reference link valid: $FILE"
    else
        echo "⚠️  Broken reference link: $FILE"
    fi
done

7. Naming Convention Check:

# Check verb-noun pattern
SKILL_FIRST_WORD=$(echo "$SKILL_NAME" | cut -d- -f1)
COMMON_VERBS="create manage setup generate analyze process coordinate build handle configure deploy execute extract transform validate parse render compile"

if echo "$COMMON_VERBS" | grep -qw "$SKILL_FIRST_WORD"; then
    echo "✅ Naming convention: '$SKILL_FIRST_WORD' follows verb-noun pattern"
else
    echo "⚠️  Naming: '$SKILL_FIRST_WORD' is not a common verb - verify it's action-oriented"
fi