@devxiyang/agent-skill 0.0.6 → 0.0.8

package/README.md

@@ -1,5 +1,10 @@
 # agent.skill
 
+[![npm version](https://img.shields.io/npm/v/@devxiyang/agent-skill)](https://www.npmjs.com/package/@devxiyang/agent-skill)
+[![npm downloads](https://img.shields.io/npm/dm/@devxiyang/agent-skill)](https://www.npmjs.com/package/@devxiyang/agent-skill)
+[![node >=18](https://img.shields.io/node/v/@devxiyang/agent-skill)](https://www.npmjs.com/package/@devxiyang/agent-skill)
+[![license](https://img.shields.io/npm/l/@devxiyang/agent-skill)](./LICENSE)
+
 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.

package/dist/copy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=copy.test.d.ts.map

package/dist/copy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.test.d.ts","sourceRoot":"","sources":["../src/copy.test.ts"],"names":[],"mappings":""}

package/dist/copy.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { copySkills } from './copy.js';
+let tmpDir;
+let srcRoot;
+beforeAll(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-skill-copy-test-'));
+    srcRoot = path.join(tmpDir, 'src');
+    // Create fixture skills
+    for (const name of ['git', 'github', 'web']) {
+        const dir = path.join(srcRoot, name);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, 'SKILL.md'), `---\nname: ${name}\n---\n`);
+    }
+    // A dir without SKILL.md (should be ignored)
+    await fs.mkdir(path.join(srcRoot, 'not-a-skill'), { recursive: true });
+});
+afterAll(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe('copySkills', () => {
+    it('copies all skills to target', async () => {
+        const to = path.join(tmpDir, 'dest-all');
+        const result = await copySkills({ from: srcRoot, to });
+        expect(result.copied.sort()).toEqual(['git', 'github', 'web']);
+        expect(result.skipped).toEqual([]);
+        for (const name of result.copied) {
+            const skillMd = path.join(to, name, 'SKILL.md');
+            await expect(fs.access(skillMd)).resolves.toBeUndefined();
+        }
+    });
+    it('filters by skill names', async () => {
+        const to = path.join(tmpDir, 'dest-filter');
+        const result = await copySkills({ from: srcRoot, to, skills: ['git', 'web'] });
+        expect(result.copied.sort()).toEqual(['git', 'web']);
+        expect(result.skipped).toEqual([]);
+        await expect(fs.access(path.join(to, 'github'))).rejects.toThrow();
+    });
+    it('skips existing skills by default', async () => {
+        const to = path.join(tmpDir, 'dest-skip');
+        await copySkills({ from: srcRoot, to });
+        const result = await copySkills({ from: srcRoot, to });
+        expect(result.copied).toEqual([]);
+        expect(result.skipped.sort()).toEqual(['git', 'github', 'web']);
+    });
+    it('overwrites existing skills when overwrite: true', async () => {
+        const to = path.join(tmpDir, 'dest-overwrite');
+        await copySkills({ from: srcRoot, to });
+        const result = await copySkills({ from: srcRoot, to, overwrite: true });
+        expect(result.copied.sort()).toEqual(['git', 'github', 'web']);
+        expect(result.skipped).toEqual([]);
+    });
+    it('ignores directories without SKILL.md', async () => {
+        const to = path.join(tmpDir, 'dest-no-skill-md');
+        const result = await copySkills({ from: srcRoot, to });
+        expect(result.copied).not.toContain('not-a-skill');
+    });
+    it('creates target directory if it does not exist', async () => {
+        const to = path.join(tmpDir, 'new', 'nested', 'dest');
+        await copySkills({ from: srcRoot, to });
+        await expect(fs.access(to)).resolves.toBeUndefined();
+    });
+});
+//# sourceMappingURL=copy.test.js.map

package/dist/copy.test.js.map

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

package/dist/discovery/discovery.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=discovery.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.test.d.ts","sourceRoot":"","sources":["../../src/discovery/discovery.test.ts"],"names":[],"mappings":""}

package/dist/discovery/discovery.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { SkillDiscovery } from './discovery.js';
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+async function makeSkillDir(root, name, frontmatter, body = '') {
+    const dir = path.join(root, name);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'SKILL.md'), `---\n${frontmatter}\n---\n${body}`);
+    return dir;
+}
+let tmpDir;
+beforeAll(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-skill-test-'));
+});
+afterAll(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+describe('SkillDiscovery.list()', () => {
+    it('returns empty list when root does not exist', async () => {
+        const d = new SkillDiscovery([{ path: '/nonexistent/path', scope: 'system' }]);
+        expect(await d.list()).toEqual([]);
+    });
+    it('discovers a valid skill', async () => {
+        const root = path.join(tmpDir, 'basic');
+        await makeSkillDir(root, 'git', 'name: git\ndescription: Git skill');
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }]);
+        const entries = await d.list();
+        expect(entries).toHaveLength(1);
+        expect(entries[0].name).toBe('git');
+        expect(entries[0].description).toBe('Git skill');
+        expect(entries[0].scope).toBe('system');
+    });
+    it('skips directories without SKILL.md', async () => {
+        const root = path.join(tmpDir, 'skip');
+        await fs.mkdir(path.join(root, 'empty-dir'), { recursive: true });
+        await makeSkillDir(root, 'real', 'name: real');
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }]);
+        const entries = await d.list();
+        expect(entries).toHaveLength(1);
+        expect(entries[0].name).toBe('real');
+    });
+    it('user scope takes priority over system scope for same name', async () => {
+        const userRoot = path.join(tmpDir, 'priority-user');
+        const sysRoot = path.join(tmpDir, 'priority-sys');
+        await makeSkillDir(userRoot, 'shared', 'name: shared\ndescription: user version');
+        await makeSkillDir(sysRoot, 'shared', 'name: shared\ndescription: system version');
+        const d = new SkillDiscovery([
+            { path: userRoot, scope: 'user' },
+            { path: sysRoot, scope: 'system' },
+        ]);
+        const entries = await d.list();
+        expect(entries).toHaveLength(1);
+        expect(entries[0].description).toBe('user version');
+        expect(entries[0].scope).toBe('user');
+    });
+    it('returns entries sorted by name', async () => {
+        const root = path.join(tmpDir, 'sorted');
+        for (const name of ['zebra', 'alpha', 'mango']) {
+            await makeSkillDir(root, name, `name: ${name}`);
+        }
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }]);
+        const names = (await d.list()).map((e) => e.name);
+        expect(names).toEqual([...names].sort());
+    });
+    it('marks skill ineligible when validator reports missing bin', async () => {
+        const root = path.join(tmpDir, 'ineligible-bin');
+        await makeSkillDir(root, 'gh', 'name: gh\nrequires: bin:definitely-not-a-real-bin-xyz');
+        const validator = {
+            checkBin: async () => false,
+            checkEnv: () => true,
+            checkOs: () => true,
+        };
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }], validator);
+        const [entry] = await d.list();
+        expect(entry.eligible).toBe(false);
+        expect(entry.missing[0].kind).toBe('bin');
+    });
+    it('marks skill ineligible when validator reports missing env', async () => {
+        const root = path.join(tmpDir, 'ineligible-env');
+        await makeSkillDir(root, 'api', 'name: api\nrequires: env:MISSING_API_KEY');
+        const validator = {
+            checkBin: async () => true,
+            checkEnv: () => false,
+            checkOs: () => true,
+        };
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }], validator);
+        const [entry] = await d.list();
+        expect(entry.eligible).toBe(false);
+        expect(entry.missing[0].kind).toBe('env');
+    });
+    it('marks skill ineligible when OS does not match', async () => {
+        const root = path.join(tmpDir, 'ineligible-os');
+        await makeSkillDir(root, 'platform', `name: platform\nos: unsupported-os-xyz`);
+        const validator = {
+            checkBin: async () => true,
+            checkEnv: () => true,
+            checkOs: () => false,
+        };
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }], validator);
+        const [entry] = await d.list();
+        expect(entry.eligible).toBe(false);
+        expect(entry.missing[0].kind).toBe('os');
+    });
+    it('exposes always flag', async () => {
+        const root = path.join(tmpDir, 'always');
+        await makeSkillDir(root, 'memory', 'name: memory\nalways: true');
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }]);
+        const [entry] = await d.list();
+        expect(entry.always).toBe(true);
+    });
+});
+describe('SkillDiscovery.load()', () => {
+    it('returns full SKILL.md content including frontmatter', async () => {
+        const root = path.join(tmpDir, 'load');
+        const dir = await makeSkillDir(root, 'mskill', 'name: mskill', 'This is the body.');
+        const filePath = path.join(dir, 'SKILL.md');
+        const d = new SkillDiscovery([{ path: root, scope: 'system' }]);
+        const content = await d.load(filePath);
+        expect(content).toContain('name: mskill');
+        expect(content).toContain('This is the body.');
+    });
+});
+//# sourceMappingURL=discovery.test.js.map

