|
| 1 | +/** Source-only checks. No local Agent configuration or complete listing is available here. */ |
| 2 | +export interface SkillContextCheck { |
| 3 | + code: 'frontmatter' | 'name' | 'description' | 'codex-description-cap' | 'claude-description-cap' | 'listing-share' |
| 4 | + tone: 'warning' | 'error' |
| 5 | + message: string |
| 6 | +} |
| 7 | + |
| 8 | +type ClaudeListing |
| 9 | + = | { _tag: 'unavailable' } |
| 10 | + | { _tag: 'explicit-only' } |
| 11 | + | { _tag: 'listed', characters: number, percent: number } |
| 12 | + |
| 13 | +// Versioned observations, not tokenizer counts or a visitor's configured allowance. |
| 14 | +// https://github.com/smol-ai/skit/blob/08ff55d9d995b402ebd29c51bdedbe5690b9b0e0/docs/skill-context-budgets.md |
| 15 | +// Codex 0.160.1: 1,024 code points; Claude Code 2.1.292: 1,536 combined code points. |
| 16 | +const CODEX_DESCRIPTION_CAP = 1024 |
| 17 | +const CLAUDE_DESCRIPTION_CAP = 1536 |
| 18 | +const CLAUDE_EXAMPLE_ALLOWANCE = 8000 // 200,000 context tokens × 4 characters × 1%. |
| 19 | + |
| 20 | +export function resolveSkillContextChecks(input: { |
| 21 | + raw: string | null |
| 22 | + frontmatter: Record<string, unknown> | null |
| 23 | +}): { checks: SkillContextCheck[], claudeListing: ClaudeListing } { |
| 24 | + const checks: SkillContextCheck[] = [] |
| 25 | + if (!input.raw) |
| 26 | + return { checks, claudeListing: { _tag: 'unavailable' } } |
| 27 | + const fields = input.frontmatter |
| 28 | + if (!fields) { |
| 29 | + checks.push({ code: 'frontmatter', tone: 'error', message: 'SKILL.md needs a valid YAML header with a name and description.' }) |
| 30 | + return { checks, claudeListing: { _tag: 'unavailable' } } |
| 31 | + } |
| 32 | + const name = typeof fields.name === 'string' ? fields.name.trim() : '' |
| 33 | + const description = typeof fields.description === 'string' ? fields.description.trim() : '' |
| 34 | + if (!name) |
| 35 | + checks.push({ code: 'name', tone: 'error', message: 'The name in the SKILL.md header is missing or is not text.' }) |
| 36 | + if (!description) |
| 37 | + checks.push({ code: 'description', tone: 'error', message: 'The description in the SKILL.md header is missing or is not text.' }) |
| 38 | + if (!name || !description) |
| 39 | + return { checks, claudeListing: { _tag: 'unavailable' } } |
| 40 | + |
| 41 | + if (Array.from(description).length > CODEX_DESCRIPTION_CAP) |
| 42 | + checks.push({ code: 'codex-description-cap', tone: 'warning', message: 'Codex shortens descriptions longer than 1,024 characters. Put when-to-use details first.' }) |
| 43 | + |
| 44 | + const explicitOnly = fields['disable-model-invocation'] === true || fields['disable-model-invocation'] === 'true' |
| 45 | + if (explicitOnly) |
| 46 | + return { checks, claudeListing: { _tag: 'explicit-only' } } |
| 47 | + |
| 48 | + const combined = [description, typeof fields.when_to_use === 'string' ? fields.when_to_use : ''].filter(Boolean).join(' ').trim() |
| 49 | + const combinedCharacters = Array.from(combined) |
| 50 | + if (combinedCharacters.length > CLAUDE_DESCRIPTION_CAP) |
| 51 | + checks.push({ code: 'claude-description-cap', tone: 'warning', message: 'Claude Code shortens description plus when_to_use after 1,536 characters by default. Put when-to-use details first.' }) |
| 52 | + |
| 53 | + // Matches Skit's estimated name, separator, capped description, and newline row. |
| 54 | + const characters = Array.from(`${name}: ${combinedCharacters.slice(0, CLAUDE_DESCRIPTION_CAP).join('')}\n`).length |
| 55 | + const percent = characters / CLAUDE_EXAMPLE_ALLOWANCE * 100 |
| 56 | + if (characters * 100 > CLAUDE_EXAMPLE_ALLOWANCE) |
| 57 | + checks.push({ code: 'listing-share', tone: 'warning', message: 'A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.' }) |
| 58 | + return { checks, claudeListing: { _tag: 'listed', characters, percent } } |
| 59 | +} |
0 commit comments