@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

Package	Role
@framers/agentos-skills	Content — 88 SKILL.md files + registry.json
@framers/agentos-skills-registry	Catalog SDK — query helpers, lazy loaders, factories
@framers/agentos	Engine — SkillLoader, SkillRegistry, SkillSnapshot

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

Package	Role	What	Runtime Code	Dependencies
@framers/agentos/skills	Engine	SkillLoader, SkillRegistry, path utils	Yes	yaml
@framers/agentos-skills	Content	88 SKILL.md files + registry.json index	No	None
@framers/agentos-skills-registry	Catalog SDK	SKILLS_CATALOG, query helpers, lazy loaders, factories	Yes	agentos-skills, yaml

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

Entry Point	What	Peer Deps
@framers/agentos-skills-registry	Full API: catalog + factories + workspace discovery	@framers/agentos (optional)
@framers/agentos-skills-registry/catalog	SKILLS_CATALOG, query helpers, lazy loaders	None
@framers/agentos-skills-registry/workspace-discovery	Workspace skill scanning + merging	None

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

Guide	What
Contributing	Development setup, commit and pull request rules, review threads, contribution licensing
Release guide	How the daily release (10:17 UTC) publishes merged changes to npm, and how to release now
Agent instructions	Commands and conventions for coding agents
Code of Conduct	Community standards
Security Policy	Reporting vulnerabilities privately
Support	Where to get help

License

Apache 2.0 — see LICENSE.