@devxiyang/agent-skill 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dev.xiyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# agent.skill
+
+SDK for skill discovery and registration — integrates into any agent.
+
+A **skill** is a folder containing a `SKILL.md` file (with YAML frontmatter + instructions) and optional resources (scripts, references, assets). This SDK provides the tooling to discover, validate, and load skills into an agent's context.
+
+## Installation
+
+```bash
+npm install @devxiyang/agent-skill
+```
+
+## Concepts
+
+### Skill folder structure
+
+```
+skill-name/
+├── SKILL.md          # required — frontmatter metadata + instructions
+├── scripts/          # optional — executable scripts
+├── references/       # optional — docs loaded on demand
+└── assets/           # optional — files used in output
+```
+
+### SKILL.md frontmatter
+
+```yaml
+---
+name: github
+description: Interact with GitHub using the gh CLI.
+requires: bin:gh,env:GITHUB_TOKEN
+os: darwin,linux
+---
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | yes | Skill identifier |
+| `description` | yes | What the skill does and when to use it |
+| `requires` | no | `bin:<name>` and/or `env:<NAME>` comma-separated |
+| `os` | no | Allowed platforms: `darwin`, `linux`, `win32` |
+| `always` | no | Load into agent context on every run |
+
+## Usage
+
+```typescript
+import { SkillDiscovery, builtinSkillsRoot } from '@devxiyang/agent-skill';
+
+const discovery = new SkillDiscovery([
+  { path: '/my/workspace/skills', scope: 'user' },  // checked first — higher priority
+  { path: builtinSkillsRoot(), scope: 'system' },   // fallback
+]);
+
+// Discover all skills with eligibility info
+const entries = await discovery.list();
+
+// Load the body of a SKILL.md (frontmatter stripped)
+const content = await discovery.load(entries[0].filePath);
+```
+
+**Priority is determined by roots array order** — the first root that contains a skill with a given name wins; later roots are skipped for that name. The `scope` field is metadata only and does not affect priority.
+
+To override a built-in skill, place a skill folder with the same name in an earlier root:
+
+```
+/my/workspace/skills/
+└── git/           ← overrides the built-in git skill
+    └── SKILL.md
+```
+
+## Built-in skills
+
+| Skill | Requires | Description |
+|---|---|---|
+| `git` | `git` | Local git operations |
+| `github` | `gh` | GitHub issues, PRs, CI via gh CLI |
+| `tmux` | `tmux` (macOS/Linux) | Remote-control interactive terminal sessions |
+| `weather` | `curl` | Current weather and forecasts, no API key |
+| `web` | `curl` | Fetch pages, call REST APIs, download files |
+| `skill-creator` | — | Guide for creating and structuring new skills |
+
+## Copying skills
+
+Copy skill folders from any source root into a target directory. Useful for seeding a workspace with built-in or third-party skill sets.
+
+```typescript
+import { copySkills, builtinSkillsRoot } from '@devxiyang/agent-skill';
+
+// Copy all built-in skills
+await copySkills({
+  from: builtinSkillsRoot(),
+  to: '/my/workspace/skills',
+});
+
+// Copy a subset
+await copySkills({
+  from: builtinSkillsRoot(),
+  to: '/my/workspace/skills',
+  skills: ['git', 'github'],
+});
+
+// Overwrite existing
+await copySkills({
+  from: builtinSkillsRoot(),
+  to: '/my/workspace/skills',
+  overwrite: true,
+});
+```
+
+Returns `{ copied: string[], skipped: string[] }`. Existing skills are skipped by default (`overwrite: false`). Directories without a `SKILL.md` are ignored.
+
+## Custom validator
+
+By default, dependency checks use the built-in `defaultValidator` (Node.js PATH lookup, `process.env`, `process.platform`). You can provide your own:
+
+```typescript
+import { SkillDiscovery, SkillValidator } from '@devxiyang/agent-skill';
+
+const myValidator: SkillValidator = {
+  async checkBin(name) { /* custom bin check */ return true; },
+  checkEnv(name) { return !!process.env[name]; },
+  checkOs(platforms) { return platforms.includes(process.platform); },
+};
+
+const discovery = new SkillDiscovery([{ path: myRoot, scope: 'user' }], myValidator);
+```
+
+## API
+
+### `SkillDiscovery`
+
+```typescript
+new SkillDiscovery(roots: SkillRoot[], validator?: SkillValidator)
+
+discovery.list(): Promise<SkillEntry[]>
+discovery.load(filePath: string): Promise<string>
+```
+
+### `copySkills(options): Promise<CopySkillsResult>`
+
+```typescript
+type CopySkillsOptions = {
+  from: string;        // source skills root
+  to: string;          // target directory
+  skills?: string[];   // filter by skill name (default: all)
+  overwrite?: boolean; // overwrite existing (default: false)
+};
+
+type CopySkillsResult = {
+  copied: string[];
+  skipped: string[];
+};
+```
+
+### `builtinSkillsRoot(): string`
+
+Returns the absolute path to the built-in skills directory bundled with this package.
+
+### `defaultValidator`
+
+The built-in `SkillValidator` implementation for Node.js environments.
+
+### Types
+
+```typescript
+type SkillEntry = {
+  name: string;
+  description: string | null;
+  path: string;        // skill folder path
+  filePath: string;    // SKILL.md path
+  scope: 'user' | 'system';
+  eligible: boolean;   // all dependencies satisfied
+  always: boolean;
+  tags: string[];
+  missing: SkillMissingReason[];
+};
+
+type SkillMissingReason = {
+  kind: 'bin' | 'env' | 'os' | 'invalid';
+  value: string;
+  message: string;
+};
+```
+
+## License
+
+MIT

package/dist/builtin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns the absolute path to the built-in skills directory bundled with this package.
+ *
+ * Resolves relative to this file's location so the path remains correct regardless
+ * of where the consuming project is installed. Pass the result to SkillDiscovery
+ * as a system-scoped root:
+ *
+ * ```ts
+ * new SkillDiscovery([
+ *   { path: userSkillsDir, scope: 'user' },
+ *   { path: builtinSkillsRoot(), scope: 'system' },
+ * ])
+ * ```
+ *
+ * Note for Electron apps: if the app is packaged with asar, add
+ * `node_modules/@devxiyang/agent-skill/skills` to `asarUnpack` in
+ * electron-builder config so the directory is accessible via the filesystem.
+ */
+export declare function builtinSkillsRoot(): string;
+//# sourceMappingURL=builtin.d.ts.map

package/dist/builtin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../src/builtin.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C"}

package/dist/builtin.js

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Returns the absolute path to the built-in skills directory bundled with this package.
+ *
+ * Resolves relative to this file's location so the path remains correct regardless
+ * of where the consuming project is installed. Pass the result to SkillDiscovery
+ * as a system-scoped root:
+ *
+ * ```ts
+ * new SkillDiscovery([
+ *   { path: userSkillsDir, scope: 'user' },
+ *   { path: builtinSkillsRoot(), scope: 'system' },
+ * ])
+ * ```
+ *
+ * Note for Electron apps: if the app is packaged with asar, add
+ * `node_modules/@devxiyang/agent-skill/skills` to `asarUnpack` in
+ * electron-builder config so the directory is accessible via the filesystem.
+ */
+export function builtinSkillsRoot() {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(dir, '..', 'skills');
+}
+//# sourceMappingURL=builtin.js.map

package/dist/builtin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.js","sourceRoot":"","sources":["../src/builtin.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC3C,CAAC"}

package/dist/copy.d.ts

@@ -0,0 +1,30 @@
+export type CopySkillsOptions = {
+    /** Source skills root directory (e.g. builtinSkillsRoot()). */
+    from: string;
+    /** Target directory to copy skills into. Created if it does not exist. */
+    to: string;
+    /** Only copy these skill names. Copies all if omitted. */
+    skills?: string[];
+    /** Overwrite existing skill folders. Default: false. */
+    overwrite?: boolean;
+};
+export type CopySkillsResult = {
+    /** Names of skills that were successfully copied. */
+    copied: string[];
+    /** Names of skills that were skipped because they already exist and overwrite is false. */
+    skipped: string[];
+};
+/**
+ * Copy skill folders from a source root into a target directory.
+ *
+ * Only directories that contain a SKILL.md are treated as valid skills;
+ * everything else is silently ignored.
+ *
+ * ```ts
+ * import { copySkills, builtinSkillsRoot } from '@devxiyang/agent-skill';
+ *
+ * await copySkills({ from: builtinSkillsRoot(), to: '/my/workspace/skills' });
+ * ```
+ */
+export declare function copySkills(options: CopySkillsOptions): Promise<CopySkillsResult>;
+//# sourceMappingURL=copy.d.ts.map

package/dist/copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.d.ts","sourceRoot":"","sources":["../src/copy.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2FAA2F;IAC3F,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4CtF"}

package/dist/copy.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Copy skill folders from a source root into a target directory.
+ *
+ * Only directories that contain a SKILL.md are treated as valid skills;
+ * everything else is silently ignored.
+ *
+ * ```ts
+ * import { copySkills, builtinSkillsRoot } from '@devxiyang/agent-skill';
+ *
+ * await copySkills({ from: builtinSkillsRoot(), to: '/my/workspace/skills' });
+ * ```
+ */
+export async function copySkills(options) {
+    const { from, to, skills, overwrite = false } = options;
+    await fs.mkdir(to, { recursive: true });
+    const dirents = await fs.readdir(from, { withFileTypes: true });
+    const candidates = dirents.filter((d) => d.isDirectory() && !d.name.startsWith('.'));
+    // Apply optional name filter.
+    const targets = skills
+        ? candidates.filter((d) => skills.includes(d.name))
+        : candidates;
+    const copied = [];
+    const skipped = [];
+    for (const dirent of targets) {
+        const srcPath = path.join(from, dirent.name);
+        const destPath = path.join(to, dirent.name);
+        // Validate: must contain a SKILL.md to be considered a skill folder.
+        try {
+            await fs.access(path.join(srcPath, 'SKILL.md'));
+        }
+        catch {
+            continue;
+        }
+        const destExists = await exists(destPath);
+        if (destExists && !overwrite) {
+            skipped.push(dirent.name);
+            continue;
+        }
+        if (destExists) {
+            await fs.rm(destPath, { recursive: true });
+        }
+        await copyDir(srcPath, destPath);
+        copied.push(dirent.name);
+    }
+    return { copied, skipped };
+}
+/** Recursively copies a directory tree from src to dest. */
+async function copyDir(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcEntry = path.join(src, entry.name);
+        const destEntry = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDir(srcEntry, destEntry);
+        }
+        else {
+            await fs.copyFile(srcEntry, destEntry);
+        }
+    }
+}
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=copy.js.map

package/dist/copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.js","sourceRoot":"","sources":["../src/copy.ts"],"names":[],"mappings":"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"}

package/dist/discovery/discovery.d.ts

@@ -0,0 +1,40 @@
+import type { SkillEntry, SkillRoot } from '../types.js';
+import type { SkillValidator } from '../validator.js';
+/**
+ * Discovers and loads skills from one or more root directories.
+ *
+ * Priority is determined by the order of the `roots` array — the first root
+ * that contains a skill folder with a given name wins; subsequent roots are
+ * skipped for that name. Place higher-priority roots (e.g. user overrides)
+ * before lower-priority ones (e.g. built-in skills).
+ *
+ * ```ts
+ * const discovery = new SkillDiscovery([
+ *   { path: userSkillsDir, scope: 'user' },        // checked first
+ *   { path: builtinSkillsRoot(), scope: 'system' }, // fallback
+ * ]);
+ * ```
+ */
+export declare class SkillDiscovery {
+    private readonly roots;
+    private readonly validator;
+    constructor(roots: SkillRoot[], validator?: SkillValidator);
+    /**
+     * Scans all roots and returns every discovered skill with its eligibility status.
+     *
+     * Skills are deduplicated by folder name (first-root-wins). The returned array
+     * is sorted alphabetically by skill name.
+     */
+    list(): Promise<SkillEntry[]>;
+    /**
+     * Reads a SKILL.md file and returns its body with the frontmatter block stripped.
+     * This is the content suitable for injecting into an agent's context.
+     */
+    load(filePath: string): Promise<string>;
+    /**
+     * Checks all requires/os constraints declared in the frontmatter against the
+     * current environment and returns a list of unmet requirements.
+     */
+    private resolveMissing;
+}
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/discovery/discovery.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsB,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;gBAGxB,KAAK,EAAE,SAAS,EAAE,EACnC,SAAS,CAAC,EAAE,cAAc;IAK5B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCnC;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO7C;;;OAGG;YACW,cAAc;CAyB7B"}

package/dist/discovery/discovery.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { defaultValidator } from '../validators/index.js';
+import { parseFrontmatter, stripFrontmatter } from './frontmatter.js';
+/**
+ * Discovers and loads skills from one or more root directories.
+ *
+ * Priority is determined by the order of the `roots` array — the first root
+ * that contains a skill folder with a given name wins; subsequent roots are
+ * skipped for that name. Place higher-priority roots (e.g. user overrides)
+ * before lower-priority ones (e.g. built-in skills).
+ *
+ * ```ts
+ * const discovery = new SkillDiscovery([
+ *   { path: userSkillsDir, scope: 'user' },        // checked first
+ *   { path: builtinSkillsRoot(), scope: 'system' }, // fallback
+ * ]);
+ * ```
+ */
+export class SkillDiscovery {
+    roots;
+    validator;
+    constructor(roots, validator) {
+        this.roots = roots;
+        this.validator = validator ?? defaultValidator;
+    }
+    /**
+     * Scans all roots and returns every discovered skill with its eligibility status.
+     *
+     * Skills are deduplicated by folder name (first-root-wins). The returned array
+     * is sorted alphabetically by skill name.
+     */
+    async list() {
+        const byName = new Map();
+        for (const root of this.roots) {
+            if (!(await exists(root.path)))
+                continue;
+            const dirents = await fs.readdir(root.path, { withFileTypes: true });
+            for (const dirent of dirents) {
+                if (!dirent.isDirectory() || dirent.name.startsWith('.'))
+                    continue;
+                // First root wins — skip if already discovered from a higher-priority root.
+                if (byName.has(dirent.name))
+                    continue;
+                const skillPath = path.join(root.path, dirent.name);
+                const filePath = path.join(skillPath, 'SKILL.md');
+                if (!(await exists(filePath)))
+                    continue;
+                const content = await fs.readFile(filePath, 'utf8');
+                const fm = parseFrontmatter(content);
+                const missing = await this.resolveMissing(fm);
+                byName.set(dirent.name, {
+                    name: fm.name ?? dirent.name,
+                    description: fm.description,
+                    path: skillPath,
+                    filePath,
+                    scope: root.scope,
+                    eligible: missing.length === 0,
+                    always: fm.always,
+                    tags: fm.tags,
+                    missing,
+                });
+            }
+        }
+        return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Reads a SKILL.md file and returns its body with the frontmatter block stripped.
+     * This is the content suitable for injecting into an agent's context.
+     */
+    async load(filePath) {
+        const content = await fs.readFile(filePath, 'utf8');
+        return stripFrontmatter(content);
+    }
+    // ---------------------------------------------------------------------------
+    /**
+     * Checks all requires/os constraints declared in the frontmatter against the
+     * current environment and returns a list of unmet requirements.
+     */
+    async resolveMissing(fm) {
+        const missing = [];
+        for (const bin of fm.requiresBins) {
+            if (!(await this.validator.checkBin(bin))) {
+                missing.push({ kind: 'bin', value: bin, message: `Missing executable: ${bin}` });
+            }
+        }
+        for (const env of fm.requiresEnvs) {
+            if (!this.validator.checkEnv(env)) {
+                missing.push({ kind: 'env', value: env, message: `Missing env var: ${env}` });
+            }
+        }
+        if (fm.requiresOs.length > 0 && !this.validator.checkOs(fm.requiresOs)) {
+            missing.push({
+                kind: 'os',
+                value: fm.requiresOs.join(','),
+                message: `Requires OS: ${fm.requiresOs.join(' or ')}`,
+            });
+        }
+        return missing;
+    }
+}
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/discovery/discovery.ts"],"names":[],"mappings":"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"}

package/dist/discovery/frontmatter.d.ts

@@ -0,0 +1,27 @@
+/** Parsed and normalized representation of a SKILL.md frontmatter block. */
+export type SkillFrontmatter = {
+    name: string | null;
+    description: string | null;
+    always: boolean;
+    tags: string[];
+    requiresBins: string[];
+    requiresEnvs: string[];
+    requiresOs: string[];
+};
+/**
+ * Parses the YAML frontmatter of a SKILL.md file into a normalized structure.
+ *
+ * Supports two requirement sources:
+ * 1. Top-level `requires` field: `bin:git,env:GITHUB_TOKEN`
+ * 2. `metadata` field: a JSON string with a namespaced object (`octoii` or `openclaw`)
+ *    containing `requires`, `bins`, `env`, and `os` keys.
+ *
+ * Values from both sources are merged and deduplicated.
+ */
+export declare function parseFrontmatter(content: string): SkillFrontmatter;
+/**
+ * Strips the frontmatter block from a SKILL.md file and returns the trimmed body.
+ * This is the markdown content passed to the agent as skill instructions.
+ */
+export declare function stripFrontmatter(content: string): string;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/discovery/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/discovery/frontmatter.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAgBlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD"}