@devxiyang/agent-skill 0.0.7 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devxiyang/agent-skill",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "SDK for skill discovery and registration — integrates into any agent",
   "license": "MIT",
   "repository": {

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"
+```