@skills-supply/agents-toml

Parser and validator for agents.toml manifest files.

Installation

npm install @skills-supply/agents-toml

Usage

import { parse, parseOrThrow } from "@skills-supply/agents-toml"

const result = parse(`
[package]
name = "my-skills"
version = "1.0.0"

[agents]
claude-code = true

[dependencies]
superpowers = "[email protected]"
`)

if (result.ok) {
  console.log(result.value.package?.name) // "my-skills"
  console.log(result.value.agents.get("claude-code")) // true
  console.log(result.value.dependencies.get("superpowers"))
  // { type: "registry", name: "superpowers", version: "1.0.0" }
}

// Or throw on error:
const manifest = parseOrThrow(tomlString)

What is agents.toml?

A TOML-based manifest file that lets you:

• Declare agent compatibility — specify which AI agents (Claude Code, Codex, etc.) can use your skills
• Manage dependencies — pull skills from registries, GitHub, generic git, or local paths
• Configure exports — control what your package exposes

Quick Example

[package]
name = "my-skills"
version = "1.0.0"

[agents]
claude-code = true

[dependencies]
superpowers = "superpowers-marketplace/[email protected]"
local-tools = { path = "../my-local-tools" }

Documentation

• SPEC.md — Full specification

Dependency Types

| Type | Syntax | Example | |------|--------|---------| | Registry | "[@org/]name@version" | "[email protected]" | | GitHub | { gh = "owner/repo", tag = "v1.0" } | { gh = "user/skills", branch = "main" } | | Git | { git = "https://...", rev = "abc" } | { git = "https://gitlab.com/o/r", tag = "v1" } | | Local | { path = "..." } | { path = "../local-skills" } | | Plugin | { type = "claude-plugin", ... } | { type = "claude-plugin", plugin = "x", marketplace = "o/r" } |

JSON Schema

Access the generated JSON schema:

import schema from "@skills-supply/agents-toml/schema.json"

API

parse(contents: string): ParseResult<ValidatedManifest>

Parses and validates an agents.toml string. Returns a result object:

type ParseResult<T> =
  | { ok: true; value: T }
  | { ok: false; error: ParseError }

parseOrThrow(contents: string): ValidatedManifest

Same as parse, but throws on error.

Schemas (Zod)

All Zod schemas are exported for custom validation:

import {
  ManifestSchema,
  PackageSchema,
  AgentsSchema,
  DependenciesSchema,
  // ...
} from "@skills-supply/agents-toml"

License

MIT