@framers/agentos-skills 0.3.0 → 0.4.1

package/scripts/update-registry.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * Regenerate skills registry.json from SKILL.md files.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.join(__dirname, '..');
+const registryPath = path.join(packageRoot, 'registry.json');
+const curatedRoot = path.join(packageRoot, 'registry', 'curated');
+const communityRoot = path.join(packageRoot, 'registry', 'community');
+
+function readFrontmatter(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  try {
+    const parsed = YAML.parse(match[1]);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function listSkillDirs(root) {
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(root, d.name, 'SKILL.md')))
+    .map((d) => d.name)
+    .sort();
+}
+
+function cleanObject(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v === undefined) continue;
+    if (Array.isArray(v) && v.length === 0) continue;
+    if (v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+function toStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === 'string' && v.trim().length > 0);
+}
+
+function slugToDisplayName(slug) {
+  return slug
+    .split(/[-_]/g)
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function buildEntry(name, source, updatedAt) {
+  const skillPath = path.join(packageRoot, 'registry', source, name, 'SKILL.md');
+  const fm = readFrontmatter(skillPath);
+  const metadata = fm?.metadata?.agentos && typeof fm.metadata.agentos === 'object'
+    ? fm.metadata.agentos
+    : undefined;
+
+  return cleanObject({
+    id: source === 'curated' ? `com.framers.skill.${name}` : `com.community.skill.${name}`,
+    name,
+    displayName:
+      typeof fm.name === 'string' && fm.name.trim().length > 0
+        ? fm.name
+        : slugToDisplayName(name),
+    version: typeof fm.version === 'string' && fm.version ? fm.version : '1.0.0',
+    path: `registry/${source}/${name}`,
+    description: typeof fm.description === 'string' ? fm.description : '',
+    category: typeof fm.category === 'string' && fm.category ? fm.category : 'uncategorized',
+    namespace: typeof fm.namespace === 'string' && fm.namespace ? fm.namespace : 'wunderland',
+    verified: source === 'curated',
+    source,
+    verifiedAt: source === 'curated' ? updatedAt : undefined,
+    keywords: toStringArray(fm.tags),
+    requiredSecrets: toStringArray(fm.requires_secrets),
+    requiredTools: toStringArray(fm.requires_tools),
+    metadata: metadata && typeof metadata === 'object' ? metadata : undefined,
+  });
+}
+
+function generateRegistry() {
+  const updated = new Date().toISOString();
+  const curatedNames = listSkillDirs(curatedRoot);
+  const communityNames = listSkillDirs(communityRoot);
+
+  const curated = curatedNames.map((name) => buildEntry(name, 'curated', updated));
+  const community = communityNames.map((name) => buildEntry(name, 'community', updated));
+
+  return {
+    version: '1.0.0',
+    updated,
+    categories: {
+      curated: curatedNames,
+      community: communityNames,
+    },
+    skills: {
+      curated,
+      community,
+    },
+    stats: {
+      totalSkills: curated.length + community.length,
+      curatedCount: curated.length,
+      communityCount: community.length,
+    },
+  };
+}
+
+const registry = generateRegistry();
+fs.writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
+
+console.log('✅ Skills registry updated');
+console.log(`   curated: ${registry.stats.curatedCount}`);
+console.log(`   community: ${registry.stats.communityCount}`);
+console.log(`   total: ${registry.stats.totalSkills}`);

package/scripts/validate-skill.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+
+/**
+ * SKILL.md validator for @framers/agentos-skills
+ *
+ * Usage:
+ *   node scripts/validate-skill.mjs registry/community/my-skill/SKILL.md
+ *   node scripts/validate-skill.mjs                                        # validates ALL skills
+ *
+ * Exit code 0 on pass, 1 on fail.
+ * Zero external dependencies — uses only Node.js built-ins.
+ */
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { resolve, basename, dirname, join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const VALID_CATEGORIES = new Set([
+  'automation',
+  'communication',
+  'content',
+  'creative',
+  'developer-tools',
+  'devops',
+  'information',
+  'infrastructure',
+  'marketing',
+  'media',
+  'productivity',
+  'research',
+  'security',
+  'social-automation',
+]);
+
+const VALID_NAMESPACES = new Set(['wunderland', 'community']);
+
+const REQUIRED_FIELDS = ['name', 'version', 'description', 'author', 'namespace', 'category', 'tags'];
+
+const MAX_DESCRIPTION_LENGTH = 200;
+
+/** Patterns that suggest accidentally-committed secrets. */
+const SECRET_PATTERNS = [
+  /(?:api[_-]?key|apikey)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i,
+  /(?:secret|token|password|passwd|pwd)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i,
+  /sk-[A-Za-z0-9]{20,}/,                          // OpenAI-style keys
+  /ghp_[A-Za-z0-9]{36,}/,                          // GitHub personal access tokens
+  /gho_[A-Za-z0-9]{36,}/,                          // GitHub OAuth tokens
+  /xox[bpors]-[A-Za-z0-9\-]{10,}/,                 // Slack tokens
+  /AKIA[0-9A-Z]{16}/,                              // AWS access key IDs
+  /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/,       // Private keys
+  /Bearer\s+[A-Za-z0-9_\-\.]{20,}/,                // Bearer tokens
+];
+
+// ---------------------------------------------------------------------------
+// Simple YAML frontmatter parser (no dependencies)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse basic YAML key-value pairs from frontmatter lines.
+ * Handles:
+ *   key: value           -> string
+ *   key: 'value'         -> string (strip quotes)
+ *   key: "value"         -> string (strip quotes)
+ *   key: [a, b, c]       -> string[]
+ *   key: []              -> string[] (empty)
+ *
+ * Nested keys (like metadata.agentos.emoji) are ignored — only top-level
+ * keys matter for required-field validation.
+ */
+function parseSimpleYaml(yamlText) {
+  const result = {};
+  const lines = yamlText.split('\n');
+
+  for (const line of lines) {
+    // Skip blank lines and comments
+    const trimmed = line.trimStart();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Only parse top-level keys (no leading whitespace)
+    if (line[0] === ' ' || line[0] === '\t') continue;
+
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    let value = trimmed.slice(colonIndex + 1).trim();
+
+    if (!key) continue;
+
+    // Inline array: [a, b, c]
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      if (inner === '') {
+        result[key] = [];
+      } else {
+        result[key] = inner.split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, ''));
+      }
+      continue;
+    }
+
+    // Strip surrounding quotes
+    if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+      value = value.slice(1, -1);
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a single SKILL.md file. Returns an object with:
+ *   { path, passed, errors[] }
+ */
+function validateSkill(filePath) {
+  const errors = [];
+  const absolutePath = resolve(filePath);
+
+  // --- Read file --------------------------------------------------------
+
+  let content;
+  try {
+    content = readFileSync(absolutePath, 'utf-8');
+  } catch (err) {
+    return { path: absolutePath, passed: false, errors: [`Cannot read file: ${err.message}`] };
+  }
+
+  // --- Split frontmatter / body ----------------------------------------
+
+  const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+  const match = content.match(fmRegex);
+
+  if (!match) {
+    return {
+      path: absolutePath,
+      passed: false,
+      errors: ['File does not contain valid YAML frontmatter (expected --- delimiters).'],
+    };
+  }
+
+  const yamlText = match[1];
+  const markdownBody = match[2];
+
+  // --- Parse YAML -------------------------------------------------------
+
+  const meta = parseSimpleYaml(yamlText);
+
+  // --- Required fields --------------------------------------------------
+
+  for (const field of REQUIRED_FIELDS) {
+    if (meta[field] === undefined || meta[field] === '') {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // --- Category ---------------------------------------------------------
+
+  if (meta.category && !VALID_CATEGORIES.has(meta.category)) {
+    errors.push(
+      `Invalid category "${meta.category}". Must be one of: ${[...VALID_CATEGORIES].join(', ')}`,
+    );
+  }
+
+  // --- Namespace --------------------------------------------------------
+
+  if (meta.namespace && !VALID_NAMESPACES.has(meta.namespace)) {
+    errors.push(
+      `Invalid namespace "${meta.namespace}". Must be one of: ${[...VALID_NAMESPACES].join(', ')}`,
+    );
+  }
+
+  // --- Description length -----------------------------------------------
+
+  if (meta.description && typeof meta.description === 'string' && meta.description.length > MAX_DESCRIPTION_LENGTH) {
+    errors.push(
+      `Description is ${meta.description.length} characters (max ${MAX_DESCRIPTION_LENGTH}).`,
+    );
+  }
+
+  // --- Tags -------------------------------------------------------------
+
+  if (meta.tags !== undefined) {
+    if (!Array.isArray(meta.tags)) {
+      errors.push('tags must be an array.');
+    } else if (meta.tags.length === 0) {
+      errors.push('tags array must contain at least 1 tag.');
+    }
+  }
+
+  // --- Name matches directory -------------------------------------------
+
+  const dirName = basename(dirname(absolutePath));
+  if (meta.name && meta.name !== dirName) {
+    errors.push(
+      `Skill name "${meta.name}" does not match directory name "${dirName}".`,
+    );
+  }
+
+  // --- Markdown body not empty ------------------------------------------
+
+  if (!markdownBody || markdownBody.trim().length === 0) {
+    errors.push('Markdown body is empty. Include usage instructions, Examples, and Constraints.');
+  }
+
+  // --- Secret pattern scan ----------------------------------------------
+
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.test(content)) {
+      errors.push(`Possible secret or credential detected (pattern: ${pattern.source}). Remove it before submitting.`);
+    }
+  }
+
+  return { path: absolutePath, passed: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Discover all SKILL.md files
+// ---------------------------------------------------------------------------
+
+function discoverSkills(rootDir) {
+  const skills = [];
+  const tiers = ['curated', 'community'];
+
+  for (const tier of tiers) {
+    const tierDir = join(rootDir, 'registry', tier);
+    if (!existsSync(tierDir)) continue;
+
+    for (const entry of readdirSync(tierDir)) {
+      const skillDir = join(tierDir, entry);
+      if (!statSync(skillDir).isDirectory()) continue;
+
+      const skillFile = join(skillDir, 'SKILL.md');
+      if (existsSync(skillFile)) {
+        skills.push(skillFile);
+      }
+    }
+  }
+
+  return skills;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+
+  let filesToValidate;
+
+  if (args.length === 0) {
+    // Validate all skills
+    const rootDir = resolve(dirname(new URL(import.meta.url).pathname), '..');
+    filesToValidate = discoverSkills(rootDir);
+    if (filesToValidate.length === 0) {
+      console.log('No SKILL.md files found in registry/curated/ or registry/community/.');
+      process.exit(0);
+    }
+    console.log(`Validating ${filesToValidate.length} skill(s)...\n`);
+  } else {
+    filesToValidate = [resolve(args[0])];
+  }
+
+  let allPassed = true;
+
+  for (const filePath of filesToValidate) {
+    const result = validateSkill(filePath);
+
+    if (result.passed) {
+      console.log(`  PASS  ${result.path}`);
+    } else {
+      allPassed = false;
+      console.log(`  FAIL  ${result.path}`);
+      for (const err of result.errors) {
+        console.log(`        - ${err}`);
+      }
+    }
+  }
+
+  console.log('');
+
+  if (allPassed) {
+    console.log(`All ${filesToValidate.length} skill(s) passed validation.`);
+    process.exit(0);
+  } else {
+    const failCount = filesToValidate.length - filesToValidate.filter((_, i) => {
+      // Re-validate to count (cheap for small set)
+      return validateSkill(filesToValidate[i]).passed;
+    }).length;
+    // Simpler: just fail
+    console.log('Validation failed. Fix the errors above and re-run.');
+    process.exit(1);
+  }
+}
+
+main();

package/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Type declarations for the `@framers/agentos-skills` content package.
+ *
+ * Describes the shape of `registry.json` — the machine-readable index of all
+ * bundled SKILL.md prompt modules. These types are consumed by
+ * `@framers/agentos-skills-registry` (the catalog SDK) and any tooling that
+ * reads the registry directly.
+ *
+ * @module @framers/agentos-skills
+ */
+
+/** Supported package-manager / install strategies for skill prerequisites. */
+export type SkillInstallKind = 'brew' | 'apt' | 'node' | 'go' | 'uv' | 'download';
+
+/**
+ * Describes how to install a single prerequisite binary for a skill.
+ *
+ * Each install spec maps to a concrete command the agent or user can run
+ * (e.g. `brew install gh`, `npm install -g typescript`).
+ */
+export interface SkillInstallSpec {
+  /** Unique ID for this install option (e.g. 'brew-gh') */
+  id?: string;
+  /** Package manager or install strategy */
+  kind: SkillInstallKind;
+  /** Human-readable label for the install option */
+  label?: string;
+  /** Binary names this install provides (used for verification) */
+  bins?: string[];
+  /** OS restrictions — only show this option on matching platforms */
+  os?: readonly string[];
+  /** Homebrew formula name */
+  formula?: string;
+  /** npm / pip / go package name */
+  package?: string;
+  /** Node module name (for `npx`-style invocation) */
+  module?: string;
+  /** Direct download URL */
+  url?: string;
+  /** Archive filename within the download */
+  archive?: string;
+  /** Whether to extract the download */
+  extract?: boolean;
+  /** Number of directory levels to strip when extracting */
+  stripComponents?: number;
+  /** Target directory for the extracted/downloaded binary */
+  targetDir?: string;
+}
+
+/**
+ * Binary, environment variable, and config requirements that must be met
+ * before a skill is eligible to run.
+ */
+export interface SkillRequirements {
+  /** All of these binaries must be on PATH */
+  bins?: string[];
+  /** At least one of these binaries must be on PATH */
+  anyBins?: string[];
+  /** All of these environment variables must be set */
+  env?: string[];
+  /** All of these config file paths must exist */
+  config?: string[];
+}
+
+/**
+ * Structured metadata extracted from the `metadata.agentos` block in SKILL.md
+ * frontmatter. Controls eligibility, discoverability, and installation UX.
+ */
+export interface SkillMetadata {
+  /** If true, skill is always included in agent context (no opt-in needed) */
+  always?: boolean;
+  /** Override key used for per-skill config in agent.config.json */
+  skillKey?: string;
+  /** Primary environment variable this skill needs (e.g. 'GITHUB_TOKEN') */
+  primaryEnv?: string;
+  /** Emoji icon for display in catalogs and CLI */
+  emoji?: string;
+  /** URL to the skill's homepage or docs */
+  homepage?: string;
+  /** OS restrictions — skill only available on these platforms */
+  os?: readonly string[];
+  /** Binary and env requirements for eligibility checking */
+  requires?: SkillRequirements;
+  /** Installation options for missing prerequisites */
+  install?: SkillInstallSpec[];
+}
+
+/**
+ * Shape of a single skill entry in `registry.json`.
+ *
+ * Each entry maps to one `registry/curated/{name}/SKILL.md` file and includes
+ * all metadata needed for catalog queries without reading the file from disk.
+ */
+export interface SkillRegistryEntry {
+  /** Fully-qualified ID (e.g. 'com.framers.skill.github') */
+  id: string;
+  /** Unique slug matching the directory name under registry/curated/ */
+  name: string;
+  /** Human-readable display name (e.g. 'GitHub') */
+  displayName?: string;
+  /** Semantic version from the SKILL.md frontmatter */
+  version: string;
+  /** Relative path from package root to the skill directory */
+  path: string;
+  /** Brief description of the skill's capabilities */
+  description: string;
+  /** Grouping category (e.g. 'developer', 'social', 'voice') */
+  category?: string;
+  /** Namespace used for registry scoping */
+  namespace?: string;
+  /** Whether this skill has been staff-verified */
+  verified: boolean;
+  /** Provenance: curated (staff-maintained) or community-submitted */
+  source?: 'curated' | 'community';
+  /** ISO timestamp of last verification */
+  verifiedAt?: string;
+  /** Searchable keywords */
+  keywords?: string[];
+  /** Secret identifiers the skill requires (e.g. 'github.token') */
+  requiredSecrets?: string[];
+  /** Tool identifiers the skill depends on */
+  requiredTools?: string[];
+  /** Structured metadata from the SKILL.md frontmatter */
+  metadata?: SkillMetadata;
+}
+
+/** Aggregate counts for the registry. */
+export interface SkillsRegistryStats {
+  totalSkills: number;
+  curatedCount: number;
+  communityCount: number;
+}
+
+/**
+ * Shape of the full `registry.json` file.
+ *
+ * Auto-generated by `scripts/update-registry.mjs` from the SKILL.md files
+ * in `registry/curated/` and `registry/community/`.
+ */
+export interface SkillsRegistry {
+  /** Schema version */
+  version: string;
+  /** ISO timestamp of last regeneration */
+  updated: string;
+  /** Category names present in each source */
+  categories: {
+    curated: string[];
+    community: string[];
+  };
+  /** Skill entries grouped by source */
+  skills: {
+    curated: SkillRegistryEntry[];
+    community: SkillRegistryEntry[];
+  };
+  /** Aggregate statistics */
+  stats: SkillsRegistryStats;
+}
+
+declare const registry: SkillsRegistry;
+export default registry;

package/dist/SkillLoader.d.ts

@@ -1,50 +0,0 @@
-/**
- * @fileoverview Skill Loader for AgentOS
- * @module @framers/agentos-skills/SkillLoader
- *
- * Loads skills from directories by parsing SKILL.md files with YAML frontmatter.
- * Skills are modular capabilities that extend agent functionality.
- */
-import type { SkillEntry, SkillMetadata, SkillEligibilityContext, ParsedSkillFrontmatter } from './types.js';
-/**
- * Parse YAML frontmatter from SKILL.md content.
- * Supports the standard `---` delimited format.
- */
-export declare function parseSkillFrontmatter(content: string): {
-    frontmatter: ParsedSkillFrontmatter;
-    body: string;
-};
-/**
- * Extract SkillMetadata from parsed frontmatter.
- */
-export declare function extractMetadata(frontmatter: ParsedSkillFrontmatter): SkillMetadata | undefined;
-/**
- * Load a single skill from a directory.
- *
- * @param skillDir - Path to skill directory (should contain SKILL.md)
- * @returns SkillEntry or null if invalid
- */
-export declare function loadSkillFromDir(skillDir: string): Promise<SkillEntry | null>;
-/**
- * Load all skills from a directory.
- *
- * @param dir - Parent directory containing skill subdirectories
- * @returns Array of SkillEntry objects
- */
-export declare function loadSkillsFromDir(dir: string): Promise<SkillEntry[]>;
-/**
- * Filter skill entries by platform.
- */
-export declare function filterByPlatform(entries: SkillEntry[], platform: string): SkillEntry[];
-/**
- * Filter skill entries by eligibility context.
- */
-export declare function filterByEligibility(entries: SkillEntry[], context: SkillEligibilityContext): SkillEntry[];
-/**
- * Check if all binary requirements for a skill are met.
- */
-export declare function checkBinaryRequirements(entry: SkillEntry, hasBin: (bin: string) => boolean): {
-    met: boolean;
-    missing: string[];
-};
-//# sourceMappingURL=SkillLoader.d.ts.map

package/dist/SkillLoader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SkillLoader.d.ts","sourceRoot":"","sources":["../src/SkillLoader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAEV,UAAU,EACV,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG;IACtD,WAAW,EAAE,sBAAsB,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd,CAkCA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,sBAAsB,GAAG,aAAa,GAAG,SAAS,CAoC9F;AAiED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyCnF;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAuB1E;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAStF;AAaD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,UAAU,EAAE,EACrB,OAAO,EAAE,uBAAuB,GAC/B,UAAU,EAAE,CA+Bd;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAC/B;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBrC"}