@opendirectory.dev/skills 0.1.65 → 0.1.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendirectory.dev/skills",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/skills/blog-cover-image-cli/README.md

@@ -1,4 +1,4 @@
-# Blog Cover Image CLI
+# Blog Cover Image CLI
 
 A modern, AI-powered CLI tool designed to automatically generate high-converting, minimalist blog cover images and thumbnails using **Gemini 3.1 Flash Image Preview**. 
 
@@ -37,3 +37,114 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## Features
+- **Full AI Generation**: Uses `gemini-3.1-flash-image-preview` to generate the entire image.
+- **Smart Logo Fetching**: Pass a domain (like `vercel.com`) and the CLI automatically fetches the logo using `Brandfetch`, normalizes it to PNG via `sharp`, and injects it into the AI context.
+- **Aesthetic Control**: Bundled with `examples/` that automatically guide the model to produce clean, white-background, heavy-typography styles.
+- **Google Search Grounding**: The image generation is hooked into Google Search to pull real-time data if your title involves current events.
+- **Agent Ready**: Includes an OpenCode `SKILL.md` so your favorite AI agents can use this CLI autonomously.
+- **Self-Healing AI Generator**: Automatically validates generated images using Gemini Pro Vision to detect typos or layout issues, retrying up to 3 times with corrective feedback.
+- **Automated Publishing**: Built-in CI/CD workflow for seamless NPM releases via GitHub Actions.
+
+---
+
+## Installation
+
+You can install this globally via npm:
+
+```bash
+npm install -g blog-cover-image-cli
+```
+
+*(Note: Ensure you are using Node.js v18+)*
+
+---
+
+## Configuration
+
+The CLI securely stores your API key on your local machine using the `conf` package so you don't have to export it every time.
+
+```bash
+# 1. Set your Gemini API Key (Required for image generation)
+blog-cover-cli config set-key <YOUR_GEMINI_API_KEY>
+
+# 2. Set your Brandfetch Client ID (Required to fetch high-res logos)
+blog-cover-cli config set-brandfetch-id <YOUR_BRANDFETCH_CLIENT_ID>
+
+# Check your keys (masked)
+blog-cover-cli config get-key
+blog-cover-cli config get-brandfetch-id
+```
+
+*If you run the generate command without a key, a secure, interactive prompt will ask you for it.*
+
+---
+
+## Usage
+
+Generate a 16:9 cover image by providing a title and a domain name for the logo.
+
+```bash
+# Example 1: Cursor
+blog-cover-cli generate -t "Why Cursor is the Ultimate AI Code Editor" -l "cursor.com"
+
+# Example 2: Lovable
+blog-cover-cli generate -t "Building Apps in Minutes with Lovable" -l "lovable.dev"
+
+# Example 3: X (Twitter)
+blog-cover-cli generate -t "The Future of Real-time Information" -l "x.com"
+```
+
+### Options
+
+| Flag | Full Name | Description | Required | Default |
+|---|---|---|---|---|
+| `-t` | `--title` | The exact text to render on the cover | **Yes** | |
+| `-l` | `--logo` | The domain to fetch the logo from (e.g. `google.com`) | No | |
+| `-o` | `--output` | The output path for the PNG file | No | `./output/<auto-name>.png` |
+
+If you omit the `--output` flag, the CLI automatically creates an `output/` directory in your current path and names the file intelligently based on the logo domain or title (e.g., `output/cursor-cover.png`).
+
+---
+
+## For AI Agents (OpenCode Skill)
+
+This package includes a structured OpenCode skill! Agents can install this package and read the instructions in `agent-skill/blog-cover-generator/SKILL.md` to learn how to generate cover images for users autonomously. 
+
+**Workflow for Agents:**
+1. Execute `npx -p blog-cover-image-cli blog-cover-cli config set-key $KEY`
+2. Execute `npx -p blog-cover-image-cli blog-cover-cli generate -t "Title" -l "domain.com"`
+3. Return the generated image to the user.
+
+---
+
+## Self-Healing AI Generator
+
+The CLI features a built-in Automated QA (Critic) loop to ensure high-quality results. 
+
+1. **Generation**: The tool generates an image based on your title and logo.
+2. **Validation**: It uses `gemini-3.1-pro-preview` to OCR the generated image and check for typos, layout issues, or missing elements.
+3. **Self-Correction**: If the validation fails, the CLI automatically retries (up to 3 times), passing the specific "critical feedback" back to the generator to fix the errors.
+
+This ensures that common AI image generation issues, like misspelled words in typography, are caught and corrected before you even see the file.
+
+---
+
+## Automated Publishing (CI/CD)
+
+This repository includes a GitHub Action workflow for automated NPM publishing. To set this up for your fork:
+
+1. **Generate Token**: Go to [npmjs.com](https://www.npmjs.com/), navigate to **Access Tokens**, and generate a new "Automation" token.
+2. **Add Secret**: In your GitHub repository, go to **Settings > Secrets and variables > Actions**.
+3. **Save Secret**: Create a new repository secret named `NPM_TOKEN` and paste your token.
+
+The workflow will automatically publish a new version to NPM whenever you create a new GitHub Release.
+
+---
+
+## How it works under the hood
+1. **Logo Fetcher**: Hits `Brandfetch`, parses WebP/SVGs/AVIFs, and converts to strict PNGs.
+2. **Context Assembly**: Loads aesthetic examples from the `./examples` folder to ground the style.
+3. **Multimodal Prompting**: Assembles the exact text instructions, the visual examples, and the fetched logo into a single unified payload.
+4. **Google GenAI SDK**: Sends the payload with `tools: [{ googleSearch: {} }]` to the Gemini 3.1 Flash Image model.

package/skills/brand-alchemy/README.md

@@ -1,4 +1,4 @@
-# Brand Alchemy
+# Brand Alchemy
 
 <img width="1920" height="1072" alt="brand-alchemy-skill-cover-image" src="https://github.com/user-attachments/assets/15d90c97-9eef-4eed-abb3-7ce58438adf0" />
 
@@ -27,3 +27,33 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## Core Capabilities
+
+When invoked, the skill commands the AI agent to act as an elite branding consultant through a rigorous protocol:
+
+* **The Interrogation**: Forces the AI to stop and ask critical discovery questions (Core, Audience, Alternative, Vibe) to extract your brand's true DNA before generating names.
+* **Strategic Positioning**: Applies frameworks from April Dunford ("Obviously Awesome") and Category Design ("Play Bigger") to position your startup against the status quo.
+* **Phonosemantics & Lexicon Science**: Uses sound symbolism (Plosives, Fricatives, Vowel Size) to engineer names that subconsciously communicate speed, power, or luxury.
+* **Universal Domain Verification**: Automatically runs a robust Python script to check DNS and RDAP availability for any TLD (`.com`, `.io`, `.ai`, `.tech`, etc.), ensuring you don't fall in love with a taken name.
+
+## Project Structure
+
+```text
+brand-alchemy/
+├── README.md                           # Documentation
+├── SKILL.md                            # Master protocol for the AI
+├── scripts/
+│   └── domain_checker.py               # Universal domain verification script (Python)
+└── references/
+    ├── core-brand-strategy.md          # Elite positioning & category design playbook
+    └── lexicon-naming-science.md       # Phonosemantics & naming linguistics guide
+```
+
+## How to Prompt the AI
+
+Once the skill is installed, simply ask the AI to help you name your startup or build a brand strategy.
+
+> "Help me name my AI distribution startup. We help technical founders get users."
+
+The AI will automatically pause and initiate **Step 1: The Interrogation**, asking you specific questions about your core offering, audience, alternatives, and desired brand vibe.

package/skills/claude-md-generator/README.md

@@ -1,4 +1,4 @@
-# claude-md-generator
+# claude-md-generator
 
 <img width="1280" height="640" alt="claude-md-generator" src="https://github.com/user-attachments/assets/0e295271-2216-47f7-828f-845c98ef0298" />
 
@@ -28,3 +28,75 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## What It Does
+
+- Scans project files: package.json, tsconfig.json, linter configs, Makefile, directory structure
+- Extracts all build, test, lint, and dev commands
+- Identifies code style conventions that differ from defaults (path aliases, export patterns, naming)
+- Maps non-obvious architecture decisions
+- Finds gotchas: auto-generated files, required env var setup, test dependencies
+- Generates CLAUDE.md using Gemini, then verifies it stays under 200 lines
+- If CLAUDE.md already exists, improves it without discarding custom content
+
+## Requirements
+
+| Requirement | Purpose | How to Set Up |
+|------------|---------|--------------|
+| Gemini API key | CLAUDE.md generation from codebase analysis | aistudio.google.com, Get API key |
+
+## Setup
+
+```bash
+cp .env.example .env
+# Add GEMINI_API_KEY
+```
+
+## How to Use
+
+From the project root you want to document:
+```
+"Generate a CLAUDE.md for this project"
+"Create a CLAUDE.md"
+"Write Claude configuration for this repo"
+"Help Claude understand this codebase"
+```
+
+To update an existing CLAUDE.md:
+```
+"Update my CLAUDE.md: we added Vitest and changed the build system"
+"Improve my existing CLAUDE.md"
+```
+
+## What Goes in CLAUDE.md
+
+| Section | Include | Skip |
+|---------|---------|------|
+| Commands | Exact runnable commands, flags needed, env vars required | `npm install` and other obvious ones |
+| Architecture | Non-obvious structure, auto-generated directories | "src contains source files" |
+| Code Style | Path aliases, export conventions, non-default settings | Indent size (formatter handles it) |
+| Testing | Required setup, how to run one test | "we use Jest" (visible from package.json) |
+| Gotchas | Auto-generated files, env var order, known intentional issues | Things derivable from the code |
+
+## Why Under 200 Lines
+
+Long CLAUDE.md files get ignored. Claude loads the full file into context every session: a bloated CLAUDE.md with obvious content trains Claude to skim it. A tight 100-150 line CLAUDE.md with only non-obvious facts gets read and used.
+
+The skill cuts aggressively: if a section says only things Claude can infer from the code, it removes it.
+
+## Project Structure
+
+```
+claude-md-generator/
+├── SKILL.md
+├── README.md
+├── .env.example
+├── evals/
+│   └── evals.json
+└── references/
+    └── section-guide.md
+```
+
+## License
+
+MIT

package/skills/cold-email-verifier/README.md

@@ -1,4 +1,4 @@
-# Cold Email Verifier
+# Cold Email Verifier
 
 Agent Skill that equips your AI agent with the ability to autonomously guess, enrich, and verify cold email addresses directly from a CSV file.
 
@@ -30,3 +30,43 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## Verification Engines Supported
+The AI is trained to use two different verification backends:
+1. **ValidEmail.co API (Highly Recommended)**: The AI will use this SaaS API for enterprise-grade accuracy, bypassing strict catch-all servers. You can get a free tier of verification credits at validemail.co.
+2. **Reacher (Self-Hosted)**: The AI can route checks through your own self-hosted Reacher Docker container (e.g., on an AWS EC2 instance with an unblocked Port 25) for 100% free verification.
+
+## Installation
+
+To install this skill into your AI agent's workspace:
+
+1. Clone or download this folder.
+2. Copy the entire cold-email-verifier folder into your agent's skills directory (e.g., ~/.agents/skills/ or your project's .agents/skills/ folder).
+3. Ensure the dependencies in 
+equirements.txt are installed in your environment:
+   `ash
+   pip install -r requirements.txt
+   `
+4. Copy the .env.example to .env and add your ValidEmail.co API key:
+   `ash
+   cp .env.example .env
+   `
+
+## How to Prompt the AI
+
+Once the skill is installed, you can simply talk to your AI agent. Here are example prompts:
+
+**Using ValidEmail.co:**
+> "Use the cold email verifier skill to process leads.csv. Please use the validemail mode."
+
+**Using a Self-Hosted Reacher Server:**
+> "Verify the emails in leads.csv using the cold email verifier. Use reacher-http mode and point it to http://YOUR_SERVER_IP:8080/v0/check_email."
+
+The AI will automatically parse the CSV, handle the domain lookups, generate the permutations, run the verification engine, and output a clean CSV with the valid emails appended.
+
+## CSV Format Requirements
+The AI expects the input CSV to contain at least the following headers:
+- First Name
+- Last Name
+- Company Name
+- Domain Name

