@framers/agentos-skills-registry

Catalog SDK for querying and loading AgentOS skills.

npm install @framers/agentos-skills-registry

For the skill content (SKILL.md files), see @framers/agentos-skills.

Ecosystem

This layout mirrors the extensions ecosystem: @framers/agentos-extensions (content) + @framers/agentos-extensions-registry (SDK).

Quick Start

1. Browse the catalog (zero peer deps)

import {
  SKILLS_CATALOG,
  searchSkills,
  getSkillsByCategory,
  getSkillByName,
} from '@framers/agentos-skills-registry/catalog';

// Full-text search
const matches = searchSkills('github');
console.log(matches.map((s) => `${s.name}: ${s.description}`));

// By category
const devSkills = getSkillsByCategory('developer');
console.log(`${devSkills.length} developer skills`);

// By name
const gh = getSkillByName('github');
console.log(gh?.requiredSecrets); // ['github.token']

2. Lazy-load a skill on demand

import { loadSkillByName } from '@framers/agentos-skills-registry';

const skill = await loadSkillByName('github');
if (skill) {
  console.log(skill.content); // SKILL.md body for prompt injection
  console.log(skill.metadata?.emoji); // "octopus"
}

3. Build a SkillSnapshot (requires @framers/agentos)

import { createCuratedSkillSnapshot } from '@framers/agentos-skills-registry';

const snapshot = await createCuratedSkillSnapshot({
  skills: ['github', 'web-search', 'notion'],
  platform: 'darwin',
});

// Inject into agent prompt
console.log(snapshot.prompt);

4. Workspace skill discovery

import {
  discoverWorkspaceSkills,
  mergeWithWorkspaceSkills,
  SKILLS_CATALOG,
} from '@framers/agentos-skills-registry';

// Scan .agents/skills/ for workspace-local skills
const workspace = await discoverWorkspaceSkills();

// Merge with curated (workspace takes priority on name collision)
const merged = mergeWithWorkspaceSkills(SKILLS_CATALOG, workspace);

Discovery does not follow symbolic links below the skills folder. A skill folder or a SKILL.md that is a link, or a SKILL.md that is not a regular file, is skipped with a warning, and each discovered skill's loadSkill() reads its file the same way.

Sub-exports

API Reference

Catalog Queries

• SKILLS_CATALOG -- Sorted array of all curated + community skill entries
• searchSkills(query) -- Full-text search across names, descriptions, tags
• getSkillsByCategory(category) -- Filter by category
• getSkillByName(name) -- Single skill lookup
• getAvailableSkills(installedTools) -- Filter by available tools
• getCategories() -- List unique categories
• getSkillsByTag(tag) -- Filter by tag
• getCuratedSkills() / getCommunitySkills() / getAllSkills() -- Source filters
• getSkillEntries(names) -- Filter by name list ('all' | 'none' | string[])

Lazy Loading

• loadSkillByName(name) -- Load and parse a single SKILL.md by name
• loadSkillsByNames(names) -- Parallel load multiple skills
• createLocalSkillProxy(relativePath, displayName) -- Factory for lazy loading

Factory Functions (requires @framers/agentos)

• createCuratedSkillRegistry(options?) -- Create a live SkillRegistry with selected curated skills
• createCuratedSkillSnapshot(options?) -- Build a SkillSnapshot ready for prompt injection

Path Helpers

• getBundledCuratedSkillsDir() -- Absolute path to @framers/agentos-skills/registry/curated/
• getBundledCommunitySkillsDir() -- Absolute path to @framers/agentos-skills/registry/community/

Workspace Discovery

• discoverWorkspaceSkills(options?) -- Scan .agents/skills/ for workspace-local skills, without following symbolic links below it
• mergeWithWorkspaceSkills(registry, workspace) -- Merge with priority to workspace
• parseSkillFrontmatter(content) -- Parse YAML frontmatter from skill content

Contributing and support

License

Apache 2.0 — see LICENSE.