@opendirectory.dev/skills 0.1.0

package/skills/claude-md-generator/references/section-guide.md

@@ -0,0 +1,175 @@
+# CLAUDE.md Section Guide
+
+What to include in each section and what to leave out.
+
+---
+
+## Canonical Section Order
+
+```markdown
+# CLAUDE.md
+
+## Project Overview
+## Commands
+## Architecture
+## Code Style
+## Testing
+## Gotchas
+```
+
+Not all sections are required. If a section has nothing non-obvious to say, omit it.
+
+---
+
+## Project Overview
+
+**Include:**
+- What the project does in one sentence (only if it is not obvious from the directory name)
+- The core tech stack if it is unusual or non-standard for the file types present
+- Any important context for understanding the codebase (e.g., "this is the billing service, not the main app")
+
+**Do not include:**
+- "This is a Next.js project" (Claude can see the files)
+- Marketing copy about what the product does for users
+- History of the project or team
+
+**Example: good:**
+```markdown
+## Project Overview
+The billing service. Handles subscription lifecycle, invoices, and Stripe webhooks. Runs as a standalone Express app; the main app in /apps/web calls it via internal API.
+```
+
+---
+
+## Commands
+
+**Include:**
+- The exact command to run the dev server
+- The exact command to run all tests
+- How to run a single test file or test by name
+- How to build for production
+- Lint/typecheck command
+- Any command that requires setup steps to work (note the setup)
+- Database migration commands if they are needed before running tests
+
+**Do not include:**
+- Commands that are self-explanatory from package.json (`npm install`, `npm start`)
+- Commands that Claude can infer from the framework
+
+**Example: good:**
+```markdown
+## Commands
+- Dev: `npm run dev` (starts on port 3000)
+- Test: `npm test` (requires `DATABASE_URL` in .env.local)
+- Test single file: `npm test -- --testPathPattern=auth`
+- Lint: `npm run lint`
+- Build: `npm run build && npm run export`
+- DB migrations: `npm run db:migrate` (run after pulling main)
+```
+
+---
+
+## Architecture
+
+**Include:**
+- Non-obvious directory organization (e.g., why `lib/` vs `utils/` exists)
+- How the main entry points connect to each other
+- External services and what they are used for
+- Any generated directories that should not be edited
+
+**Do not include:**
+- "The src directory contains source code" (obvious)
+- Framework defaults ("pages directory is for Next.js pages")
+- Descriptions of standard patterns (REST API routes, MVC structure)
+
+**Example: good:**
+```markdown
+## Architecture
+`src/api/`: Express route handlers only. Business logic lives in `src/services/`.
+`src/generated/`: Auto-generated from Prisma schema and GraphQL introspection. Do not edit these files.
+The queue workers (`src/workers/`) are separate processes; they share the database but do not import from `src/api/`.
+```
+
+---
+
+## Code Style
+
+**Include:**
+- Anything that differs from the linter/formatter default
+- Import alias mappings (`@/` = `src/`, `~components/` = `src/components/`)
+- Export convention (named vs default) if the project enforces one consistently
+- File naming convention if it differs from framework default
+- Any rule about where to put types
+
+**Do not include:**
+- Indent size and tab/space settings (the formatter enforces this)
+- "We use TypeScript" (obviously visible from the files)
+- ESLint rules that are already in .eslintrc
+
+**Example: good:**
+```markdown
+## Code Style
+- Imports: use `@/` alias for `src/` (configured in tsconfig paths and Jest moduleNameMapper)
+- Exports: named exports only: no default exports except for Next.js pages
+- Types: co-located with the code that uses them; shared types in `src/types/`
+- Components: one component per file, file name matches component name
+```
+
+---
+
+## Testing
+
+**Include:**
+- How to run tests (if not already in Commands)
+- What needs to be running for tests to pass (database, mock server, env vars)
+- Test file naming convention if non-standard
+- Where fixtures or test data live
+- Any `beforeAll` setup that is important to know about
+
+**Do not include:**
+- "We use Jest" (visible from package.json)
+- "Tests go in the tests directory" (obvious from the file structure)
+
+**Example: good:**
+```markdown
+## Testing
+Tests require a running PostgreSQL instance. Start it with `docker compose up -d db` before running `npm test`.
+Test files: `*.test.ts` next to the source file. Integration tests: `tests/integration/*.test.ts`.
+Fixtures: `tests/fixtures/`: seeded before each test suite in `tests/setup.ts`.
+```
+
+---
+
+## Gotchas
+
+**The most important section.** This is where you put the things that will waste 30+ minutes if not documented.
+
+**Always include:**
+- Things that look like they should work but do not
+- Files that are auto-generated and should not be edited manually
+- Env vars that must exist before the app starts
+- Dependencies between services (e.g., must start service A before service B)
+- Known issues that are intentional (not bugs)
+- Auth setup that differs from standard
+
+**Examples:**
+
+```markdown
+## Gotchas
+- `src/graphql/types.ts` is auto-generated by `npm run codegen`. Do not edit it directly.
+- The test database is separate from the dev database. Run `npm run db:seed:test` once before running tests for the first time.
+- `NEXT_PUBLIC_API_URL` must be set at build time (not runtime): changing it requires a rebuild.
+- The `useAuth` hook returns `null` during SSR. Guard with `if (!user)` before accessing user properties.
+- Tailwind classes are not purged during dev but are in production. If a class works in dev but disappears in production, check that it appears as a complete string (not assembled dynamically).
+```
+
+---
+
+## What CLAUDE.md is NOT
+
+- Not a README for human developers
+- Not documentation of how the framework works
+- Not a list of all dependencies
+- Not a tutorial for new team members
+
+If a section would read the same for any project using the same framework, cut it.

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

@@ -0,0 +1,86 @@
+# 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" />
+
+This guide explains how to set up, configure, and run the `cook-the-blog` skill. This AI agent pipeline autonomously researches companies, extracts SEO keywords, generates custom cover images, writes high-converting MDX case studies without AI fluff, uploads assets to cloud storage, and pushes the final code to your designated GitHub repository.
+
+## 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/cook-the-blog/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: cook-the-blog
+description: "Generate high-converting, deep-dive growth case studies in MDX format. Use this skill when asked to write a case study or blog post about a company's growth, tech stack, or product-led strategy. It handles the full pipeline (researching the company via Tavily, generating a 16:9 cover image, quality checking the draft, uploading assets to cloud storage, and pushing directly to the target repository)."
+author: OpenDirectory
+version: 1.0.0
+---
+
+# cook-the-blog Workflow
+
+Follow these steps exactly when asked to generate a case study for a company.
+
+**MANDATORY SETUP CHECK:** Before starting, ensure you have the required environment variables and target destinations configured (Target Repo, Image Bucket/Storage, Author Email, etc.). If any are missing, STOP and ask the user for them.
+
+**MANDATORY QA CHECK AT EACH STEP:** After completing every single step below, you MUST perform a strict, self-critical QA check. If a step fails or is hallucinated, you MUST retry until it succeeds. Do not fake success.
+
+## 1. Deep Research (Tavily)
+- Use the `tavily` tool (via MCP) and standard web searches to deeply research the company. **Note:** Always check if the registered business name differs from the product name. Search Reddit and other relevant forums for authentic developer insights.
+- **QA Tester:** Did you actually extract real, hard metrics and specific details about their GTM strategy, or is it generic fluff? If fluff, research deeper.
+
+## 2. SEO Keyword Research (Google Trends via SerpApi)
+- Run the python script: `export SERPAPI_KEY="[YOUR_SERPAPI_KEY]" && python3 [PATH_TO_SEO_SCRIPT] "[Company Name]"`
+- Identify the breakout and high-growth keywords from the output.
+- **QA Tester:** Did the script succeed? Are the keywords real and high-volume? If not, retry or adjust the query.
+
+## 3. Title & Cover Generation
+- **Title:** Format: `"How [Company] [Achieved X] by [Core Strategy]"`. Make it specific and highly descriptive.
+- **Cover:** Use the `blog-cover-cli generate` command to generate the cover image. **CRITICAL: The title passed to the cover image generator using the `-t` flag should contain around 7-10 words total. Do NOT use newlines (`\n`) in the string. Just provide a normal, single-line string and let the CLI handle the text wrapping automatically! Write a concise, aggressive title (e.g., `blog-cover-cli generate -t "How Baseten Scaled AI Infrastructure To a 5 Billion Valuation" -l "domain.com" -o "./cover.png"`).**
+- **QA Tester:** Was the image actually generated and saved? Verify the file exists.
+
+## 4. MDX Assembly
+Synthesize the research and write the case study in a strict MDX format.
+**Writing Rules (Use the `stop-slop` skill):**
+- Tone: Sharp, analytical, founder-focused. No fluff. Every sentence should teach something.
+- Audience: Early-stage startup founders, AI/developer tool builders, product-led growth enthusiasts.
+- Length: 1,200-1,800 words.
+- POV: Third-person analysis, like a smart investor memo written for a builder audience.
+- Do not ever use em-dashes (—).
+- Always use simple and conversational English with connector words. Avoid corporate jargon ("synergy," "leverage," "ecosystem play," "disruption" -> replace with plain language).
+- Every claim must feel backed by evidence or logic. Use specific numbers.
+- Each H3 sub-section should start with a concept sentence, then explain the mechanism, then give 1 example.
+- **Do not repeat the title in the MDX body.** The title should only exist in the frontmatter. Do NOT include an `<h1>` or `# [Title]` just before the TL;DR.
+- Never write a conclusion section. End on the takeaway paragraph or the FAQ.
+
+The MDX must follow this exact structure:
+
+```mdx
+---
+title: "How [Company] [Achieved X] by [Core Strategy]"
+description: "[1-2 sentence compelling summary with hard numbers]"
+date: "YYYY-MM-DD"
+slug: "[URL-friendly-slug-e.g.-company-name-case-study]"
+image: "[PUBLIC_IMAGE_URL]"
+readingTime: "[X] Min"
+published: true
+---
+
+<div style={{ textAlign: 'left' }}>
+
+**TL;DR**
+* **Challenge:** [The core painful problem in the market they addressed]
+* **Solution:** [What they specifically built or did differently]
+* **Results:** [2–3 hard metrics — downloads, revenue, users, growth %]
+* **Investment/Strategy:** [The one key strategic bet they made]
+
+## The Problem
+[Paint the before-state: What was the world like before this company's solution? Who was suffering, and what were they forced to do instead? Make it visceral use developer/founder language. Length: 2-3 paragraphs. No bullet points.]
+
+## The Execution & GTM Strategy
+[Break into 2–4 H3 sub-sections picking from: a) THE DISTRIBUTION STRATEGY, b) THE MONETIZATION LAYER, c) THE TECHNICAL / PRODUCT MOAT, d) THE INTERNAL DOGFOODING MOMENT, e) THE TIMING INSIGHT]
+### [H3 Sub-section]
+[Concept sentence. Mechanism. 1 Example.]
+
+## The Results & Takeaways
+[3–5 hard metrics in bullet points (downloads, revenue, customers, conversions, time saved)]
+
+**What a small startup can take from them:**
+[Actionable and specific takeaway connected directly to the target audience. Tie the lesson directly to the company's specific strategy. No generic advice.]
+
+---
+
+## Frequently Asked Questions
+
+<FAQSection>
+  <FAQItem question="[AEO Question 1 - e.g., What was their primary growth strategy?]">
+    [Fully answered in 2-4 sentences. Never leave blank.]
+  </FAQItem>
+
+  <FAQItem question="[AEO Question 2 - e.g., How do they monetize?]">
+    [Fully answered in 2-4 sentences. Never leave blank.]
+  </FAQItem>
+  
+  <FAQItem question="[Promotion Question - e.g., How can my startup replicate this?]">
+    [Answer explaining the strategy, followed by a subtle pitch for your brand/product: "If you are looking to build a predictable distribution engine like [Company], [YourBrand](https://yourdomain.com) specializes in engineering these exact growth loops. Book a strategy call to see if you are a fit."]
+  </FAQItem>
+</FAQSection>
+
+</div>
+```
+- **QA Tester:** Are there 0 em-dashes? Is it 1200-1800 words? Are there hard metrics? If not, rewrite.
+
+## 5. Quality Assurance (QA) Check
+Before proceeding, self-audit the draft again:
+- **MDX Rules:** Is it strictly following the MDX format? Are there exactly zero em-dashes?
+- **Tone:** Is it punchy and analytical?
+- **Cover Image:** Is the image generated and ready?
+
+## 6. Asset Upload
+- Upload the cover image to the user's preferred storage bucket (e.g., GCS, AWS S3, Cloudinary).
+- Command: Use the appropriate CLI tool (e.g., `gsutil cp ./cover.png [TARGET_BUCKET]`).
+- Verify the public URL matches the `image:` field in the MDX.
+- **QA Tester:** Did the upload succeed? Verify the public URL exists.
+
+## 7. GitHub Publishing (Direct Push)
+- Use `git` CLI to clone the target repository: `[TARGET_REPO_URL]`
+- Move the generated MDX file into the target directory (e.g., `blogs/`).
+- **Build Check:** Before committing, run the project's build command (e.g., `npm install && npm run build`) inside the repo to ensure the MDX syntax doesn't break the build.
+- **Git Config:** Ensure you are pushing with the correct author details. Run `git config user.name "[GIT_USER_NAME]"` and `git config user.email "[GIT_USER_EMAIL]"` before committing.
+- Commit the changes and push directly to the remote branch of `[TARGET_REPO_URL]` using `git pull upstream main --rebase && git push upstream main` (or the equivalent remote structure).
+- **QA Tester:** Did the build pass? Did the git push succeed? If not, fix the errors.
+
+## 8. Verification & Delivery
+- **DO NOT SKIP THIS:** Before completing the task, you MUST run `git log -1` and `git status` inside the repo to prove the file was committed and pushed.
+- Your final response to the user MUST include:
+  1. A detailed summary of the SerpAPI (Google Trends) research.
+  2. The public URL of the uploaded cover image.
+  3. The actual output of the `git log -1` command proving the work is done.
+- **Email Notification:** You MUST also send this exact same final summary via email to `[ADMIN_EMAIL]`. You can quickly write and execute a Python script using `smtplib` to send it from the configured sender email using an App Password.
+- **Final QA Tester:** Did you send the email? Did you include the git log in the final message? If not, you have failed the entire pipeline.
+
+

package/skills/dependency-update-bot/.env.example

@@ -0,0 +1,13 @@
+# dependency-update-bot — Environment Variables
+# ================================================
+# Gemini is required. GITHUB_TOKEN is optional but recommended.
+
+# Required: Google Gemini API key for changelog summarization
+# Get it: aistudio.google.com, Get API key
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Optional: GitHub personal access token for higher changelog fetch rate limits
+# Without this: 60 unauthenticated GitHub API requests per hour (enough for ~30 packages)
+# With this: 5,000 requests per hour
+# Get it: github.com/settings/tokens — create a fine-grained token with read-only access to public repos
+GITHUB_TOKEN=your_github_token_here

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

@@ -0,0 +1,101 @@
+# dependency-update-bot
+
+<img width="1280" height="640" alt="dependency-update-bot" src="https://github.com/user-attachments/assets/08939280-bba2-4ac9-a349-2ca8c25ca328" />
+
+
+Weekly scan for outdated npm or pip packages. Fetches changelogs for each. Summarizes breaking changes with Gemini. Opens one PR per risk group.
+
+## 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