package/skills/competitor-pr-finder/README.md

@@ -1,4 +1,4 @@
-# competitor-pr-finder
+# competitor-pr-finder
 
 Give it your product URL. It finds your top 5 competitors, researches every press mention, podcast appearance, and community post across all of them, and tells you exactly which channels to pitch -- with the journalist's name, the angle that got your competitors featured, and a ready-to-send cold pitch for your product.
 
@@ -57,3 +57,71 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## Setup
+
+```bash
+cp .env.example .env
+# Add TAVILY_API_KEY (required) and FIRECRAWL_API_KEY (optional)
+```
+
+## Usage
+
+```
+Find my PR targets: https://yourstartup.com
+```
+
+Or paste a description if you don't have a live URL:
+```
+Find PR targets for my startup. We build [what you do] for [who]. [Stage], [geography].
+```
+
+## Cost
+
+| Operation | Searches | Cost |
+|---|---|---|
+| Product page fetch | 1 Firecrawl or Tavily extract | ~$0.001 |
+| Competitor discovery | 2 Tavily searches | ~$0.02 |
+| 3-track PR research (5 competitors) | 15 Tavily searches | ~$0.15 |
+| Journalist lookup (up to 7 Tier 1 channels) | ~6 Tavily searches | ~$0.06 |
+| **Total** | **~23-24 searches** | **~$0.23/run** |
+
+## Zero-Hallucination Policy
+
+Every channel name in the output traces to a URL in the search results. Every journalist name traces to a search result snippet. Story angles are extracted from article titles found by Tavily -- not inferred from AI training knowledge. Fields that could not be sourced are labeled "not found in search data."
+
+## Project Structure
+
+```
+competitor-pr-finder/
+├── SKILL.md                    -- 10-step workflow for Claude Code
+├── README.md                   -- this file
+├── .env.example                -- environment variable template
+├── scripts/
+│   └── research.py             -- two-phase Tavily data collector
+├── evals/
+│   └── evals.json              -- 5 test cases
+└── references/
+    ├── pr-channel-types.md     -- how to identify editorial, podcast, community channels
+    ├── pitch-guide.md          -- cold pitch structure, forbidden phrases, angle extraction
+    └── tier-scoring.md         -- channel tiering rules and frequency map construction
+```
+
+## Standalone Script Usage
+
+```bash
+# Phase 1: competitor discovery
+python3 scripts/research.py \
+    --phase discover \
+    --product-analysis /tmp/cprf-product-analysis.json \
+    --tavily-key "$TAVILY_API_KEY" \
+    --output /tmp/cprf-competitors-raw.json
+
+# Phase 2: PR research on confirmed competitors
+python3 scripts/research.py \
+    --phase pr-research \
+    --competitors /tmp/cprf-competitors-confirmed.json \
+    --product-analysis /tmp/cprf-product-analysis.json \
+    --tavily-key "$TAVILY_API_KEY" \
+    --output /tmp/cprf-pr-raw.json
+```