package/dist/discovery/discovery.test.js.map

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

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=frontmatter.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.test.d.ts","sourceRoot":"","sources":["../../src/discovery/frontmatter.test.ts"],"names":[],"mappings":""}

package/dist/discovery/frontmatter.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { parseFrontmatter } from './frontmatter.js';
+const wrap = (body, content = '') => `---\n${body}\n---\n${content}`;
+describe('parseFrontmatter', () => {
+    it('returns defaults when no frontmatter', () => {
+        const fm = parseFrontmatter('just markdown');
+        expect(fm.name).toBeNull();
+        expect(fm.description).toBeNull();
+        expect(fm.always).toBe(false);
+        expect(fm.requiresBins).toEqual([]);
+        expect(fm.requiresEnvs).toEqual([]);
+        expect(fm.requiresOs).toEqual([]);
+    });
+    it('parses basic fields', () => {
+        const fm = parseFrontmatter(wrap('name: github\ndescription: GitHub CLI skill\nalways: true'));
+        expect(fm.name).toBe('github');
+        expect(fm.description).toBe('GitHub CLI skill');
+        expect(fm.always).toBe(true);
+    });
+    it('parses requires string', () => {
+        const fm = parseFrontmatter(wrap('name: git\nrequires: bin:git,env:GITHUB_TOKEN'));
+        expect(fm.requiresBins).toContain('git');
+        expect(fm.requiresEnvs).toContain('GITHUB_TOKEN');
+    });
+    it('handles quoted description', () => {
+        const fm = parseFrontmatter(wrap('name: x\ndescription: "hello world"'));
+        expect(fm.description).toBe('hello world');
+    });
+    it('ignores unknown boolean values and uses fallback', () => {
+        const fm = parseFrontmatter(wrap('name: x\nalways: maybe'));
+        expect(fm.always).toBe(false);
+    });
+    it('parses top-level os field', () => {
+        const fm = parseFrontmatter(wrap('name: tmux\nos: darwin,linux'));
+        expect(fm.requiresOs).toContain('darwin');
+        expect(fm.requiresOs).toContain('linux');
+    });
+});
+//# sourceMappingURL=frontmatter.test.js.map

