@opendirectory.dev/skills 0.1.0

package/skills/dependency-update-bot/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: dependency-update-bot
+description: Scans your project for outdated npm, pip, Cargo, Go, or Ruby packages. Runs a CVE security audit. Fetches changelogs, summarizes breaking changes with Gemini, and opens one PR per risk group (patch, minor, major). Includes Diagnosis Mode for install conflicts. Use when asked to update dependencies, check for outdated packages, open dependency PRs, scan for package updates, audit for CVEs, or flag breaking changes in upgrades. Trigger when a user says "check for outdated packages", "update my dependencies", "open PRs for dependency updates", "scan for CVEs", or "which packages need upgrading".
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: OpenDirectory
+version: 1.0.0
+---
+
+# Dependency Update Bot
+
+Scan for outdated packages. Run a security audit. Fetch changelogs. Summarize breaking changes. Open one PR per risk group.
+
+---
+
+**Critical rule:** Only update packages that the package manager's outdated command actually reports. Never guess or invent version numbers. If a changelog cannot be fetched, note the gap rather than inventing content.
+
+---
+
+## Step 1: Setup Check
+
+```bash
+echo "GEMINI_API_KEY: ${GEMINI_API_KEY:+set}"
+echo "GITHUB_TOKEN: ${GITHUB_TOKEN:-not set, changelog fetching rate-limited to 60/hour}"
+gh auth status 2>/dev/null | head -1 || echo "gh: not authenticated"
+```
+
+**If GEMINI_API_KEY is missing:** Stop. Tell the user: "GEMINI_API_KEY is required. Get it at aistudio.google.com. Add it to your .env file."
+
+**If gh is not authenticated:** Stop. Tell the user: "GitHub CLI must be authenticated. Run: gh auth login"
+
+**Detect package manager(s):**
+
+```bash
+ls package.json 2>/dev/null && echo "npm"
+ls requirements.txt pyproject.toml 2>/dev/null && echo "pip"
+ls Cargo.toml 2>/dev/null && echo "cargo"
+ls go.mod 2>/dev/null && echo "go"
+ls Gemfile 2>/dev/null && echo "ruby"
+```
+
+If multiple are found, ask: "Found [list]. Which should I scan? (all / npm / pip / cargo / go / ruby)"
+
+---
+
+## Step 2: Detect Outdated Packages
+
+**npm:**
+```bash
+npm outdated --json --long 2>/dev/null | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for name, info in data.items():
+    print(json.dumps({'name': name, 'current': info.get('current','?'), 'latest': info.get('latest','?'), 'dep_type': info.get('type','dependencies')}))
+"
+```
+
+**pip:**
+```bash
+pip list --outdated --format=json 2>/dev/null | python3 -c "
+import sys, json
+for p in json.load(sys.stdin):
+    print(json.dumps({'name': p['name'], 'current': p['version'], 'latest': p['latest_version']}))
+"
+```
+
+**Cargo (Rust):**
+```bash
+cargo outdated --format json 2>/dev/null || \
+  cargo outdated 2>/dev/null | grep -v "^---" | tail -n +3 | head -30
+# If cargo-outdated not installed: cargo install cargo-outdated
+```
+
+**Go modules:**
+```bash
+go list -u -m -json all 2>/dev/null | python3 -c "
+import sys, json
+decoder = json.JSONDecoder()
+buf = sys.stdin.read()
+pos = 0
+while pos < len(buf):
+    try:
+        obj, idx = decoder.raw_decode(buf, pos)
+        if obj.get('Update'):
+            print(json.dumps({'name': obj['Path'], 'current': obj['Version'], 'latest': obj['Update']['Version']}))
+        pos += idx
+    except: break
+"
+```
+
+**Ruby (Bundler):**
+```bash
+bundle outdated --parseable 2>/dev/null | python3 -c "
+import sys
+for line in sys.stdin:
+    parts = line.strip().split()
+    if len(parts) >= 4:
+        print('{\"name\":\"' + parts[0] + '\",\"current\":\"' + parts[3].strip('()') + '\",\"latest\":\"' + parts[1] + '\"}')
+"
+```
+
+If all return empty: "All packages are up to date." Stop.
+
+State count before proceeding: "Found X outdated packages."
+
+---
+
+## Step 3: Classify by Risk Level
+
+Parse version bump (current → latest):
+- MAJOR: first digit changed (1.x.x → 2.x.x)
+- MINOR: second digit changed (1.2.x → 1.3.x)
+- PATCH: third digit changed (1.2.3 → 1.2.4)
+
+```bash
+python3 -c "
+def classify(current, latest):
+    try:
+        c = [int(x) for x in current.lstrip('v').split('.')[:3]]
+        l = [int(x) for x in latest.lstrip('v').split('.')[:3]]
+        if l[0] > c[0]: return 'major'
+        if len(l) > 1 and len(c) > 1 and l[1] > c[1]: return 'minor'
+        return 'patch'
+    except: return 'unknown'
+"
+```
+
+State the breakdown: "Patch: X packages. Minor: Y packages. Major: Z packages."
+
+---
+
+## Step 4: Security Audit
+
+Run a CVE scan before creating any PRs. This determines urgency.
+
+**npm:**
+```bash
+npm audit --json 2>/dev/null | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+vulns = d.get('vulnerabilities', {})
+for pkg, info in vulns.items():
+    sev = info.get('severity', 'unknown')
+    via = [v.get('title','') for v in info.get('via',[]) if isinstance(v, dict)]
+    print(f'  [{sev.upper()}] {pkg}: {via[0] if via else \"see npm audit\"}')
+" 2>/dev/null || echo "No vulnerabilities found or npm audit not available"
+```
+
+**pip:**
+```bash
+pip-audit --format=json 2>/dev/null | python3 -c "
+import sys, json
+for vuln in json.load(sys.stdin):
+    print(f'  [{vuln.get(\"aliases\",[\"\"])[0]}] {vuln[\"name\"]} {vuln[\"version\"]}: {vuln[\"description\"][:80]}')
+" 2>/dev/null || echo "pip-audit not installed. Run: pip install pip-audit"
+```
+
+**Cargo:**
+```bash
+cargo audit 2>/dev/null | grep -E "^(ID|Package|Severity|URL)" | head -30 \
+  || echo "cargo-audit not installed. Run: cargo install cargo-audit"
+```
+
+**Escalation rule:** If a PATCH or MINOR update has a Critical or High CVE, promote it to MAJOR priority: it gets its own PR and the CVE details go in the PR body.
+
+Report security findings before proceeding:
+```
+Security audit: [N] vulnerabilities found
+  [CRITICAL] lodash 4.17.19: Prototype Pollution (CVE-2021-23337)
+  [HIGH] axios 0.21.1: Server-Side Request Forgery (CVE-2021-3749)
+```
+
+If no vulnerabilities: "Security audit: clean."
+
+---
+
+## Step 5: Fetch Changelogs
+
+For each package, try sources in order. Stop at first that returns content.
+
+**Source 1: GitHub Releases API**
+
+Get repo URL from registry:
+```bash
+# npm
+curl -s "https://registry.npmjs.org/{PACKAGE}/latest" \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); r=d.get('repository',{}); print(r.get('url','') if isinstance(r,dict) else str(r))"
+
+# pip
+curl -s "https://pypi.org/pypi/{PACKAGE}/json" \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('info',{}).get('home_page','') or d.get('info',{}).get('project_urls',{}).get('Source',''))"
+```
+
+Fetch last 5 releases:
+```bash
+AUTH_HEADER=""
+[ -n "$GITHUB_TOKEN" ] && AUTH_HEADER="-H \"Authorization: Bearer $GITHUB_TOKEN\""
+curl -s $AUTH_HEADER \
+  "https://api.github.com/repos/{OWNER}/{REPO}/releases?per_page=5" \
+  | python3 -c "import sys,json; [print(json.dumps({'tag':r.get('tag_name',''),'body':r.get('body','')[:1500]})) for r in json.load(sys.stdin)]"
+```
+
+Keep releases between current and latest version only.
+
+**Source 2: npm registry README (fallback)**
+```bash
+curl -s "https://registry.npmjs.org/{PACKAGE}" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin).get('readme','')[:3000])"
+```
+
+**Source 3: PyPI description (last resort for pip)**
+```bash
+curl -s "https://pypi.org/pypi/{PACKAGE}/json" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin).get('info',{}).get('description','')[:2000])"
+```
+
+If no source returns content: note "No changelog found" and continue.
+
+---
+
+## Step 6: Summarize with Gemini
+
+One request per risk group. Include security findings for any CVE-affected packages:
+
+```bash
+cat > /tmp/deps-summary-request.json << 'ENDJSON'
+{
+  "system_instruction": {
+    "parts": [{
+      "text": "You are a developer writing a GitHub PR description for a dependency update. Given a list of packages being updated and their raw changelog content, write a concise PR body in Markdown. Rules: For each package, list only what changed between the OLD version and the NEW version. Use bullet points. Flag breaking changes with a BREAKING prefix. Flag CVE fixes with a SECURITY prefix and include the CVE ID. Keep each package section to 3-5 bullets maximum. If no changelog was found for a package, write 'No changelog available.' Do not use em dashes. Do not use these words: seamless, robust, leverage, transform, innovative. Output only the Markdown PR body, no commentary."
+    }]
+  },
+  "contents": [{
+    "parts": [{
+      "text": "PACKAGES_AND_CHANGELOGS_HERE"
+    }]
+  }],
+  "generationConfig": {
+    "temperature": 0.2,
+    "maxOutputTokens": 2048
+  }
+}
+ENDJSON
+
+curl -s -X POST \
+  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/deps-summary-request.json \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
+```
+
+---
+
+## Step 7: Create PRs
+
+One PR per non-empty risk group. One PR per package for major updates (individual review required).
+
+**1. Create branch:**
+```bash
+BRANCH="deps/{RISK}-updates-$(date +%Y%m%d)"
+git checkout -b "$BRANCH"
+```
+
+**2. Update package file:**
+
+npm:
+```bash
+npm install {package}@{latest_version} --save-exact
+# devDependencies:
+npm install {package}@{latest_version} --save-dev --save-exact
+```
+
+pip:
+```bash
+python3 -c "
+import re, sys
+pkg, version, filename = sys.argv[1], sys.argv[2], sys.argv[3]
+with open(filename) as f: content = f.read()
+pattern = rf'^{re.escape(pkg)}[>=<!\s].*$'
+new_content = re.sub(pattern, f'{pkg}=={version}', content, flags=re.MULTILINE|re.IGNORECASE)
+if new_content == content: new_content = content + f'\n{pkg}=={version}'
+open(filename, 'w').write(new_content)
+" "{PACKAGE}" "{LATEST}" "requirements.txt"
+```
+
+Cargo:
+```bash
+# Edit Cargo.toml version field for the package, then:
+cargo update {package}
+```
+
+Go:
+```bash
+go get {module}@{latest_version}
+go mod tidy
+```
+
+Ruby:
+```bash
+bundle update {gem_name}
+```
+
+**3. Commit:**
+```bash
+git add -A
+git commit -m "chore(deps): update {RISK} dependencies $(date +%Y-%m-%d)"
+```
+
+**4. Create PR:**
+```bash
+cat > /tmp/dep-pr-body-{RISK}.md << 'ENDMD'
+PR_BODY_FROM_GEMINI
+ENDMD
+
+gh pr create \
+  --title "chore(deps): update {RISK} dependencies" \
+  --body-file /tmp/dep-pr-body-{RISK}.md \
+  --label "dependencies" \
+  --base main
+```
+
+Major updates get label `dependencies,breaking-change`. CVE-fixing updates get label `dependencies,security`.
+
+After each PR, return to main: `git checkout main`
+
+---
+
+## Step 8: Diagnosis Mode
+
+**Trigger:** If any package install command fails mid-run, enter Diagnosis Mode instead of stopping.
+
+Detect the failure type:
+
+| Error pattern | Likely cause | Suggested fix |
+|---------------|-------------|--------------|
+| `peer dep conflict` | Peer dependency incompatibility | Show conflicting pair, suggest `--legacy-peer-deps` flag or downgrade |
+| `ERESOLVE` | npm resolution conflict | Run `npm install --legacy-peer-deps` for the affected package only |
+| `version not found` | Version does not exist in registry | Check registry with `npm view {pkg} versions` |
+| `python requires` | Python version incompatibility | Note required Python version, skip package |
+| `cargo E0463` | Rust edition incompatibility | Flag for manual review |
+
+Present a diagnosis summary:
+```
+Install failed for {package}: {error type}
+Likely cause: {explanation}
+Suggested fix: {specific command or action}
+Remaining packages: proceeding with {N} that succeeded.
+```
+
+Do not stop the entire run when one package fails. Continue with packages that succeed.
+
+---
+
+## Step 9: Output Summary
+
+```
+## Dependency Update Summary: [YYYY-MM-DD]
+
+### Security
+[CRITICAL] lodash: CVE-2021-23337 fixed in 4.17.21: PR #42
+[HIGH] axios: CVE-2021-3749 fixed in 0.21.4: PR #42
+
+| Risk Level | Packages | PR |
+|------------|----------|-----|
+| Patch | lodash 4.17.19→4.17.21, axios 0.21.1→0.21.4 | #42 |
+| Minor | express 4.17.1→4.18.2 | #43 |
+| Major | react 17.0.2→18.2.0 | #44 |
+
+PRs opened: 3
+
+Packages with no changelog: some-obscure-pkg (no GitHub repo in registry)
+Install failures: none
+
+Next action: Review major update PRs individually before merging.
+```
+
+

