@skill-tools/core

Core parser, types, and utilities for the skill-tools ecosystem. This is the foundation package that all other tools depend on. Implements the Agent Skills specification.

npm install @skill-tools/core

What it does

Parses SKILL.md files — extracts YAML frontmatter, markdown sections, file references, and token counts
Defines shared types — Skill, SkillMetadata, Diagnostic, ParseResult
Counts tokens — using tiktoken (cl100k_base encoding, GPT-4o compatible)
Resolves skill files — finds SKILL.md files in directories and directory trees

API

`parseSkill(filePath)`

Reads and parses a SKILL.md file from disk. Returns a discriminated union result.

import { parseSkill } from '@skill-tools/core';

const result = await parseSkill('./my-skill/SKILL.md');

if (result.ok) {
  console.log(result.skill.metadata.name);
  console.log(result.skill.body);
  console.log(result.skill.tokenCount);
} else {
  console.error(result.diagnostics);
}

`parseSkillContent(content, filePath, dirPath)`

Parses SKILL.md from a string. Synchronous. Useful when content is already in memory.

import { parseSkillContent } from '@skill-tools/core';

const result = parseSkillContent(rawMarkdown, '/path/SKILL.md', '/path');

`countTokens(text)`

Returns the token count for a string using the cl100k_base encoding.

`resolveSkillFiles(searchPath)`

Finds all SKILL.md files in a path. Handles single files, single directories, and parent directories containing multiple skill subdirectories.

Validation Rules

The parser enforces the Agent Skills specification:

Rule ID	Severity	Description
`frontmatter-required`	error	YAML frontmatter must be present
`frontmatter-valid-yaml`	error	Frontmatter must be valid YAML
`name-required`	error	Name field is required
`name-format`	error	Name must be lowercase alphanumeric + hyphens, 1-64 chars, no consecutive hyphens
`description-required`	error	Description field is required
`description-length`	warn/error	Warns if <10 chars, errors if >1024 chars
`token-budget`	warning	Warns when total tokens exceed 5,000
`file-reference-exists`	warning	Referenced files should exist on disk

Security

Prototype pollution protection on frontmatter keys (__proto__, constructor)
Path traversal guard on file references

Dependencies

gray-matter — YAML frontmatter parsing
js-tiktoken — Token counting (cl100k_base encoding)