Skip to content

AI-native design editor. Open-source Figma alternative.

3.9 KB
Raw Blame
import * as v from 'valibot'
import { parse as parseYAML } from 'yaml'

import type { SkillDefinition, SkillParseError, SkillWarning } from './types'

/** Limits from the Agent Skills specification (https://agentskills.io/specification). */
export const MAX_SKILL_NAME_LENGTH = 64
export const MAX_SKILL_DESCRIPTION_LENGTH = 1024
const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/

const FRONTMATTER = /^?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/

const frontmatterSchema = v.object({
  name: v.optional(v.string()),
  description: v.optional(v.string()),
  'disable-model-invocation': v.optional(v.boolean()),
  'user-invocable': v.optional(v.boolean())
})

export type SkillParseResult =
  | { ok: true; skill: SkillDefinition; warnings: SkillWarning[] }
  | { ok: false; error: SkillParseError }

const PLAIN_LINE = /^([A-Za-z][\w-]*):[ \t]*(.*)$/

/**
 * Frontmatter that is not valid YAML read as one `key: value` per line, indented lines
 * continuing the value above. Descriptions with an unquoted ": " are the usual cause, and other
 * agents still load those skills.
 */
function readPlainFrontmatter(source: string): Record<string, string | boolean> {
  const fields: Record<string, string> = {}
  let key: string | null = null
  for (const line of source.split(/\r?\n/)) {
    const field = PLAIN_LINE.exec(line)
    if (field?.[1] !== undefined) {
      key = field[1]
      fields[key] = field.at(2)?.trim() ?? ''
    } else if (key !== null && /^\s+\S/.test(line)) {
      fields[key] = `${fields[key] ?? ''} ${line.trim()}`.trim()
    }
  }
  return Object.fromEntries(
    Object.entries(fields).map(([name, value]) => [name, plainValue(value)])
  )
}

function plainValue(value: string): string | boolean {
  if (value === 'true') return true
  if (value === 'false') return false
  return value.replace(/^(["'])(.*)\1$/, '$2')
}

function readFrontmatter(
  text: string
): { data: unknown; body: string; plain?: true } | { error: SkillParseError } {
  const match = FRONTMATTER.exec(text)
  if (!match) return { error: { code: 'no-frontmatter' } }
  const source = match.at(1) ?? ''
  const body = text.slice(match[0].length)
  try {
    return { data: parseYAML(source), body }
  } catch {
    return { data: readPlainFrontmatter(source), body, plain: true }
  }
}

/**
 * Reads a SKILL.md as pi and Claude Code do: a skill without a description cannot be offered,
 * so it fails; other departures from the specification are warnings and the skill still loads.
 * A SKILL.md that came without a folder, such as an upload, must name itself.
 */
export function parseSkill(text: string, folderName: string | null): SkillParseResult {
  const frontmatter = readFrontmatter(text)
  if ('error' in frontmatter) return { ok: false, error: frontmatter.error }
  const parsed = v.safeParse(frontmatterSchema, frontmatter.data ?? {})
  if (!parsed.success) {
    return { ok: false, error: { code: 'invalid-frontmatter', detail: v.summarize(parsed.issues) } }
  }
  const fields = parsed.output
  const description = fields.description?.trim() ?? ''
  if (!description) return { ok: false, error: { code: 'no-description' } }

  const warnings: SkillWarning[] = frontmatter.plain ? ['plain-frontmatter'] : []
  const name = fields.name?.trim() || folderName
  if (!name) return { ok: false, error: { code: 'no-name' } }
  if (!fields.name?.trim()) warnings.push('name-from-folder')
  if (name.length > MAX_SKILL_NAME_LENGTH) warnings.push('long-name')
  if (!NAME_PATTERN.test(name)) warnings.push('name-format')
  if (folderName !== null && name !== folderName) warnings.push('name-mismatch')
  if (description.length > MAX_SKILL_DESCRIPTION_LENGTH) warnings.push('long-description')

  return {
    ok: true,
    skill: {
      name,
      description,
      instructions: frontmatter.body.trim(),
      modelInvocable: fields['disable-model-invocation'] !== true,
      userInvocable: fields['user-invocable'] !== false
    },
    warnings
  }
}