package/skills/dependency-update-bot/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "dependency-update-bot",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Check for outdated packages and open PRs. The project uses npm.",
+      "expected_output": "Agent checks GEMINI_API_KEY (set) and gh auth status (authenticated). Detects package.json. Runs npm outdated --json --long. Finds outdated packages. Classifies each by semver diff into patch, minor, or major. For each package, fetches changelog via GitHub Releases API (parses repo URL from npm registry first), falls back to raw CHANGELOG.md, falls back to npm registry README. Writes changelog content to /tmp/deps-summary-request.json and calls Gemini at temperature 0.2 for summarization. Creates one branch per risk group, runs npm install for each package in the group, commits, creates PR using gh pr create with --body-file and heredoc. States PR numbers in final summary table. Returns to main branch after each PR.",
+      "files": [
+        "package.json"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Scan my Python packages for updates.",
+      "expected_output": "Agent detects requirements.txt (or pyproject.toml). Runs pip list --outdated --format=json. Finds outdated packages. Classifies each by semver diff. For each package, fetches repo URL from PyPI JSON API and then fetches GitHub Releases. Falls back to raw CHANGELOG.md from GitHub, then PyPI project description. Groups into patch, minor, major. Creates branches, updates requirements.txt using the Python regex replacement script for each package, commits, creates PRs. Major updates each get their own branch and PR with label 'dependencies,breaking-change'. Summary table shows all PRs created.",
+      "files": [
+        "requirements.txt"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Check for outdated packages.",
+      "expected_output": "Agent detects GEMINI_API_KEY is missing. Stops immediately at Step 1. Tells the user: 'GEMINI_API_KEY is required. Get it at aistudio.google.com. Add it to your .env file.' No package scanning or PR creation attempted.",
+      "files": [],
+      "setup": "GEMINI_API_KEY not set in environment"
+    },
+    {
+      "id": 4,
+      "prompt": "Run the dependency update bot.",
+      "expected_output": "Agent runs npm outdated --json --long. Command returns empty object {}. Agent reports: 'All dependencies are up to date. Nothing to update.' No branches created, no PRs opened. Does not error or proceed to changelog fetching.",
+      "files": [
+        "package.json"
+      ],
+      "setup": "All packages already at latest versions"
+    },
+    {
+      "id": 5,
+      "prompt": "Update my dependencies. There is a major version update for react (17.0.2 to 18.2.0) and a patch update for lodash (4.17.19 to 4.17.21).",
+      "expected_output": "Agent classifies react as major (17 to 18) and lodash as patch (4.17.19 to 4.17.21). Fetches changelogs for both. For react, GitHub Releases shows BREAKING CHANGES in the migration guide. For lodash, changelog shows two CVE security fixes. Gemini summarizes each group. Creates two branches: deps/patch-updates-YYYYMMDD and deps/major-updates-YYYYMMDD (or deps/react-v18). Patch PR groups lodash with its CVE notes. Major PR for react includes the breaking change summary with BREAKING prefix. Two separate PRs opened. Patch PR gets label 'dependencies', major PR gets label 'dependencies,breaking-change'. Summary table shows both PRs.",
+      "files": [
+        "package.json"
+      ]
+    }
+  ]
+}

