Agent Skill

Personal agent skill specification with a built-in reference parser

What is Agent Skill?

Agent Skill is a personal, opinionated variant of the Agent Skills specification. The upstream format requires YAML frontmatter for metadata; this variant deliberately omits frontmatter entirely. All metadata and instructions live inside a single XML-mixed <skill> element in the Markdown body. This package parses SKILL.md documents into strongly-typed skill objects with metadata, purpose, guidelines, and implementation sections.

Installation

npm:

npm install @neabyte/agent-skill

CDN (jsDelivr/esm.sh):

<script type="module">
  import Skill from 'https://cdn.jsdelivr.net/npm/@neabyte/agent-skill/dist/index.mjs'
</script>

Or via esm.sh:

<script type="module">
  import Skill from 'https://esm.sh/@neabyte/agent-skill'
</script>

Usage

Warning

This is a pure text-to-data API with no filesystem I/O, designed to run in any environment including browsers, CLI, and terminal applications. Reading SKILL.md files from disk is left to the consumer.

import Skill, { type SkillResult } from '@neabyte/agent-skill'

const source = `
<skill name="code-reviewer">
<purpose hint="Overall goal the agent must achieve here">

Review pull requests for correctness, style, and security concerns thoroughly.

</purpose>
<guidelines hint="Non-negotiable rules the agent must always obey">

- Always read the full diff before commenting.
- Flag security issues before style preferences.

</guidelines>
<implementation hint="Concrete blueprint the agent must follow step by step">

Read each changed file, check invariants, then summarize findings inline.

</implementation>
</skill>
`

const result: SkillResult[] = Skill.parse(source)
console.log(result[0])
// {
//   skill: { name: 'code-reviewer' },
//   purpose: {
//     hint: 'Overall goal the agent must achieve here',
//     body: 'Review pull requests for correctness, style, and security concerns thoroughly.'
//   },
//   guidelines: {
//     hint: 'Non-negotiable rules the agent must always obey',
//     body: '- Always read the full diff before commenting.\n- Flag security issues before style preferences.'
//   },
//   implementation: {
//     hint: 'Concrete blueprint the agent must follow step by step',
//     body: 'Read each changed file, check invariants, then summarize findings inline.'
//   }
// }

Multiple skills in one file

const source = `
<skill name="skill-one">
<purpose>...</purpose>
<guidelines>...</guidelines>
<implementation>...</implementation>
</skill>
<skill name="skill-two">
<purpose>...</purpose>
<guidelines>...</guidelines>
<implementation>...</implementation>
</skill>
`

const result = Skill.parse(source)
// result.length === 2
// result[0].skill.name === 'skill-one'
// result[1].skill.name === 'skill-two'

Custom root attributes

Any attribute on the <skill> root tag is preserved as-is. Kebab-case is kept intact.

const source = `
<skill name="changelog-writer" self-invoked="true" license="MIT" version="1.0">
<purpose>...</purpose>
<guidelines>...</guidelines>
<implementation>...</implementation>
</skill>
`

const [parsed] = Skill.parse(source)
console.log(parsed.skill)
// { name: 'changelog-writer', 'self-invoked': 'true', license: 'MIT', version: '1.0' }

Error handling

The parser throws on structural problems so callers know exactly where the issue is.

try {
  Skill.parse('not a skill document')
} catch (error) {
  // SyntaxError: missing <skill> element
}

try {
  Skill.parse('<skill name="a"><skill name="nested"></skill></skill>')
} catch (error) {
  // SyntaxError: nested <skill> element
}

try {
  Skill.parse('<skill name="a"><purpose>x</purpose>')
} catch (error) {
  // SyntaxError: unclosed <skill> element
}

See SPECIFICATION.md for the full specification and AGENTS.md for integration guidance when embedding the parser into agent tooling.

Build and Test

Note

Prerequisites: Deno for all development tasks.

Check - format, lint, and typecheck source:

deno task check

Unit tests - run all tests:

deno task test

Build - produce the npm distribution:

npm run build

Acknowledgements

Based on the upstream Agent Skills specification, reworked into a frontmatter-free, XML-mixed Markdown variant with strict section ordering and recommended word-count guidance. The XML-mixed body layout follows Anthropic's guidance in Use XML tags to structure your prompts, which recommends wrapping distinct prompt parts in XML tags so downstream models can parse them reliably.

License

Code in this repository is licensed under Apache 2.0, documentation is licensed under CC-BY-4.0.