package/dist/discovery/frontmatter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.test.js","sourceRoot":"","sources":["../../src/discovery/frontmatter.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,OAAO,GAAG,EAAE,EAAE,EAAE,CAC1C,QAAQ,IAAI,UAAU,OAAO,EAAE,CAAC;AAElC,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,EAAE,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;QAC7C,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC3B,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,CAAC;QAClC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;QAC7B,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC,CAAC;QAC/F,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/B,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAChD,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wBAAwB,EAAE,GAAG,EAAE;QAChC,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC,CAAC;QACnF,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC,CAAC;QACzE,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC;QAC5D,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,CAAC;QAClE,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devxiyang/agent-skill",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "SDK for skill discovery and registration — integrates into any agent",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "vitest run tests",
+    "test:watch": "vitest tests"
   },
   "peerDependencies": {
     "@types/node": ">=18"

package/skills/jq/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: jq
+description: Process and transform JSON data using jq. Use when filtering API responses, extracting fields, reshaping JSON, or querying structured data.
+requires: bin:jq
+tags: json,jq
+---
+
+# jq Skill
+
+## Preflight
+
+Verify jq is available before proceeding:
+
+```bash
+jq --version
+```
+
+If missing, load `references/install.md` for installation instructions.
+
+## Basic filtering
+
+```bash
+# Pretty-print JSON
+cat data.json | jq .
+
+# Extract a field
+echo '{"name":"alice","age":30}' | jq '.name'
+
+# Nested field
+echo '{"user":{"email":"a@b.com"}}' | jq '.user.email'
+
+# Array index
+echo '[1,2,3]' | jq '.[0]'
+
+# Array slice
+echo '[1,2,3,4,5]' | jq '.[2:4]'
+```
+
+## Iterating arrays
+
+```bash
+# Iterate all elements
+curl -s "https://api.example.com/users" | jq '.[]'
+
+# Extract field from each element
+curl -s "https://api.example.com/users" | jq '.[].name'
+
+# Same with pipe
+curl -s "https://api.example.com/users" | jq '.[] | .name'
+```
+
+## Selecting & filtering
+
+```bash
+# Filter array by condition
+jq '[.[] | select(.age > 25)]' data.json
+
+# Filter by string match
+jq '[.[] | select(.status == "active")]' data.json
+
+# Filter by field existence
+jq '[.[] | select(.email != null)]' data.json
+```
+
+## Transforming
+
+```bash
+# Build a new object
+jq '{id: .id, label: .name}' data.json
+
+# Map over array
+jq '[.[] | {id: .id, label: .name}]' data.json
+
+# Append a field
+jq '. + {processed: true}' data.json
+
+# keys, values, length
+jq 'keys' data.json
+jq '.items | length' data.json
+```
+
+## String interpolation
+
+```bash
+jq '.[] | "User \(.name) is \(.age) years old"' data.json
+```
+
+## Combining with curl
+
+```bash
+# Extract specific field from API response
+curl -s "https://api.example.com/item/1" | jq '.data.title'
+
+# Filter and format a list
+curl -s "https://api.example.com/items" | jq '[.[] | select(.active) | {id, name}]'
+```
+
+## Raw output & compact
+
+```bash
+# Raw string output (no quotes)
+jq -r '.name' data.json
+
+# Compact output (no whitespace)
+jq -c '.' data.json
+
+# Read from file
+jq '.items' data.json
+```

package/skills/jq/references/install.md

@@ -0,0 +1,38 @@
+# Installing jq
+
+## macOS
+
+```bash
+brew install jq
+```
+
+If Homebrew is not installed, download the binary from https://jqlang.github.io/jq/download/ and place it in `/usr/local/bin`.
+
+## Windows
+
+If winget is available:
+
+```powershell
+winget install jqlang.jq
+```
+
+Download the binary directly from https://jqlang.github.io/jq/download/ — pick `jq-windows-amd64.exe`, rename to `jq.exe`, and add its location to PATH.
+
+If Chocolatey is available:
+
+```powershell
+choco install jq
+```
+
+## Linux
+
+```bash
+# Debian/Ubuntu
+sudo apt install jq
+
+# Fedora
+sudo dnf install jq
+
+# Arch
+sudo pacman -S jq
+```

package/skills/python/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: python
+description: Run Python scripts, manage environments, and use common stdlib patterns. Use for scripting, data processing, automation, and general Python development.
+requires: bin:python3
+tags: python,scripting
+---
+
+# Python Skill
+
+## Preflight
+
+Verify Python is available before proceeding:
+
+```bash
+python3 --version
+```
+
+If missing, load `references/install.md` for installation instructions.
+
+## Running scripts
+
+```bash
+python3 script.py
+python3 script.py arg1 arg2
+python3 -c "print('hello')"
+
+# Run a module
+python3 -m http.server 8000
+python3 -m json.tool data.json
+```
+
+## Virtual environments
+
+### venv (built-in)
+
+```bash
+# Create
+python3 -m venv .venv
+
+# Activate
+source .venv/bin/activate        # macOS/Linux
+.venv\Scripts\activate           # Windows
+
+# Deactivate
+deactivate
+```
+
+### uv (fast, recommended)
+
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows
+
+# Create and activate venv
+uv venv
+source .venv/bin/activate
+
+# Run without activating
+uv run script.py
+```
+
+## Package management
+
+### pip
+
+```bash
+pip install requests
+pip install -r requirements.txt
+pip freeze > requirements.txt
+pip list --outdated
+```
+
+### uv (faster alternative)
+
+```bash
+uv pip install requests
+uv pip install -r requirements.txt
+uv pip freeze > requirements.txt
+```
+
+## Common stdlib patterns
+
+### File I/O (pathlib)
+
+```python
+from pathlib import Path
+
+p = Path("data/file.txt")
+text = p.read_text()
+p.write_text("content")
+
+# Iterate files
+for f in Path("src").rglob("*.py"):
+    print(f)
+```
+
+### JSON
+
+```python
+import json
+
+# Parse
+data = json.loads('{"key": "value"}')
+data = json.load(open("data.json"))
+
+# Serialize
+json.dumps(data, indent=2)
+json.dump(data, open("out.json", "w"), indent=2)
+```
+
+### HTTP requests
+
+```python
+# Built-in (no deps)
+from urllib.request import urlopen
+import json
+
+with urlopen("https://api.example.com/data") as r:
+    data = json.loads(r.read())
+
+# With requests (install first)
+import requests
+r = requests.get("https://api.example.com/data")
+data = r.json()
+```
+
+### Subprocess
+
+```python
+import subprocess
+
+# Run and capture output
+result = subprocess.run(["git", "status"], capture_output=True, text=True)
+print(result.stdout)
+
+# Check for errors
+result = subprocess.run(["npm", "test"], check=True)
+```
+
+### Argument parsing
+
+```python
+import argparse
+
+parser = argparse.ArgumentParser(description="My script")
+parser.add_argument("input", help="Input file")
+parser.add_argument("--output", "-o", default="out.txt")
+parser.add_argument("--verbose", "-v", action="store_true")
+args = parser.parse_args()
+```

package/skills/python/references/install.md

@@ -0,0 +1,52 @@
+# Installing Python
+
+## macOS
+
+macOS ships with Python 3 from Xcode Command Line Tools:
+
+```bash
+xcode-select --install
+```
+
+To get a newer version, download from https://www.python.org/downloads/mac-osx/ and run the `.pkg` installer — no Homebrew needed.
+
+If you have Homebrew:
+
+```bash
+brew install python3
+```
+
+## Windows
+
+Download the installer from https://www.python.org/downloads/windows/ — pick the latest stable release and run the `.exe` installer. Check "Add Python to PATH" during installation.
+
+If winget is available:
+
+```powershell
+winget install Python.Python.3
+```
+
+## Linux
+
+```bash
+# Debian/Ubuntu
+sudo apt update && sudo apt install python3 python3-pip python3-venv
+
+# Fedora
+sudo dnf install python3 python3-pip
+
+# Arch
+sudo pacman -S python
+```
+
+## uv (optional, fast package manager)
+
+uv is a fast Python package and environment manager. Install it separately:
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```

package/skills/shell/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: shell
+description: Write and run shell scripts. Use for automation, file operations, pipelines, and system tasks. Covers bash/zsh (macOS/Linux) and PowerShell (Windows).
+tags: shell,cli
+---
+
+# Shell Skill
+
+## Unix (bash/zsh)
+
+### Variables & strings
+
+```bash
+name="alice"
+echo "Hello, $name"
+echo "Home is ${HOME}"
+
+# Command substitution
+files=$(ls -1 | wc -l)
+today=$(date +%Y-%m-%d)
+```
+
+### Conditionals
+
+```bash
+if [ -f "file.txt" ]; then
+  echo "exists"
+elif [ -d "dir" ]; then
+  echo "is a directory"
+else
+  echo "not found"
+fi
+
+# One-liner
+[ -f "file.txt" ] && echo "exists" || echo "missing"
+```
+
+### Loops
+
+```bash
+# Over a list
+for name in alice bob carol; do
+  echo "Hello, $name"
+done
+
+# Over files
+for f in *.log; do
+  echo "Processing $f"
+done
+
+# While loop
+while IFS= read -r line; do
+  echo "$line"
+done < input.txt
+```
+
+### Functions
+
+```bash
+greet() {
+  local name="$1"
+  echo "Hello, $name"
+}
+greet "alice"
+```
+
+### Pipes & redirection
+
+```bash
+# Pipe output
+cat file.txt | grep "error" | sort | uniq -c
+
+# Redirect stdout
+echo "log" >> output.log
+
+# Redirect stderr
+command 2>> errors.log
+
+# Redirect both
+command > output.log 2>&1
+
+# Discard output
+command > /dev/null 2>&1
+```
+
+### Error handling
+
+```bash
+# Exit on first error
+set -e
+
+# Exit on unset variable
+set -u
+
+# Catch pipe failures
+set -o pipefail
+
+# Combine (recommended for scripts)
+set -euo pipefail
+
+# Check exit code
+if ! command; then
+  echo "command failed"
+fi
+```
+
+### Useful patterns
+
+```bash
+# Find files by name
+find . -name "*.log" -type f
+
+# Find and delete
+find . -name "*.tmp" -type f -delete
+
+# Find and execute
+find . -name "*.js" -exec wc -l {} +
+
+# Filter with grep
+grep -r "TODO" src/ --include="*.ts"
+
+# Transform with awk
+awk '{print $1, $3}' data.txt
+
+# Process with xargs
+find . -name "*.log" | xargs rm -f
+```
+
+---
+
+## Windows (PowerShell)
+
+### Variables & strings
+
+```powershell
+$name = "alice"
+Write-Output "Hello, $name"
+
+# Command substitution
+$files = (Get-ChildItem).Count
+$today = Get-Date -Format "yyyy-MM-dd"
+```
+
+### Conditionals
+
+```powershell
+if (Test-Path "file.txt") {
+    Write-Output "exists"
+} elseif (Test-Path "dir" -PathType Container) {
+    Write-Output "is a directory"
+} else {
+    Write-Output "not found"
+}
+```
+
+### Loops
+
+```powershell
+# Over a list
+foreach ($name in "alice", "bob", "carol") {
+    Write-Output "Hello, $name"
+}
+
+# Over files
+Get-ChildItem *.log | ForEach-Object {
+    Write-Output "Processing $($_.Name)"
+}
+```
+
+### Functions
+
+```powershell
+function Greet {
+    param($Name)
+    Write-Output "Hello, $Name"
+}
+Greet "alice"
+```
+
+### Pipes & redirection
+
+```powershell
+# Pipe objects
+Get-Content file.txt | Select-String "error" | Sort-Object | Get-Unique
+
+# Redirect to file
+"log" | Out-File -Append output.log
+
+# Discard output
+command | Out-Null
+```
+
+### Error handling
+
+```powershell
+# Stop on error
+$ErrorActionPreference = "Stop"
+
+# Try/catch
+try {
+    SomeCommand
+} catch {
+    Write-Error "Failed: $_"
+}
+```
+
+### Useful patterns
+
+```powershell
+# Find files
+Get-ChildItem -Recurse -Filter "*.log"
+
+# Find and delete
+Get-ChildItem -Recurse -Filter "*.tmp" | Remove-Item
+
+# Search in files
+Select-String -Path "src\*.ts" -Pattern "TODO"
+```