package/skills/dependency-update-bot/references/changelog-patterns.md

@@ -0,0 +1,201 @@
+# Changelog Patterns
+
+How to fetch and parse changelogs for npm and pip packages. Fallback strategies when the primary source has no content.
+
+---
+
+## Source Priority
+
+Try sources in this order. Stop at the first that returns usable content (more than 50 characters of actual release notes).
+
+1. GitHub Releases API (best — structured, version-tagged)
+2. Raw CHANGELOG.md from GitHub (good — often more detailed than release notes)
+3. npm registry README (fallback — unstructured but usually mentions recent changes)
+4. PyPI project description (last resort — often just the README)
+
+---
+
+## Source 1: GitHub Releases API
+
+**When it works:** The package has a GitHub repo AND publishes versioned releases with release notes.
+
+**How to find the repo URL:**
+
+For npm packages:
+```bash
+curl -s "https://registry.npmjs.org/{PACKAGE}/latest" \
+  | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+repo = d.get('repository', {})
+url = repo.get('url', '') if isinstance(repo, dict) else str(repo)
+# Clean up git+https:// or git:// prefixes
+import re
+url = re.sub(r'^git\+|^git:', '', url).replace('.git', '')
+print(url.strip())
+"
+```
+
+For PyPI packages:
+```bash
+curl -s "https://pypi.org/pypi/{PACKAGE}/json" \
+  | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+info = d.get('info', {})
+urls = info.get('project_urls') or {}
+# Try multiple URL fields in priority order
+for key in ['Source', 'Homepage', 'Repository', 'Code']:
+    if key in urls and 'github.com' in urls[key]:
+        print(urls[key])
+        break
+else:
+    hp = info.get('home_page', '')
+    print(hp if 'github.com' in hp else '')
+"
+```
+
+**Parse owner/repo from URL:**
+```bash
+python3 -c "
+import re, sys
+url = sys.argv[1]
+m = re.search(r'github\.com[/:]([^/\s]+)/([^/.\s]+)', url)
+if m:
+    print(m.group(1), m.group(2))
+else:
+    print('', '')
+" "URL_HERE"
+```
+
+**Fetch releases:**
+```bash
+curl -s ${GITHUB_TOKEN:+-H "Authorization: Bearer $GITHUB_TOKEN"} \
+  "https://api.github.com/repos/{OWNER}/{REPO}/releases?per_page=10" \
+  | python3 -c "
+import sys, json
+releases = json.load(sys.stdin)
+if isinstance(releases, dict) and 'message' in releases:
+    print('ERROR:', releases['message'])
+else:
+    for r in releases[:5]:
+        body = r.get('body') or ''
+        if body.strip():
+            print('TAG:', r.get('tag_name', ''))
+            print(body[:1500])
+            print('---')
+"
+```
+
+**Version matching:** Tags may be prefixed (`v4.17.21`, `4.17.21`, `release-4.17.21`). Strip non-numeric prefixes before comparing to package versions.
+
+---
+
+## Source 2: Raw CHANGELOG.md from GitHub
+
+**When it works:** The repo maintains a CHANGELOG.md but does not use GitHub Releases.
+
+```bash
+curl -s "https://raw.githubusercontent.com/{OWNER}/{REPO}/main/CHANGELOG.md" \
+  | head -200
+```
+
+Also try `HEAD`, `master`, `trunk` if `main` returns 404.
+
+**Extract the relevant section** (between current version header and previous version header):
+```bash
+python3 -c "
+import sys, re
+content = sys.stdin.read()
+# Find section starting with target version
+pattern = r'#+\s*\[?{TARGET_VERSION}\]?.*?(?=\n#+\s*\[?[0-9]|\Z)'
+m = re.search(pattern, content, re.DOTALL | re.IGNORECASE)
+if m:
+    print(m.group(0)[:2000])
+else:
+    print('Version section not found in CHANGELOG.md')
+"
+```
+
+---
+
+## Source 3: npm Registry README (Fallback)
+
+**When it works:** Package has no GitHub repo or does not use GitHub Releases, but includes a changelog in the README.
+
+```bash
+curl -s "https://registry.npmjs.org/{PACKAGE}" \
+  | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+readme = d.get('readme', '')
+if readme:
+    # Look for changelog section
+    import re
+    m = re.search(r'#+\s*(changelog|changes|release notes|history).*', readme, re.IGNORECASE | re.DOTALL)
+    if m:
+        print(m.group(0)[:2000])
+    else:
+        # Just print the first 1500 chars of README
+        print(readme[:1500])
+else:
+    print('No README found in registry')
+"
+```
+
+---
+
+## Source 4: PyPI Project Description (Last Resort)
+
+```bash
+curl -s "https://pypi.org/pypi/{PACKAGE}/json" \
+  | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+desc = d.get('info', {}).get('description', '')
+print(desc[:2000] if desc else 'No description found')
+"
+```
+
+---
+
+## Handling Missing Changelogs
+
+If all four sources fail or return less than 50 characters of useful content:
+
+- Record: "No changelog found for {package}"
+- In the PR body, write: "No changelog available for {package}. Review the diff manually before merging."
+- Do NOT skip the package from the PR — still include the version bump, just with no notes
+
+---
+
+## Identifying Breaking Changes
+
+Gemini handles most of this, but these patterns in raw changelog text are strong signals to flag:
+
+```
+BREAKING CHANGE:
+BREAKING:
+[BREAKING]
+!BREAKING
+Removed support for
+Dropped support for
+No longer supports
+Migration required
+Deprecated in X, removed in Y
+```
+
+If a changelog contains any of these patterns for a patch or minor update, escalate that package's risk classification to major before PR creation.
+
+---
+
+## Rate Limits
+
+| Source | Rate Limit | Auth |
+|--------|-----------|------|
+| GitHub API (unauthenticated) | 60 requests/hour | None |
+| GitHub API (with GITHUB_TOKEN) | 5,000 requests/hour | Bearer token |
+| npm registry | No documented limit (generous) | None |
+| PyPI API | No documented limit | None |
+
+For most projects (under 60 outdated packages), unauthenticated GitHub API is sufficient. Set GITHUB_TOKEN if you have more than 30-40 packages to scan (2 API calls per package).

package/skills/docs-from-code/.env.example

@@ -0,0 +1,13 @@
+# docs-from-code — Environment Variables
+# =========================================
+# Most of this skill works with zero config — it reads your codebase directly.
+# Only GitHub integration requires a token.
+
+# Optional: GitHub token for opening a PR with generated docs
+# Scopes needed: repo (read + write)
+# Get one at: https://github.com/settings/tokens
+GITHUB_TOKEN=your_github_token_here
+
+# Optional: Override the detected project root (absolute path)
+# By default the skill uses the current working directory
+# PROJECT_ROOT=/path/to/your/project