firefrost-gaming/antigravity-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'codex/validator-alignment'

Browse Source
This commit is contained in:
sck_0
2026-02-02 21:43:27 +01:00
parent 988f528708 3f7dce00b8
commit afc06d1af6
6 changed files with 208 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/QUALITY_BAR.md
View File

@@ -21,6 +21,7 @@ The skill MUST have a section explicitly stating when to trigger it.
- **Good**: "Use when the user asks to debug a React component."
- **Bad**: "This skill helps you with code."
Accepted headings: `## When to Use`, `## Use this skill when`, `## When to Use This Skill`.
### 3. Safety & Risk Classification

2
scripts/normalize-frontmatter.js
View File

@@ -8,6 +8,8 @@ const SKILLS_DIR = path.join(ROOT, 'skills');
const ALLOWED_FIELDS = new Set([
'name',
'description',
'risk',
'source',
'license',
'compatibility',
'metadata',

18
scripts/tests/test_validate_skills_headings.py Normal file
View File

@@ -0,0 +1,18 @@
import os
import sys
sys.path.append(os.path.dirname(os.path.dirname(__file__)))
from validate_skills import has_when_to_use_section
SAMPLES = [
("## When to Use", True),
("## Use this skill when", True),
("## When to Use This Skill", True),
("## Overview", False),
]
for heading, expected in SAMPLES:
content = f"\n{heading}\n- item\n"
assert has_when_to_use_section(content) is expected, heading
print("ok")

16
scripts/tests/validate_skills_headings.test.js Normal file
View File

@@ -0,0 +1,16 @@
const assert = require('assert');
const { hasUseSection } = require('../validate-skills');
const samples = [
['## When to Use', true],
['## Use this skill when', true],
['## When to Use This Skill', true],
['## Overview', false],
];
for (const [heading, expected] of samples) {
const content = `\n${heading}\n- item\n`;
assert.strictEqual(hasUseSection(content), expected, heading);
}
console.log('ok');

299
scripts/validate-skills.js
View File

@@ -32,12 +32,24 @@ const MAX_SKILL_LINES = 500;
const ALLOWED_FIELDS = new Set([
'name',
'description',
'risk',
'source',
'license',
'compatibility',
'metadata',
'allowed-tools',
]);
const USE_SECTION_PATTERNS = [
/^##\s+When\s+to\s+Use/im,
/^##\s+Use\s+this\s+skill\s+when/im,
/^##\s+When\s+to\s+Use\s+This\s+Skill/im,
];
function hasUseSection(content) {
return USE_SECTION_PATTERNS.some(pattern => pattern.test(content));
}
function isPlainObject(value) {
return value && typeof value === 'object' && !Array.isArray(value);
}
@@ -99,172 +111,183 @@ function addStrictSectionErrors(label, missing, baselineSet) {
}
}
const skillIds = listSkillIds(SKILLS_DIR);
const baseline = loadBaseline();
const baselineUse = new Set(baseline.useSection || []);
const baselineDoNotUse = new Set(baseline.doNotUseSection || []);
const baselineInstructions = new Set(baseline.instructionsSection || []);
const baselineLongFile = new Set(baseline.longFile || []);
function run() {
const skillIds = listSkillIds(SKILLS_DIR);
const baseline = loadBaseline();
const baselineUse = new Set(baseline.useSection || []);
const baselineDoNotUse = new Set(baseline.doNotUseSection || []);
const baselineInstructions = new Set(baseline.instructionsSection || []);
const baselineLongFile = new Set(baseline.longFile || []);
for (const skillId of skillIds) {
const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');
for (const skillId of skillIds) {
const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');
if (!fs.existsSync(skillPath)) {
addError(`Missing SKILL.md: ${skillId}`);
continue;
}
const content = fs.readFileSync(skillPath, 'utf8');
const { data, errors: fmErrors, hasFrontmatter } = parseFrontmatter(content);
const lineCount = content.split(/\r?\n/).length;
if (!hasFrontmatter) {
addError(`Missing frontmatter: ${skillId}`);
}
if (fmErrors && fmErrors.length) {
fmErrors.forEach(error => addError(`Frontmatter parse error (${skillId}): ${error}`));
}
if (!NAME_PATTERN.test(skillId)) {
addError(`Folder name must match ${NAME_PATTERN}: ${skillId}`);
}
if (data.name !== undefined) {
const nameError = validateStringField('name', data.name, { min: 1, max: MAX_NAME_LENGTH });
if (nameError) {
addError(`${nameError} (${skillId})`);
} else {
const nameValue = String(data.name).trim();
if (!NAME_PATTERN.test(nameValue)) {
addError(`name must match ${NAME_PATTERN}: ${skillId}`);
}
if (nameValue !== skillId) {
addError(`name must match folder name: ${skillId} -> ${nameValue}`);
}
if (!fs.existsSync(skillPath)) {
addError(`Missing SKILL.md: ${skillId}`);
continue;
}
}
const descError = data.description === undefined
? 'description is required.'
: validateStringField('description', data.description, { min: 1, max: MAX_DESCRIPTION_LENGTH });
if (descError) {
addError(`${descError} (${skillId})`);
}
const content = fs.readFileSync(skillPath, 'utf8');
const { data, errors: fmErrors, hasFrontmatter } = parseFrontmatter(content);
const lineCount = content.split(/\r?\n/).length;
if (data.license !== undefined) {
const licenseError = validateStringField('license', data.license, { min: 1, max: 128 });
if (licenseError) {
addError(`${licenseError} (${skillId})`);
if (!hasFrontmatter) {
addError(`Missing frontmatter: ${skillId}`);
}
}
if (data.compatibility !== undefined) {
const compatibilityError = validateStringField(
'compatibility',
data.compatibility,
{ min: 1, max: MAX_COMPATIBILITY_LENGTH },
);
if (compatibilityError) {
addError(`${compatibilityError} (${skillId})`);
if (fmErrors && fmErrors.length) {
fmErrors.forEach(error => addError(`Frontmatter parse error (${skillId}): ${error}`));
}
}
if (data['allowed-tools'] !== undefined) {
if (typeof data['allowed-tools'] !== 'string') {
addError(`allowed-tools must be a space-delimited string. (${skillId})`);
} else if (!data['allowed-tools'].trim()) {
addError(`allowed-tools cannot be empty. (${skillId})`);
if (!NAME_PATTERN.test(skillId)) {
addError(`Folder name must match ${NAME_PATTERN}: ${skillId}`);
}
}
if (data.metadata !== undefined) {
if (!isPlainObject(data.metadata)) {
addError(`metadata must be a string map/object. (${skillId})`);
} else {
for (const [key, value] of Object.entries(data.metadata)) {
if (typeof value !== 'string') {
addError(`metadata.${key} must be a string. (${skillId})`);
if (data.name !== undefined) {
const nameError = validateStringField('name', data.name, { min: 1, max: MAX_NAME_LENGTH });
if (nameError) {
addError(`${nameError} (${skillId})`);
} else {
const nameValue = String(data.name).trim();
if (!NAME_PATTERN.test(nameValue)) {
addError(`name must match ${NAME_PATTERN}: ${skillId}`);
}
if (nameValue !== skillId) {
addError(`name must match folder name: ${skillId} -> ${nameValue}`);
}
}
}
}
if (data && Object.keys(data).length) {
const unknownFields = Object.keys(data).filter(key => !ALLOWED_FIELDS.has(key));
if (unknownFields.length) {
unknownFieldSkills.push(skillId);
addError(`Unknown frontmatter fields (${skillId}): ${unknownFields.join(', ')}`);
const descError = data.description === undefined
? 'description is required.'
: validateStringField('description', data.description, { min: 1, max: MAX_DESCRIPTION_LENGTH });
if (descError) {
addError(`${descError} (${skillId})`);
}
if (data.license !== undefined) {
const licenseError = validateStringField('license', data.license, { min: 1, max: 128 });
if (licenseError) {
addError(`${licenseError} (${skillId})`);
}
}
if (data.compatibility !== undefined) {
const compatibilityError = validateStringField(
'compatibility',
data.compatibility,
{ min: 1, max: MAX_COMPATIBILITY_LENGTH },
);
if (compatibilityError) {
addError(`${compatibilityError} (${skillId})`);
}
}
if (data['allowed-tools'] !== undefined) {
if (typeof data['allowed-tools'] !== 'string') {
addError(`allowed-tools must be a space-delimited string. (${skillId})`);
} else if (!data['allowed-tools'].trim()) {
addError(`allowed-tools cannot be empty. (${skillId})`);
}
}
if (data.metadata !== undefined) {
if (!isPlainObject(data.metadata)) {
addError(`metadata must be a string map/object. (${skillId})`);
} else {
for (const [key, value] of Object.entries(data.metadata)) {
if (typeof value !== 'string') {
addError(`metadata.${key} must be a string. (${skillId})`);
}
}
}
}
if (data && Object.keys(data).length) {
const unknownFields = Object.keys(data).filter(key => !ALLOWED_FIELDS.has(key));
if (unknownFields.length) {
unknownFieldSkills.push(skillId);
addError(`Unknown frontmatter fields (${skillId}): ${unknownFields.join(', ')}`);
}
}
if (lineCount > MAX_SKILL_LINES) {
longFiles.push(skillId);
}
if (!hasUseSection(content)) {
missingUseSection.push(skillId);
}
if (!content.includes('## Do not use')) {
missingDoNotUseSection.push(skillId);
}
if (!content.includes('## Instructions')) {
missingInstructionsSection.push(skillId);
}
}
if (lineCount > MAX_SKILL_LINES) {
longFiles.push(skillId);
if (missingUseSection.length) {
addWarning(`Missing "Use this skill when" section: ${missingUseSection.length} skills (examples: ${missingUseSection.slice(0, 5).join(', ')})`);
}
if (!content.includes('## Use this skill when')) {
missingUseSection.push(skillId);
if (missingDoNotUseSection.length) {
addWarning(`Missing "Do not use" section: ${missingDoNotUseSection.length} skills (examples: ${missingDoNotUseSection.slice(0, 5).join(', ')})`);
}
if (!content.includes('## Do not use')) {
missingDoNotUseSection.push(skillId);
if (missingInstructionsSection.length) {
addWarning(`Missing "Instructions" section: ${missingInstructionsSection.length} skills (examples: ${missingInstructionsSection.slice(0, 5).join(', ')})`);
}
if (!content.includes('## Instructions')) {
missingInstructionsSection.push(skillId);
if (longFiles.length) {
addWarning(`SKILL.md over ${MAX_SKILL_LINES} lines: ${longFiles.length} skills (examples: ${longFiles.slice(0, 5).join(', ')})`);
}
}
if (missingUseSection.length) {
addWarning(`Missing "Use this skill when" section: ${missingUseSection.length} skills (examples: ${missingUseSection.slice(0, 5).join(', ')})`);
}
if (missingDoNotUseSection.length) {
addWarning(`Missing "Do not use" section: ${missingDoNotUseSection.length} skills (examples: ${missingDoNotUseSection.slice(0, 5).join(', ')})`);
}
if (missingInstructionsSection.length) {
addWarning(`Missing "Instructions" section: ${missingInstructionsSection.length} skills (examples: ${missingInstructionsSection.slice(0, 5).join(', ')})`);
}
if (longFiles.length) {
addWarning(`SKILL.md over ${MAX_SKILL_LINES} lines: ${longFiles.length} skills (examples: ${longFiles.slice(0, 5).join(', ')})`);
}
if (unknownFieldSkills.length) {
addWarning(`Unknown frontmatter fields detected: ${unknownFieldSkills.length} skills (examples: ${unknownFieldSkills.slice(0, 5).join(', ')})`);
}
addStrictSectionErrors('Use this skill when', missingUseSection, baselineUse);
addStrictSectionErrors('Do not use', missingDoNotUseSection, baselineDoNotUse);
addStrictSectionErrors('Instructions', missingInstructionsSection, baselineInstructions);
addStrictSectionErrors(`SKILL.md line count <= ${MAX_SKILL_LINES}`, longFiles, baselineLongFile);
if (writeBaseline) {
const baselineData = {
generatedAt: new Date().toISOString(),
useSection: [...missingUseSection].sort(),
doNotUseSection: [...missingDoNotUseSection].sort(),
instructionsSection: [...missingInstructionsSection].sort(),
longFile: [...longFiles].sort(),
};
fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineData, null, 2));
console.log(`Baseline written to ${BASELINE_PATH}`);
}
if (warnings.length) {
console.warn('Warnings:');
for (const warning of warnings) {
console.warn(`- ${warning}`);
if (unknownFieldSkills.length) {
addWarning(`Unknown frontmatter fields detected: ${unknownFieldSkills.length} skills (examples: ${unknownFieldSkills.slice(0, 5).join(', ')})`);
}
}
if (errors.length) {
console.error('\nErrors:');
for (const error of errors) {
console.error(`- ${error}`);
addStrictSectionErrors('Use this skill when', missingUseSection, baselineUse);
addStrictSectionErrors('Do not use', missingDoNotUseSection, baselineDoNotUse);
addStrictSectionErrors('Instructions', missingInstructionsSection, baselineInstructions);
addStrictSectionErrors(`SKILL.md line count <= ${MAX_SKILL_LINES}`, longFiles, baselineLongFile);
if (writeBaseline) {
const baselineData = {
generatedAt: new Date().toISOString(),
useSection: [...missingUseSection].sort(),
doNotUseSection: [...missingDoNotUseSection].sort(),
instructionsSection: [...missingInstructionsSection].sort(),
longFile: [...longFiles].sort(),
};
fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineData, null, 2));
console.log(`Baseline written to ${BASELINE_PATH}`);
}
process.exit(1);
if (warnings.length) {
console.warn('Warnings:');
for (const warning of warnings) {
console.warn(`- ${warning}`);
}
}
if (errors.length) {
console.error('\nErrors:');
for (const error of errors) {
console.error(`- ${error}`);
}
process.exit(1);
}
console.log(`Validation passed for ${skillIds.length} skills.`);
}
console.log(`Validation passed for ${skillIds.length} skills.`);
if (require.main === module) {
run();
}
module.exports = {
hasUseSection,
run,
};

12
scripts/validate_skills.py
View File

@@ -3,6 +3,15 @@ import re
import argparse
import sys
WHEN_TO_USE_PATTERNS = [
re.compile(r"^##\s+When\s+to\s+Use", re.MULTILINE | re.IGNORECASE),
re.compile(r"^##\s+Use\s+this\s+skill\s+when", re.MULTILINE | re.IGNORECASE),
re.compile(r"^##\s+When\s+to\s+Use\s+This\s+Skill", re.MULTILINE | re.IGNORECASE),
]
def has_when_to_use_section(content):
return any(pattern.search(content) for pattern in WHEN_TO_USE_PATTERNS)
def parse_frontmatter(content):
"""
Simple frontmatter parser using regex to avoid external dependencies.
@@ -30,7 +39,6 @@ def validate_skills(skills_dir, strict_mode=False):
# Pre-compiled regex
security_disclaimer_pattern = re.compile(r"AUTHORIZED USE ONLY", re.IGNORECASE)
trigger_section_pattern = re.compile(r"^##\s+When to Use", re.MULTILINE | re.IGNORECASE)
valid_risk_levels = ["none", "safe", "critical", "offensive"]
@@ -80,7 +88,7 @@ def validate_skills(skills_dir, strict_mode=False):
else: warnings.append(msg)
# 3. Content Checks (Triggers)
if not trigger_section_pattern.search(content):
if not has_when_to_use_section(content):
msg = f"⚠️ {rel_path}: Missing '## When to Use' section"
if strict_mode: errors.append(msg.replace("⚠️", "❌"))
else: warnings.append(msg)