Skip to main content

Skills (SKILL.md)

AgentOS supports skills: modular prompt modules defined by a SKILL.md file.

Skills are intended to complement tools/extensions:

  • Tools are atomic operations (ITool) that the runtime can execute.
  • Skills are higher-level instructions/workflows injected into the agent’s prompt.

File format​

Each skill lives in its own folder containing SKILL.md:

---
name: github
description: Use the GitHub CLI (gh) for issues, PRs, and repos.
metadata:
  agentos:
    emoji: "🐙"
    primaryEnv: GITHUB_TOKEN
    requires:
      bins: ["gh"]
    install:
      - id: brew
        kind: brew
        formula: gh
        bins: ["gh"]
---

# GitHub (gh CLI)

Use the `gh` CLI to interact with GitHub repositories.

Runtime API​

Load skills from one or more directories:

import { SkillRegistry } from '@framers/agentos/cognition/skills';

const registry = new SkillRegistry();
await registry.loadFromDirs(['./skills']);

const snapshot = registry.buildSnapshot({ platform: process.platform });
console.log(snapshot.prompt);

Source: SkillRegistry, SkillLoader.

Each skill is a folder of its own in a skills directory, and its SKILL.md is a regular file. The loader reads SKILL.md never through a symbolic link at the skill's folder or below it, and never waits on a named pipe: a skill folder that is a link, and a SKILL.md that is a link or not a regular file, are skipped with a warning. The skills directory itself may be a link.

With buildSnapshot({ strict: true }), the binaries a skill requires (requires.bins, requires.anyBins) are looked for in the folders on PATH. Each is named by one file name: a name such as ../bin/tool or .tool, which holds a slash or starts with a dot, counts as missing, with a warning, and no folder is looked at for it.

Curated registry (optional)​

The curated content holds 88 skills spanning developer tools, productivity, information, communication, memory, social media, and voice. See @framers/agentos-skills/registry.json for the canonical list and registry/curated/ for the SKILL.md content.

@framers/agentos-skills-registry supports two usage modes:

Agents can discover curated skills via the Capability Discovery Engine (@framers/agentos/discovery), which indexes them as CapabilityDescriptor entries with kind: 'skill'. The skills_list, skills_read, skills_enable, skills_status and skills_install tools come from the @framers/agentos-ext-skills extension pack, not from SkillRegistry, which loads skills and builds the prompt snapshot. Curated skill content (the SKILL.md files) ships in @framers/agentos-skills.

Agentic discovery​

Skills are discoverable at runtime via: