@framers/agentos-skills-registry 0.2.0 → 0.3.0

package/CONTRIBUTING.md

@@ -0,0 +1,231 @@
+# Contributing to @framers/agentos-skills-registry
+
+Thank you for your interest in contributing a skill to the AgentOS ecosystem! This guide walks you through the process of creating, testing, and submitting a new skill.
+
+## Overview
+
+Skills are **SKILL.md files** — each containing YAML frontmatter (metadata) and a markdown body (instructions for the AI agent). They live inside the `@framers/agentos-skills-registry` package alongside the typed SDK. There are no individual packages per skill.
+
+Skills are organized into two tiers:
+
+| Tier          | Directory             | Namespace    | Maintained By               | Verified |
+| ------------- | --------------------- | ------------ | --------------------------- | -------- |
+| **Curated**   | `registry/curated/`   | `wunderland` | Framers staff               | Yes      |
+| **Community** | `registry/community/` | `community`  | Original author / community | No       |
+
+Curated skills ship pre-verified and are maintained by the Framers team. Community skills are submitted via pull request by anyone and are maintained by their authors.
+
+## Creating a New Skill
+
+### Step 1 — Fork the repo
+
+Fork [framersai/agentos-skills-registry](https://github.com/framersai/agentos-skills-registry) and clone it locally.
+
+```bash
+git clone https://github.com/<your-username>/agentos-skills-registry.git
+cd agentos-skills-registry
+```
+
+### Step 2 — Create the skill directory
+
+Create a new directory under `registry/community/` with your skill name. The directory name must be lowercase, use hyphens for separators, and match the `name` field in your frontmatter.
+
+```bash
+mkdir -p registry/community/my-skill
+```
+
+### Step 3 — Write the SKILL.md file
+
+Create `registry/community/my-skill/SKILL.md` with two parts:
+
+1. **YAML frontmatter** between `---` delimiters containing metadata
+2. **Markdown body** containing instructions for the AI agent
+
+The markdown body should be written in **2nd person** ("You can...", "Use the...") because it is injected directly into an agent's system prompt.
+
+### Step 4 — Write the YAML frontmatter
+
+Fill in all required fields. See the [SKILL.md Format Reference](#skillmd-format-reference) below for the complete spec.
+
+### Step 5 — Write the markdown body
+
+The body is the actual instructions the AI agent will follow. It should include:
+
+- A heading with the skill name
+- A description of what the skill enables the agent to do
+- Step-by-step guidance for how the agent should use the skill
+- An **Examples** section with concrete usage examples
+- A **Constraints** section documenting limitations
+
+### Step 6 — Validate your skill
+
+```bash
+npm run validate registry/community/my-skill/SKILL.md
+```
+
+## SKILL.md Format Reference
+
+### Required Fields
+
+| Field         | Type   | Description                                                                |
+| ------------- | ------ | -------------------------------------------------------------------------- |
+| `name`        | string | Skill identifier. Must match the directory name. Lowercase, hyphens only.  |
+| `version`     | string | Semantic version (e.g., `'1.0.0'`). Quote it to avoid YAML parsing issues. |
+| `description` | string | Short description, under 200 characters.                                   |
+| `author`      | string | Your name or GitHub username.                                              |
+| `namespace`   | string | Must be `community` for community submissions.                             |
+| `category`    | string | One of the valid categories listed below.                                  |
+| `tags`        | array  | At least one tag. Use lowercase, hyphenated strings.                       |
+
+### Optional Fields
+
+| Field                       | Type   | Description                                                               |
+| --------------------------- | ------ | ------------------------------------------------------------------------- |
+| `requires_secrets`          | array  | Secret keys the skill needs (e.g., `[service.token]`). Use `[]` if none.  |
+| `requires_tools`            | array  | Tool names the skill depends on (e.g., `[web-search]`). Use `[]` if none. |
+| `metadata.agentos.emoji`    | string | Emoji icon for the skill in UIs.                                          |
+| `metadata.agentos.homepage` | string | URL to the skill's related service or docs.                               |
+
+### Valid Categories
+
+- `automation` — Workflow automation, orchestration, repetitive task handling
+- `communication` — Chat, email, messaging platforms
+- `content` — Content planning, drafting, publishing pipelines
+- `creative` — Art, writing, design, generation
+- `developer-tools` — Code, repos, CI/CD, debugging
+- `devops` — Operational tooling, monitoring, reliability checks
+- `information` — Data lookup, search, knowledge retrieval
+- `infrastructure` — Infrastructure provisioning, hosting, deployment workflows
+- `marketing` — SEO, campaigns, growth workflows
+- `media` — Audio, video, image, streaming
+- `productivity` — Note-taking, task management, organization
+- `research` — Multi-source investigation and synthesis
+- `security` — Passwords, encryption, access control
+- `social-automation` — Social publishing, engagement, and channel management
+
+### Full Template
+
+Copy and paste this into `registry/community/<your-skill>/SKILL.md`:
+
+```markdown
+---
+name: my-skill
+version: '1.0.0'
+description: A short description of what this skill does (under 200 characters).
+author: your-github-username
+namespace: community
+category: information
+tags: [example, template]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F527"
+    homepage: https://example.com
+---
+
+# My Skill
+
+You can use this skill to [describe what the agent can do]. When the user asks about [topic], you should [describe the agent's behavior].
+
+Provide clear, structured responses. If the user's request is ambiguous, ask for clarification before proceeding.
+
+## Examples
+
+- "Example user query 1"
+- "Example user query 2"
+- "Example user query 3"
+
+## Constraints
+
+- Limitation or caveat 1.
+- Limitation or caveat 2.
+- Limitation or caveat 3.
+```
+
+## Testing Your Skill
+
+Run the validation script against your SKILL.md file:
+
+```bash
+npm run validate registry/community/my-skill/SKILL.md
+```
+
+The validator checks:
+
+- All required frontmatter fields are present
+- Category is valid
+- Description is under 200 characters
+- Tags array has at least one entry
+- Namespace is `community` or `wunderland`
+- Skill name matches the directory name
+- Markdown body is not empty
+- No obvious secrets or API keys are embedded in the file
+
+Fix any reported issues before submitting your PR.
+
+## Submitting a PR
+
+### 1. Create a branch
+
+```bash
+git checkout -b add-skill/my-skill
+```
+
+### 2. Commit your SKILL.md
+
+```bash
+git add registry/community/my-skill/SKILL.md
+git commit -m "feat: add my-skill community skill"
+```
+
+### 3. Push and open a PR
+
+```bash
+git push origin add-skill/my-skill
+```
+
+Open a pull request against the `main` branch. The PR template will guide you through the checklist.
+
+### PR Checklist
+
+Before submitting, confirm:
+
+- [ ] Skill is in `registry/community/<name>/SKILL.md`
+- [ ] All required YAML fields are present
+- [ ] `namespace` is set to `community`
+- [ ] Category is one of the 8 valid categories
+- [ ] Description is under 200 characters
+- [ ] Markdown body includes usage instructions, Examples, and Constraints
+- [ ] No secrets, API keys, or credentials are in the file
+- [ ] `npm run validate` passes
+
+### What Reviewers Look For
+
+- **Quality**: Is the skill well-written? Are instructions clear and actionable?
+- **No secrets**: The file must not contain API keys, tokens, passwords, or credentials.
+- **Valid format**: Frontmatter must parse correctly with all required fields.
+- **Usefulness**: Does the skill provide value that is not already covered by an existing skill?
+- **Specificity**: Is the scope well-defined? Skills should do one thing well.
+
+## Promotion to Curated
+
+Community skills can be promoted to the curated tier. Promotion criteria:
+
+1. **Longevity** — The skill has been in `registry/community/` for at least 3 months.
+2. **Positive feedback** — The skill has received positive user feedback or adoption.
+3. **Maintained** — The original author is responsive to issues and keeps the skill up to date.
+4. **Staff review** — A Framers team member reviews the skill for quality and completeness.
+
+When a skill is promoted:
+
+- It moves from `registry/community/<name>/` to `registry/curated/<name>/`.
+- The `namespace` field changes from `community` to `wunderland`.
+- The `verified` flag is set to `true` in `registry.json`.
+- The Framers team assumes co-maintenance responsibility.
+
+To nominate a community skill for promotion, open an issue titled "Promote: <skill-name>" with a brief justification.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you agree to uphold this code. Please report unacceptable behavior to [team@frame.dev](mailto:team@frame.dev).

package/README.md

@@ -1,6 +1,12 @@
+<p align="center">
+  <a href="https://agentos.sh"><img src="logos/agentos-primary-no-tagline-transparent-2x.png" alt="AgentOS" height="56" /></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://frame.dev"><img src="logos/frame-logo-green-no-tagline.svg" alt="Frame.dev" height="36" /></a>
+</p>
+
 # @framers/agentos-skills-registry
 
-Curated skills registry bundle for [AgentOS](https://github.com/framersai/agentos) — lazy-loading DI of SKILL.md prompt modules.
+Curated skills registry for [AgentOS](https://github.com/framersai/agentos) — 40 SKILL.md prompt modules, typed catalog, and lazy-loading factories.
 
 [![npm](https://img.shields.io/npm/v/@framers/agentos-skills-registry?logo=npm&color=cb3837)](https://www.npmjs.com/package/@framers/agentos-skills-registry)
 
@@ -10,17 +16,19 @@ npm install @framers/agentos-skills-registry
 
 ## What's Inside
 
-This package is the **typed SDK** on top of [`@framers/agentos-skills`](https://www.npmjs.com/package/@framers/agentos-skills). It provides:
+This is the **single package** for AgentOS skills. It contains:
 
-- **Static catalog** (`SKILLS_CATALOG`) — typed array of all 16+ curated skills with metadata
-- **Query helpers** — `searchSkills()`, `getSkillsByCategory()`, `getSkillsByTag()`, `getAvailableSkills()`, etc.
+- **40 curated SKILL.md files** — prompt modules spanning social automation, developer tooling, productivity, research, voice, and more
+- **registry.json** — machine-readable index of all skills with metadata
+- **Static catalog** (`SKILLS_CATALOG`) — typed array with query helpers
 - **Registry factories** — `createCuratedSkillRegistry()`, `createCuratedSkillSnapshot()` (requires `@framers/agentos`)
+- **Validation script** — `npm run validate` to lint SKILL.md files
 
-## Two Import Paths
+## Quick Start
 
-### Lightweight (zero peer deps)
+### 1. Browse the catalog (zero peer deps)
 
-The `./catalog` sub-export works standalone — no `@framers/agentos` needed:
+The `./catalog` sub-export has no peer dependencies:
 
 ```typescript
 import {
@@ -33,23 +41,46 @@ import {
   getSkillsByTag,
 } from '@framers/agentos-skills-registry/catalog';
 
-// Search
+// Search across names, descriptions, and tags
 const matches = searchSkills('github');
 
 // Filter by category
-const devTools = getSkillsByCategory('developer-tools');
+const social = getSkillsByCategory('social-automation');
 
 // Filter by installed tools
 const available = getAvailableSkills(['web-search', 'filesystem']);
 
-// All categories
+// Get a specific skill
+const github = getSkillByName('github');
+console.log(github?.requiredSecrets); // ['github.token']
+
+// All unique categories
 const categories = getCategories();
-// ['communication', 'creative', 'developer-tools', 'devops', 'information', ...]
+// ['automation', 'communication', 'creative', 'developer-tools', 'social-automation', ...]
+```
+
+### 2. Load raw registry data
+
+Access the JSON index directly:
+
+```typescript
+import { getSkillsCatalog } from '@framers/agentos-skills-registry';
+
+const catalog = await getSkillsCatalog();
+console.log(catalog.skills.curated.length); // 40
+console.log(catalog.version); // '1.0.0'
 ```
 
-### Full registry (requires @framers/agentos)
+Or import the raw JSON:
 
-The factory functions lazy-load `@framers/agentos` via `dynamic import()` — only resolved when called:
+```typescript
+import registry from '@framers/agentos-skills-registry/registry.json';
+console.log(registry.skills.curated[0].name); // 'weather'
+```
+
+### 3. Dynamically load skills into an agent (requires @framers/agentos)
+
+The factory functions lazy-load `@framers/agentos` via dynamic `import()`:
 
 ```bash
 npm install @framers/agentos-skills-registry @framers/agentos
@@ -59,77 +90,143 @@ npm install @framers/agentos-skills-registry @framers/agentos
 import {
   createCuratedSkillRegistry,
   createCuratedSkillSnapshot,
+  getBundledCuratedSkillsDir,
+  loadSkillByName,
 } from '@framers/agentos-skills-registry';
 
-// Create a live SkillRegistry loaded with all curated skills
+// Option A: Create a live SkillRegistry loaded with all curated skills
 const registry = await createCuratedSkillRegistry();
-console.log(registry.size); // 16+
 
-// Build a prompt snapshot for agent injection
+// Or load only a specific curated subset
+const selectedRegistry = await createCuratedSkillRegistry({
+  skills: ['github', 'weather'],
+});
+
+// Option B: Build a prompt snapshot for specific skills
 const snapshot = await createCuratedSkillSnapshot({
   skills: ['github', 'weather', 'notion'], // or 'all'
   platform: 'darwin',
 });
-console.log(snapshot.prompt); // Formatted markdown for the LLM
-```
 
-If `@framers/agentos` is not installed and you call a factory function, you get a clear error:
+// Only the selected skills are loaded when you pass an explicit list.
+console.log(snapshot.skills.map((skill) => skill.name));
+// ['github', 'weather', 'notion']
+
+// Inject the snapshot prompt into your agent's system message
+const systemPrompt = `You are an AI assistant.\n\n${snapshot.prompt}`;
+
+// Option C: Load a single SKILL.md lazily with parsed metadata
+const githubSkill = await loadSkillByName('github');
+console.log(githubSkill?.metadata?.primaryEnv); // 'GITHUB_TOKEN'
+console.log(githubSkill?.frontmatter.requires_tools); // ['filesystem']
 
+// Option D: Get the directory path and load manually
+const skillsDir = getBundledCuratedSkillsDir();
+// → '/path/to/node_modules/@framers/agentos-skills-registry/registry/curated'
 ```
-Error: @framers/agentos is required for createCuratedSkillRegistry() and
-createCuratedSkillSnapshot().  Install it:
 
-  npm install @framers/agentos
+### 4. Dynamic skill resolution in Wunderland presets
 
-Or use the lightweight catalog helpers (getSkillsByCategory, searchSkills, etc.)
-which have no peer-dep requirement.
+```typescript
+// In agent.config.json:
+// { "suggestedSkills": ["github", "web-search", "notion"] }
+
+import { getSkillByName } from '@framers/agentos-skills-registry/catalog';
+import { createCuratedSkillSnapshot } from '@framers/agentos-skills-registry';
+
+// Validate skill names exist before loading
+const skillNames = ['github', 'web-search', 'notion'];
+const valid = skillNames.filter((name) => {
+  const entry = getSkillByName(name);
+  if (!entry) {
+    console.warn(`Unknown skill "${name}", skipping`);
+    return false;
+  }
+  return true;
+});
+
+// Build snapshot with only validated skills
+const snapshot = await createCuratedSkillSnapshot({ skills: valid });
 ```
 
-## Lazy Loading
+When `skills` is a string array, the registry only loads those specific `SKILL.md`
+files before building the snapshot. It does not walk the full curated bundle first.
+Loaded skills also include parsed `metadata` so consumers do not need to decode
+the `metadata.agentos` block manually.
+
+## Two Import Paths
 
-The `@framers/agentos` dependency is loaded **lazily** at runtime via dynamic `import()` and cached after first resolution. This means:
+| Import | Peer deps | Use case |
+|--------|-----------|----------|
+| `@framers/agentos-skills-registry/catalog` | None | UI browsing, search, filtering |
+| `@framers/agentos-skills-registry` | `@framers/agentos` (optional) | Runtime loading, snapshots, factories |
 
-- `import { searchSkills } from '@framers/agentos-skills-registry/catalog'` — **zero** peer deps loaded
-- `import { createCuratedSkillRegistry } from '@framers/agentos-skills-registry'` — `@framers/agentos` loaded **only when called**
+The `@framers/agentos` dependency is loaded **lazily** at runtime and cached after first resolution. If it's not installed and you call a factory function, you get a clear error with install instructions.
+
+## Included Skills (40)
+
+The catalog now includes both foundational utility skills and social automation modules, including:
+
+- Information and research: `web-search`, `weather`, `summarize`, `deep-research`
+- Developer tools: `github`, `coding-agent`, `git`
+- Productivity: `notion`, `obsidian`, `trello`, `apple-notes`, `apple-reminders`
+- Social automation: `social-broadcast`, `twitter-bot`, `instagram-bot`, `linkedin-bot`, `facebook-bot`, `threads-bot`, `bluesky-bot`, `mastodon-bot`, `youtube-bot`, `tiktok-bot`, `pinterest-bot`, `reddit-bot`, `blog-publisher`
+- Additional categories: `automation`, `communication`, `devops`, `media`, `marketing`, `creative`, `security`
 
 ## Community Skills
 
-The catalog includes both **curated** (staff-maintained) and **community** (PR-submitted) skills. Use the source-aware helpers to filter by origin:
+The catalog supports both **curated** (staff-maintained) and **community** (PR-submitted) skills:
 
 ```typescript
-import {
-  getCuratedSkills,
-  getCommunitySkills,
-  getAllSkills,
-} from '@framers/agentos-skills-registry/catalog';
+import { getCuratedSkills, getCommunitySkills } from '@framers/agentos-skills-registry/catalog';
+
+const curated = getCuratedSkills();   // Staff-verified skills
+const community = getCommunitySkills(); // Community-contributed
+```
 
-// Only staff-maintained, verified skills
-const curated = getCuratedSkills();
+Each entry includes a `source` field (`'curated'` or `'community'`) for provenance filtering.
 
-// Only community-contributed skills
-const community = getCommunitySkills();
+## Schema Types
 
-// Everything (curated + community)
-const all = getAllSkills();
+Import registry.json schema types for type-safe access:
 
-// Combine with existing filters
-import { getSkillsByCategory } from '@framers/agentos-skills-registry/catalog';
+```typescript
+import type {
+  SkillRegistryEntry,
+  SkillsRegistry,
+  SkillInstallSpec,
+  SkillMetadata,
+} from '@framers/agentos-skills-registry';
 
-const devTools = getSkillsByCategory('developer-tools');
-const curatedDevTools = devTools.filter((s) => s.source === 'curated');
-const communityDevTools = devTools.filter((s) => s.source === 'community');
+// SkillRegistryEntry — shape of entries in registry.json
+// SkillsRegistry — shape of the full registry.json file
+// SkillInstallSpec — install instructions for skill dependencies
 ```
 
-Each skill entry includes a `source` field (`'curated'` or `'community'`) so you can distinguish provenance at runtime.
+## Exports
+
+| Export path | Contents |
+|-------------|----------|
+| `.` | Full SDK: catalog helpers + factory functions + schema types |
+| `./catalog` | Lightweight: `SKILLS_CATALOG`, query helpers (zero peer deps) |
+| `./registry.json` | Raw JSON index of all skills |
+| `./types` | TypeScript declarations for registry.json schema |
 
 ## Relationship to Other Packages
 
 ```
-@framers/agentos-skills              (data: SKILL.md files + JSON index)
-  └── @framers/agentos-skills-registry   ← You are here (SDK: typed queries + factories)
-        └── @framers/agentos             (optional peer: live SkillRegistry + snapshots)
+@framers/agentos-skills-registry     ← This package (data + SDK)
+  ├── registry/curated/*/SKILL.md    (bundled prompt modules)
+  ├── registry.json                  (machine-readable index)
+  ├── catalog.ts                     (typed queries: search, filter, browse)
+  └── index.ts                       (factories: lazy-load @framers/agentos)
+        └── @framers/agentos         (optional peer: live SkillRegistry + snapshots)
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to submit new skills.
+
 ## License
 
 MIT

package/dist/catalog.d.ts

@@ -2,10 +2,53 @@
  * @fileoverview Curated Skills Catalog for AgentOS
  * @module @framers/agentos-skills-registry/catalog
  *
- * Statically-typed catalog of all curated skills with metadata for
- * programmatic discovery, filtering by category/tag, and tool-based
- * availability checks.
+ * Programmatic catalog derived from registry.json so it stays in sync with
+ * bundled SKILL.md entries.
+ *
+ * Pattern mirrors `@framers/agentos-extensions-registry/tool-registry`:
+ *   - `SKILLS_CATALOG` array with metadata + lazy `loadSkill` factory
+ *   - `createLocalSkillProxy()` for lazy-loading from local paths
+ *   - `loadSkillByName()` for on-demand loading by name
+ */
+import type { SkillMetadata } from './schema-types.js';
+/**
+ * Result of loading a skill via its `loadSkill()` factory.
+ *
+ * Contains the parsed SKILL.md content, frontmatter, and body text — everything
+ * needed to inject the skill into an agent's prompt context.
  */
+export interface LoadedSkill {
+    /** Skill name */
+    name: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Brief description */
+    description: string;
+    /** Full SKILL.md body content (after frontmatter) */
+    content: string;
+    /** Raw parsed frontmatter key/value pairs */
+    frontmatter: LoadedSkillFrontmatter;
+    /** Parsed metadata extracted from frontmatter (when available) */
+    metadata?: SkillMetadata;
+    /** Absolute path to the SKILL.md file that was loaded */
+    sourcePath: string;
+}
+export interface LoadedSkillFrontmatter extends Record<string, unknown> {
+    name?: string;
+    version?: string;
+    description?: string;
+    author?: string;
+    namespace?: string;
+    category?: string;
+    tags?: string[];
+    requires_secrets?: string[];
+    requires_tools?: string[];
+    metadata?: unknown;
+    userInvocable?: boolean | string;
+    'user-invocable'?: boolean | string;
+    disableModelInvocation?: boolean | string;
+    'disable-model-invocation'?: boolean | string;
+}
 export interface SkillCatalogEntry {
     /** Unique skill name (matches directory name under registry/curated/) */
     name: string;
@@ -21,13 +64,35 @@ export interface SkillCatalogEntry {
     requiredSecrets: string[];
     /** Tool identifiers the skill depends on (e.g. 'web-search', 'filesystem') */
     requiredTools: string[];
-    /** Relative path from the agentos-skills package root to the SKILL.md */
+    /** Relative path from the package root to the SKILL.md */
     skillPath: string;
     /** Skill source: curated (staff-maintained) or community-submitted */
     source?: 'curated' | 'community';
-    /** All curated skills are in the wunderland namespace */
-    namespace: 'wunderland';
+    /** Namespace used by the skill registry */
+    namespace: string;
+    /** Whether this skill is available (SKILL.md exists on disk). Always true for bundled skills. */
+    available: boolean;
+    /**
+     * Lazy factory function that loads and parses the SKILL.md on demand.
+     *
+     * Mirrors the `createPack` pattern from `@framers/agentos-extensions-registry`.
+     * Returns parsed skill content including frontmatter and body text.
+     */
+    loadSkill: () => Promise<LoadedSkill>;
 }
+export declare function extractLoadedSkillMetadata(frontmatter: LoadedSkillFrontmatter): SkillMetadata | undefined;
+export declare function loadSkillFromAbsolutePath(absolutePath: string, displayName: string): Promise<LoadedSkill>;
+/**
+ * Create a lazy-loading skill proxy for a relative SKILL.md path.
+ *
+ * Mirrors `createLocalPackProxy()` from the extensions-registry: the SKILL.md
+ * is only read and parsed when the returned function is called.
+ *
+ * @param relativePath - Path from the package root to the SKILL.md file
+ *                       (e.g. 'registry/curated/github/SKILL.md')
+ * @param displayName  - Human-readable display name for the loaded skill
+ */
+export declare function createLocalSkillProxy(relativePath: string, displayName: string): () => Promise<LoadedSkill>;
 export declare const SKILLS_CATALOG: SkillCatalogEntry[];
 /**
  * Get all skills in a given category.
@@ -67,4 +132,38 @@ export declare function getCommunitySkills(): SkillCatalogEntry[];
  * Get all skills (curated + community). Alias for SKILLS_CATALOG.
  */
 export declare function getAllSkills(): SkillCatalogEntry[];
+/**
+ * Get skill entries filtered by name.
+ *
+ * Mirrors `getToolEntries()` from the extensions-registry.
+ */
+export declare function getSkillEntries(names?: string[] | 'all' | 'none'): SkillCatalogEntry[];
+/**
+ * Load a skill by name from the catalog.
+ *
+ * Finds the entry in SKILLS_CATALOG and calls its `loadSkill()` factory to
+ * read and parse the SKILL.md file on demand. Returns `null` if the skill
+ * is not found in the catalog.
+ *
+ * This is the primary consumer-facing API for lazy skill loading, mirroring
+ * how the extensions-registry resolves and loads extension packs.
+ *
+ * @example
+ * ```typescript
+ * import { loadSkillByName } from '@framers/agentos-skills-registry';
+ *
+ * const skill = await loadSkillByName('github');
+ * if (skill) {
+ *   console.log(skill.content); // SKILL.md body for injection into prompt
+ * }
+ * ```
+ */
+export declare function loadSkillByName(name: string): Promise<LoadedSkill | null>;
+/**
+ * Load multiple skills by name from the catalog.
+ *
+ * Convenience wrapper that calls `loadSkillByName()` for each name in parallel.
+ * Silently skips skills that are not found in the catalog.
+ */
+export declare function loadSkillsByNames(names: string[]): Promise<LoadedSkill[]>;
 //# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IAEpB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IAEjB,sBAAsB;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,+DAA+D;IAC/D,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAElB,sEAAsE;IACtE,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAEjC,yDAAyD;IACzD,SAAS,EAAE,YAAY,CAAC;CACzB;AAMD,eAAO,MAAM,cAAc,EAAE,iBAAiB,EA+N7C,CAAC;AAMF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAEzE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAGhF;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAG/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAS/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,EAAE,CAEtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,iBAAiB,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,iBAAiB,EAAE,CAElD"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAsC,MAAM,mBAAmB,CAAC;AAM3F;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IAEpB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IAEpB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAEhB,6CAA6C;IAC7C,WAAW,EAAE,sBAAsB,CAAC;IAEpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,aAAa,CAAC;IAEzB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAuB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACpC,sBAAsB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1C,0BAA0B,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IAEpB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IAEjB,sBAAsB;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,+DAA+D;IAC/D,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAElB,sEAAsE;IACtE,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAEjC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAElB,iGAAiG;IACjG,SAAS,EAAE,OAAO,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;CACvC;AA4FD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,sBAAsB,GAClC,aAAa,GAAG,SAAS,CA4C3B;AAgCD,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAetB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,MAAM,OAAO,CAAC,WAAW,CAAC,CAE5B;AA4CD,eAAO,MAAM,cAAc,EAAE,iBAAiB,EAE7C,CAAC;AAMF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAEzE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAGhF;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAG/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAS/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,EAAE,CAEtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,iBAAiB,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,iBAAiB,EAAE,CAElD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAItF;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAI/E;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAG/E"}