@framers/agentos-skills-registry 0.1.0 → 0.2.1

package/CONTRIBUTING.md

@@ -0,0 +1,225 @@
+# 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
+
+- `information` — Data lookup, search, knowledge retrieval
+- `developer-tools` — Code, repos, CI/CD, debugging
+- `communication` — Chat, email, messaging platforms
+- `productivity` — Note-taking, task management, organization
+- `devops` — Infrastructure, monitoring, deployment
+- `media` — Audio, video, image, streaming
+- `security` — Passwords, encryption, access control
+- `creative` — Art, writing, design, generation
+
+### 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,6 @@
 # @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) — 36 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 +10,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.
+- **36 curated SKILL.md files** — prompt modules spanning social automation, developer tooling, productivity, research, 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 deps)
 
-The `./catalog` sub-export works standalone — no `@framers/agentos` needed:
+The `./catalog` sub-export has no peer dependencies:
 
 ```typescript
 import {
@@ -33,23 +35,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); // 36
+console.log(catalog.version); // '1.0.0'
+```
+
+Or import the raw JSON:
+
+```typescript
+import registry from '@framers/agentos-skills-registry/registry.json';
+console.log(registry.skills.curated[0].name); // 'weather'
 ```
 
-### Full registry (requires @framers/agentos)
+### 3. Dynamically load skills into an agent (requires @framers/agentos)
 
-The factory functions lazy-load `@framers/agentos` via `dynamic import()` — only resolved when called:
+The factory functions lazy-load `@framers/agentos` via dynamic `import()`:
 
 ```bash
 npm install @framers/agentos-skills-registry @framers/agentos
@@ -59,47 +84,123 @@ npm install @framers/agentos-skills-registry @framers/agentos
 import {
   createCuratedSkillRegistry,
   createCuratedSkillSnapshot,
+  getBundledCuratedSkillsDir,
 } 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
+// 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
+
+// Inject the snapshot prompt into your agent's system message
+const systemPrompt = `You are an AI assistant.\n\n${snapshot.prompt}`;
+
+// Option C: Get the directory path and load manually
+const skillsDir = getBundledCuratedSkillsDir();
+// → '/path/to/node_modules/@framers/agentos-skills-registry/registry/curated'
 ```
 
-If `@framers/agentos` is not installed and you call a factory function, you get a clear error:
+### 4. Dynamic skill resolution in Wunderland presets
 
+```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 });
 ```
-Error: @framers/agentos is required for createCuratedSkillRegistry() and
-createCuratedSkillSnapshot().  Install it:
 
-  npm install @framers/agentos
+## Two Import Paths
+
+| 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 |
+
+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 (36)
+
+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 supports both **curated** (staff-maintained) and **community** (PR-submitted) skills:
+
+```typescript
+import { getCuratedSkills, getCommunitySkills } from '@framers/agentos-skills-registry/catalog';
 
-Or use the lightweight catalog helpers (getSkillsByCategory, searchSkills, etc.)
-which have no peer-dep requirement.
+const curated = getCuratedSkills();   // Staff-verified skills
+const community = getCommunitySkills(); // Community-contributed
 ```
 
-## Lazy Loading
+Each entry includes a `source` field (`'curated'` or `'community'`) for provenance filtering.
 
-The `@framers/agentos` dependency is loaded **lazily** at runtime via dynamic `import()` and cached after first resolution. This means:
+## Schema Types
 
-- `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**
+Import registry.json schema types for type-safe access:
+
+```typescript
+import type {
+  SkillRegistryEntry,
+  SkillsRegistry,
+  SkillInstallSpec,
+  SkillMetadata,
+} from '@framers/agentos-skills-registry';
+
+// SkillRegistryEntry — shape of entries in registry.json
+// SkillsRegistry — shape of the full registry.json file
+// SkillInstallSpec — install instructions for skill dependencies
+```
+
+## Exports
+
+| Export path | Contents |
+|-------------|----------|
+| `.` | Full SDK: catalog helpers + factory functions + schema types |
+| `./catalog` | Lightweight: `SKILLS_CATALOG`, query helpers (zero 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,9 +2,8 @@
  * @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.
  */
 export interface SkillCatalogEntry {
     /** Unique skill name (matches directory name under registry/curated/) */
@@ -21,10 +20,12 @@ 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;
-    /** All curated skills are in the wunderland namespace */
-    namespace: 'wunderland';
+    /** Skill source: curated (staff-maintained) or community-submitted */
+    source?: 'curated' | 'community';
+    /** Namespace used by the skill registry */
+    namespace: string;
 }
 export declare const SKILLS_CATALOG: SkillCatalogEntry[];
 /**
@@ -53,4 +54,16 @@ export declare function getSkillsByTag(tag: string): SkillCatalogEntry[];
  * Full-text search across skill names, descriptions, and tags.
  */
 export declare function searchSkills(query: string): SkillCatalogEntry[];
+/**
+ * Get only staff-curated skills.
+ */
+export declare function getCuratedSkills(): SkillCatalogEntry[];
+/**
+ * Get only community-submitted skills.
+ */
+export declare function getCommunitySkills(): SkillCatalogEntry[];
+/**
+ * Get all skills (curated + community). Alias for SKILLS_CATALOG.
+ */
+export declare function getAllSkills(): SkillCatalogEntry[];
 //# 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,yDAAyD;IACzD,SAAS,EAAE,YAAY,CAAC;CACzB;AAMD,eAAO,MAAM,cAAc,EAAE,iBAAiB,EA+M7C,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"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,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;CACnB;AAyCD,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"}