Documentation

Skill Kit

Unified skill format using Markdown + YAML frontmatter, with loader and prompt assembly utilities.

A unified skill format and toolkit for managing agent prompts. Define skills as Markdown files with YAML frontmatter, load them from disk, filter by mode, and assemble into system prompts — with built-in multi-language support.

npm install @eir-open/skill-kit

Features

Markdown Format

Define skills as readable SKILL.md files with YAML frontmatter — no JSON schemas or code needed.

Mode Filtering

Each skill declares which modes it applies to. Filter skills per-mode at runtime.

Multi-Language

Support multiple languages per skill with SKILL.sv.md, SKILL.fr.md, etc. Automatic fallback to default.

Prompt Assembly

Concatenate filtered skill prompts into a single system prompt with one function call.

SKILL.md Format

Each skill lives in its own directory as a SKILL.md file with YAML frontmatter:

---
name: base-personality
description: Core role and tone for a health agent
modes: [general, assessment]
requiredTools: []
languages: [en]
---

# Base Personality

You are a helpful health assistant. You provide general health information
and support.

## Guidelines

- Be empathetic and clear
- Always recommend consulting a healthcare provider
- Use available tools when helpful
- Keep responses concise and actionable

Frontmatter Schema

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Unique skill identifier
`description`	`string`	No	—	Human-readable description
`modes`	`string[]`	No	`[]`	Modes this skill applies to (empty = all modes)
`requiredTools`	`string[]`	No	`[]`	Tools this skill expects to be available
`languages`	`string[]`	No	`['en']`	Supported language codes

Multi-Language Skills

Add language-specific variants alongside the main file:

skills/
  base-personality/
    SKILL.md          ← English (default)
    SKILL.sv.md       ← Swedish
    SKILL.fr.md       ← French

Language variants contain only the translated prompt body — no frontmatter needed.

Loading Skills

`loadSkill`

Load a single skill from a directory:

import { loadSkill } from '@eir-open/skill-kit';

const skill = await loadSkill('./skills/base-personality');
// skill.meta.name → 'base-personality'
// skill.prompts['en'] → '# Base Personality\n...'
// skill.prompts['sv'] → Swedish translation (if SKILL.sv.md exists)

Returns null if the directory doesn’t contain a valid skill.

`loadSkillDirectory`

Load all skills from a parent directory:

import { loadSkillDirectory } from '@eir-open/skill-kit';

const skills = await loadSkillDirectory('./skills');
// Map<string, LoadedSkill> keyed by skill name

for (const [name, skill] of skills) {
  console.log(`${name}: ${skill.meta.description}`);
}

Recursively discovers skill subdirectories and returns a Map keyed by skill.meta.name.

Filtering and Assembly

`getSkillsForMode`

Filter skills to those applicable to a specific mode:

import { getSkillsForMode } from '@eir-open/skill-kit';

const allSkills = await loadSkillDirectory('./skills');
const generalSkills = getSkillsForMode(allSkills, 'general');
// Returns skills where modes[] includes 'general' OR modes is empty

Skills with an empty modes array apply to all modes.

`buildSkillPrompt`

Assemble filtered skills into a single prompt string:

import { buildSkillPrompt } from '@eir-open/skill-kit';

const prompt = buildSkillPrompt(generalSkills, 'en');
// Concatenates all skill prompts with double newlines
// Falls back: requested language → 'default' → first available

Parsing

`parseSkillMarkdown`

Parse a SKILL.md string into metadata and body:

import { parseSkillMarkdown } from '@eir-open/skill-kit';

const content = fs.readFileSync('./skills/base-personality/SKILL.md', 'utf-8');
const { meta, body } = parseSkillMarkdown(content);
// meta → { name, description, modes, requiredTools, languages }
// body → markdown content after frontmatter

Types

interface SkillMeta {
  name: string;
  description?: string;
  modes: string[];
  requiredTools: string[];
  languages: string[];
}

interface LoadedSkill {
  meta: SkillMeta;
  prompts: Record<string, string>;  // language code → prompt text
  path: string;                     // filesystem path
}

Example: Full Integration

import { loadSkillDirectory, getSkillsForMode, buildSkillPrompt } from '@eir-open/skill-kit';
import { executeToolLoop, buildSystemContent, buildModeToolInstruction } from '@eir-open/agent-core';

// Load all skills
const skills = await loadSkillDirectory('./skills');

// Filter to current mode
const modeSkills = getSkillsForMode(skills, 'general');

// Build system prompt
const system = buildSystemContent([
  buildSkillPrompt(modeSkills, 'en'),
  buildModeToolInstruction({ mode: 'general', toolNames: ['greet_user'] }),
]);

// Run the agent
const result = await executeToolLoop({
  provider,
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: system },
    { role: 'user', content: 'Hello!' },
  ],
  tools,
  toolHandlers,
});