package/skills/cook-the-blog/README.md

@@ -1,4 +1,4 @@
-# cook-the-blog
+# cook-the-blog
 
 <img width="1280" height="640" alt="cook-the-blog-cover" src="https://github.com/user-attachments/assets/01fc87a2-78a8-433d-8531-a06a6a6df617" />
 
@@ -27,3 +27,84 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## Prerequisites & Dependencies
+
+Before running the skill, the AI agent needs access to several external tools, APIs, and environment details.
+
+**Agent Instruction:** Before executing the pipeline for the first time, you (the AI Agent) must explicitly ask the user for any missing configuration details listed below (Target Repo, GCS Bucket, Email, etc.). **Do not hardcode these values into the skill.md file automatically without asking.**
+
+### 1. Tavily Search (Deep Research)
+Used for deep, high-quality web research to extract hard metrics, founder details, and GTM strategies.
+- **Setup:** You need a Tavily API key from [Tavily](https://tavily.com/).
+- **Installation:** Install the Tavily MCP server so the agent can use it natively.
+  ```bash
+  npx -y @modelcontextprotocol/server-tavily
+  ```
+- **Environment Variable:** Set `TAVILY_API_KEY` in your agent's environment or MCP config.
+
+### 2. SerpApi (SEO Keyword Research)
+Used to pull Google Trends data to find breakout search queries.
+- **Setup:** Get a SerpApi key from [SerpApi](https://serpapi.com/).
+- **Installation:** Ensure Python 3 and the `requests` / `google-search-results` libraries are installed. The user must provide a custom Python script (e.g., `blog_seo_research.py`) that queries the Google Trends API. The agent must be told the exact file path to this script.
+- **Environment Variable:** `SERPAPI_KEY`
+
+### 3. Blog Cover Image CLI
+A custom Node.js CLI tool used to generate 16:9 minimalist cover images with company logos.
+- **Installation:** Install the tool globally via npm.
+  ```bash
+  npm i -g blog-cover-image-cli
+  ```
+- **Usage:** The agent calls it via `blog-cover-cli generate -t "Title" -l "Logo URL" -o "./cover.png"`.
+
+### 4. Cloud Storage (e.g., Google Cloud Storage, AWS S3)
+Used to host the generated cover images. The user must specify which cloud provider they want to use.
+- **Setup (Example for GCP):** The user needs a Google Cloud Service Account with storage write permissions.
+- **Installation:** Install the Google Cloud SDK (`gcloud` and `gsutil`).
+- **Authentication:** The user must provide a `service-account.json` file to authenticate.
+  ```bash
+  gcloud auth activate-service-account --key-file=service-account.json
+  ```
+- **Target Bucket:** The user must provide the target bucket URL (e.g., `gs://your-bucket-name/covers/`).
+
+### 5. GitHub CLI & Git
+Used for pushing the final MDX file to the target repository.
+- **Setup:** Ensure `git` and `gh` (GitHub CLI) are installed on the host.
+- **Authentication:** Log in to the GitHub CLI using a personal access token.
+  ```bash
+  gh auth login --with-token < token.txt
+  ```
+- **Configuration:** The agent will need the user's `git config user.name` and `git config user.email` to ensure proper commit attribution.
+
+### 6. Email Notifications (SMTP)
+Used to send a final success summary to the admin.
+- **Setup:** The agent creates a Python script (`send_summary.py`) using the built-in `smtplib`.
+- **Credentials:** The user must provide a dedicated sender Gmail account and an **App Password** (not their real password), as well as the destination admin email.
+
+### 7. Stop Slop (AI Output Quality)
+Used to ensure the generated case studies avoid typical AI fluff and maintain a high-quality, human-like tone.
+- **Setup:** Add the [Stop Slop](https://github.com/hardikpandya/stop-slop) skill to your agent's loaded skills before running the generation pipeline.
+
+---
+
+## Configuration Variables to Ask For
+
+When initializing this skill, the agent must ask the user to provide or confirm the following placeholders before running the pipeline:
+
+1. **`[TARGET_REPO_URL]`**: The exact GitHub repository URL or slug (e.g., `username/my-blog-repo`).
+2. **`[TARGET_BUCKET]`**: The cloud storage bucket path (e.g., `gs://my-images-bucket/blogs/`).
+3. **`[PUBLIC_IMAGE_BASE_URL]`**: The public base URL where the uploaded images will be accessible (e.g., `https://storage.googleapis.com/my-images-bucket/blogs/`).
+4. **`[GIT_USER_NAME]` & `[GIT_USER_EMAIL]`**: The exact name and email to use for Git commit authorship.
+5. **`[ADMIN_EMAIL]`**: Where to send the final summary report.
+6. **`[SENDER_EMAIL]` & `[SENDER_APP_PASSWORD]`**: The credentials for the SMTP Python script.
+7. **`[PATH_TO_SEO_SCRIPT]`**: The exact path to the Python script that handles the SerpApi Google Trends queries.
+8. **Brand Promotion Link**: The URL and pitch text to inject into the final FAQ of the MDX template (e.g., "If you want to build this, check out [MyBrand](https://mybrand.com)").
+
+---
+
+## How to Run
+
+1. Once the user has provided the environment variables and configuration details, place the `skill.md` file in your agent's workspace.
+2. The agent will read `skill.md` to understand the 8-step execution loop.
+3. Trigger the agent by saying: *"Run the case study generator for [Company Name]."*
+4. The agent will autonomously execute the entire pipeline from research to deployment.

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

@@ -1,4 +1,4 @@
-# dependency-update-bot
+# dependency-update-bot
 
 <img width="1280" height="640" alt="dependency-update-bot" src="https://github.com/user-attachments/assets/08939280-bba2-4ac9-a349-2ca8c25ca328" />
 
@@ -28,3 +28,98 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## What It Does
+
+- Runs `npm outdated --json` or `pip list --outdated` to find outdated packages
+- Classifies each update as patch (low risk), minor (medium risk), or major (high risk) using semver
+- Fetches changelogs from GitHub Releases, CHANGELOG.md, or npm/PyPI registry as fallback
+- Uses Gemini to summarize what changed between old and new versions, flagging breaking changes
+- Creates a branch per risk group, updates the package file, and opens a PR with the changelog summary
+- Opens one PR per major update (since each major bump needs individual review)
+
+## Requirements
+
+| Requirement | Purpose | How to Set Up |
+|------------|---------|--------------|
+| Gemini API key | Changelog summarization | aistudio.google.com, Get API key |
+| GitHub CLI authenticated | PR creation | `gh auth login` |
+| GitHub token (optional) | Higher rate limit for changelog fetching | github.com/settings/tokens, read-only scope |
+
+## Setup
+
+```bash
+cp .env.example .env
+```
+
+Fill in:
+- `GEMINI_API_KEY` (required)
+- `GITHUB_TOKEN` (optional, increases GitHub API rate limit from 60 to 5,000 requests/hour)
+
+## How to Use
+
+Scan npm dependencies:
+```
+"Check for outdated packages"
+"Update my dependencies and open PRs"
+"Run the dependency update bot"
+```
+
+Scan pip dependencies:
+```
+"Check my Python packages for updates"
+"Scan requirements.txt for outdated dependencies"
+```
+
+Specific risk level only:
+```
+"Only open PRs for patch updates today"
+"Show me which packages have major version updates"
+```
+
+## PR Structure
+
+Each PR includes:
+- Risk level label (patch / minor / major)
+- For each package: version bump, changelog summary (3-5 bullets), breaking changes flagged with BREAKING prefix
+- How to verify section
+
+**One PR per risk group** for patch and minor updates. **One PR per package** for major updates (since each breaking change needs individual review).
+
+## Risk Classification
+
+| Level | Version Change | Example | Action |
+|-------|---------------|---------|--------|
+| Patch | Z in X.Y.Z | 4.17.19 to 4.17.21 | Safe to merge after CI passes |
+| Minor | Y in X.Y.Z | 4.17.x to 4.18.x | Review changelog before merging |
+| Major | X in X.Y.Z | 4.x.x to 5.x.x | Read changelog carefully, test thoroughly |
+
+If a patch or minor update's changelog contains BREAKING CHANGE keywords, the bot escalates it to major automatically.
+
+## Changelog Sources
+
+The bot tries these sources in order for each package:
+
+1. GitHub Releases API (best)
+2. Raw CHANGELOG.md from the repo
+3. npm registry README (fallback)
+4. PyPI project description (last resort)
+
+If no changelog is found, the PR still includes the version bump with a note to review manually.
+
+## Project Structure
+
+```
+dependency-update-bot/
+├── SKILL.md
+├── README.md
+├── .env.example
+├── evals/
+│   └── evals.json
+└── references/
+    └── changelog-patterns.md
+```
+
+## License
+
+MIT

package/skills/docs-from-code/README.md

@@ -1,4 +1,4 @@
-# docs-from-code
+# docs-from-code
 
 ![docs-from-code](https://github.com/user-attachments/assets/493c7c61-9aa9-48e9-a71b-7c77c8c6a949)
 
@@ -27,3 +27,95 @@ https://github.com/user-attachments/assets/cea8b565-2002-4a87-8857-d902bfcfdc1c
 4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
 
 > **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## What It Generates
+
+| Output | When |
+|--------|------|
+| `README.md` (full) | Project has no README |
+| `README.md` (sections) | README exists but API or architecture sections are stale |
+| `docs/API.md` | Project has HTTP routes |
+| Architecture section | Always, from graphify's god nodes and communities |
+| GitHub PR | When you ask it to open one |
+
+## Why graphify?
+
+The skill uses graphify as its extraction engine:
+- 20 languages via tree-sitter AST: Python, TypeScript, Go, Rust, Java, and 15 more
+- Architecture insight: god nodes and community clusters show what everything connects through
+- 71.5x fewer tokens than reading raw files, efficient on large codebases
+- SHA256 cache: re-runs only process changed files
+- Honest tagging: `EXTRACTED` (found in source) vs `INFERRED` (reasonable inference with confidence score)
+- Extracts rationale from `# NOTE:`, `# WHY:`, `# HACK:` comments and docstrings
+
+The bundled `scripts/` (TypeScript and Python AST extractors) serve as a fallback if graphify is unavailable.
+
+## Supported Languages (via graphify)
+
+Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia
+
+## Requirements
+
+- Python 3.10+ (for graphify)
+- Node.js 18+ (for fallback TypeScript extractor)
+- `gh` CLI (optional, for opening PRs automatically)
+- `GITHUB_TOKEN` env var (optional, for PRs)
+
+## Setup
+
+### 1. Install graphify
+
+```bash
+pip install graphifyy
+```
+
+No API keys needed for extraction. graphify uses your agent's existing model access.
+
+### 2. Configure (Optional)
+
+```bash
+cp .env.example .env
+# Add GITHUB_TOKEN if you want auto-PR support
+```
+
+## How to Use
+
+Be inside your project and ask:
+
+```
+"Generate a README for this project"
+"My API docs are out of date, update them from the code"
+"Create docs/API.md from my FastAPI routes"
+"Add an architecture section to our README"
+"Document this TypeScript library"
+```
+
+The agent will:
+1. Run `graphify . --no-viz` to build a knowledge graph of your codebase
+2. Read `GRAPH_REPORT.md` for god nodes, communities, and architecture insights
+3. Query the graph for routes, types, and data models
+4. Read existing docs to understand what needs updating
+5. Generate accurate docs grounded in the graph
+6. Write files and optionally open a GitHub PR
+
+## Project Structure
+
+```
+docs-from-code/
+├── SKILL.md                         # Agent instructions
+├── README.md                        # This file
+├── .env.example                     # Environment variables template
+├── scripts/
+│   ├── package.json                 # Script dependencies (ts-morph)
+│   ├── extract_ts.ts                # TypeScript/JS AST extractor
+│   └── extract_py.py                # Python AST extractor
+├── references/
+│   ├── extraction-guide.md          # Per-framework extraction notes
+│   └── output-template.md          # README and API.md templates
+└── evals/
+    └── evals.json                   # Test prompts
+```
+
+## License
+
+MIT