@opendirectory.dev/skills 0.1.0

package/skills/explain-this-pr/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: explain-this-pr
+description: Takes a GitHub PR URL or the current branch and writes a plain-English explanation of what it does and why, then posts it as a PR comment. Use when asked to explain a PR, summarize a pull request, write a plain-English description of a PR, add a summary comment to a PR, or understand what a PR changes. Trigger when a user says "explain this PR", "summarize this pull request", "what does this PR do", "add a comment explaining the PR", or shares a GitHub PR URL and asks what it does.
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: OpenDirectory
+version: 1.0.0
+---
+
+# Explain This PR
+
+Read a GitHub pull request, understand what it changes, and write a plain-English explanation. Post it as a PR comment so reviewers have instant context.
+
+---
+
+## Step 1: Check Setup
+
+Confirm `gh` is authenticated:
+
+```bash
+gh auth status
+```
+
+If not authenticated: `gh auth login` and follow the prompts.
+
+Confirm input. The user must provide one of:
+- A GitHub PR URL (e.g. `https://github.com/owner/repo/pull/123`)
+- A PR number in the current repo (e.g. `#123`)
+- The keyword "current" to use the PR for the current branch
+
+If no input, ask: "Which PR should I explain? Share the URL, PR number, or say 'current' for the active branch."
+
+---
+
+## Step 2: Fetch PR Context
+
+**Get PR metadata:**
+```bash
+gh pr view PR_URL_OR_NUMBER --json number,url,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels,state,isDraft
+```
+
+If `isDraft` is `true`, note this to the user: "This PR is still in draft. The explanation is based on its current state."
+
+**Get the diff:**
+```bash
+gh pr diff PR_URL_OR_NUMBER
+```
+
+If the diff is over 400 lines, read the `--stat` summary and the first 200 lines of the diff:
+```bash
+gh pr view PR_URL_OR_NUMBER --json files
+gh pr diff PR_URL_OR_NUMBER | head -200
+```
+
+**Get existing comments (to avoid repeating what is already there):**
+```bash
+gh pr view PR_URL_OR_NUMBER --json comments --jq '.comments[].body' 2>/dev/null | head -20
+```
+
+---
+
+## Step 3: Write the Explanation
+
+Write two paragraphs. Read each rule before writing.
+
+**Paragraph 1: What it does (technical)**
+
+- One sentence per major change
+- Name the specific files, functions, or systems that changed
+- State the before/after if the diff makes it clear
+- Include concrete numbers if present in the diff (lines removed, tables dropped, endpoints added)
+- Active voice, present tense
+
+Example:
+```
+Replaces the in-memory session cache in auth.middleware.ts with a Redis-backed cache (src/cache/redis.ts). Adds get, set, and invalidate methods to the new Redis module and wraps UserService.getById() with a 5-minute TTL. Removes the Map-based cache that was limited to a single process and caused session drift across multiple instances.
+```
+
+**Paragraph 2: Why it matters (business/product impact)**
+
+- Who benefits and how
+- What problem this solves or what risk it reduces
+- If the commit messages contain a "why", use that context
+- If there is no clear "why" in the diff or commits, omit this paragraph rather than guessing
+
+Example:
+```
+Users hitting the /api/me endpoint under load were getting inconsistent session data across server instances, causing intermittent 401 errors. This change makes session state consistent across all instances and reduces database load by eliminating one query per authenticated request.
+```
+
+**Rules for both paragraphs:**
+- No em dashes — use a comma or period
+- No filler: "this PR", "this change", "as you can see"
+- No invented outcomes. Only state impacts that are directly visible in the diff or commit messages
+- If the PR is a pure refactor with no behavior change, say that explicitly: "Refactors X to Y with no change in observable behavior."
+- Under 150 words total
+
+---
+
+## Step 4: Self-QA
+
+Before posting, check:
+
+- [ ] Paragraph 1 names specific files or functions from the diff
+- [ ] No invented metrics or outcomes
+- [ ] No em dashes
+- [ ] No filler phrases
+- [ ] Under 150 words total
+- [ ] If no clear "why" exists, paragraph 2 is omitted rather than guessing
+
+Fix any violation before posting.
+
+---
+
+## Step 5: Post as PR Comment
+
+Present the explanation to the user. Ask: "Ready to post this as a PR comment, or would you like to edit it first?"
+
+On confirmation, pass the body via stdin to handle backticks, quotes, and newlines safely:
+
+```bash
+gh pr comment PR_URL_OR_NUMBER --body-file - << 'EOF'
+EXPLANATION_HERE
+EOF
+```
+
+After posting: "Comment added. View it at: [url from Step 2]"
+
+If the user says "output only", present the explanation in a code block for manual copy-paste without posting.
+
+

package/skills/explain-this-pr/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "explain-this-pr",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Explain this PR: https://github.com/vercel/next.js/pull/12345",
+      "expected_output": "Agent runs gh pr view with the URL to get metadata (title, author, additions, deletions, changedFiles, commits). Runs gh pr diff to get the full diff. Writes two paragraphs: paragraph 1 names specific files/functions that changed (active voice, present tense, concrete details from the diff); paragraph 2 explains the business or product impact using context from the PR body or commit messages. Total under 150 words. No em dashes. No invented metrics. Asks user to confirm before posting as a comment.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Add a plain-English summary comment to PR #42 in this repo",
+      "expected_output": "Agent resolves '#42' as a PR number in the current repo. Fetches PR metadata and diff. Writes the two-paragraph explanation. Runs gh pr comment 42 --body 'explanation'. Confirms 'Comment added. View it at: [URL]'.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "What does this PR change? https://github.com/owner/repo/pull/99",
+      "expected_output": "Agent fetches PR metadata and diff. If the PR is a pure refactor with no behavior change, paragraph 1 says that explicitly. If there are no commit messages explaining why, paragraph 2 is omitted entirely rather than guessing at business impact. Output is under 150 words. Agent presents the explanation and asks whether to post it or output only.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Explain the current branch PR",
+      "expected_output": "Agent runs gh pr view without a PR number to get the PR for the current branch. If no PR exists yet for the current branch, agent informs the user and asks if they want to create one first (suggests using pr-description-writer skill). If a PR exists, proceeds normally with the two-paragraph explanation.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Explain this large PR but just give me the text, don't post it",
+      "expected_output": "Agent fetches PR context. The diff is over 400 lines, so agent reads --stat and the first 200 lines of the diff rather than the full diff. Generates the two-paragraph explanation from the available context. Notes which parts of the diff were not read. Presents the explanation in a code block without running gh pr comment. Does not ask about posting.",
+      "files": []
+    }
+  ]
+}

package/skills/google-trends-api-skills/README.md

@@ -0,0 +1,78 @@
+# Google Trends API Skills
+
+<img width="1280" height="640" alt="google-trends-skills-cover" src="https://github.com/user-attachments/assets/848aa1be-64af-4b4b-bf46-af3d0798b7ee" />
+
+Agent Skills for SEO keyword research using Google Trends data via SerpApi. Built for AI agents that generate tech and developer-focused blog content.
+
+## Skills
+
+### 1. `google-trends-api/`
+The API layer — knows how to query Google Trends through SerpApi, handle responses, manage rate limits, and cache results.
+
+### 2. `seo-keyword-research/`
+The SEO workflow — uses Google Trends data to find breakout keywords, build content structure, and generate SEO-optimized blog outlines.
+
+## Quick Start
+
+```bash
+# 1. Get a free API key (250 searches/month)
+# https://serpapi.com/
+
+# 2. Set your key
+export SERPAPI_KEY="your_key_here"
+
+# 3. Install dependency
+pip install requests
+
+# 4. Run keyword research for a blog topic
+python seo-keyword-research/scripts/blog_seo_research.py "kubernetes deployment"
+
+# 5. Or just discover trending keywords
+python google-trends-api/scripts/discover_keywords.py "AI developer tools"
+```
+
+## Directory Structure
+
+```
+google-trends-api/
+├── SKILL.md                        # API skill (endpoints, params, usage)
+├── scripts/
+│   └── discover_keywords.py        # Keyword discovery script
+└── references/
+    └── api-responses.md            # Full API response structures
+
+seo-keyword-research/
+├── SKILL.md                        # SEO workflow skill (research -> outline)
+├── scripts/
+│   └── blog_seo_research.py        # Full blog SEO research script
+└── references/
+    ├── keyword-placement-guide.md  # Detailed keyword placement rules
+    └── tech-blog-examples.md       # Real examples for tech/dev blogs
+```
+
+## How It Works
+
+```
+User: "Write a blog about kubernetes deployment"
+  |
+  v
+[google-trends-api] RELATED_QUERIES -> finds "kubernetes vs docker" (Breakout!)
+[google-trends-api] RELATED_TOPICS  -> finds "Helm", "CI/CD", "Container Orchestration"
+  |
+  v
+[seo-keyword-research] Selects primary keyword, builds outline
+  |
+  v
+Output: SEO-optimized blog outline targeting trending keywords
+```
+
+## Specification
+
+These skills follow the [Agent Skills specification](https://agentskills.io/specification). Each skill has:
+- `SKILL.md` with YAML frontmatter (name, description, compatibility, metadata)
+- `scripts/` for executable code
+- `references/` for detailed documentation (loaded on demand)
+
+## License
+
+MIT

package/skills/google-trends-api-skills/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: google-trends-api-skills
+description: A skill for google-trends-api-skills
+author: OpenDirectory
+version: 1.0.0
+---
+

package/skills/google-trends-api-skills/google-trends-api/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: google-trends-api
+description: Query Google Trends data via SerpApi for search trend analysis, keyword discovery, topic comparison, and geographic interest patterns. Use when users need trending keyword data, want to compare search terms, or need Google Trends insights for content planning.
+license: MIT
+compatibility: Requires network access and a SerpApi API key (SERPAPI_KEY environment variable). Free tier provides 250 searches/month.
+metadata:
+  author: farizanjum
+  version: "2.0"
+  api-provider: serpapi
+allowed-tools: Bash(curl:*) Bash(python:*) Read
+---
+
+# Google Trends API Skill
+
+Query Google Trends data through SerpApi to discover trending keywords, compare topics, and analyze search interest patterns.
+
+## Prerequisites
+
+- **API Key**: Set `SERPAPI_KEY` environment variable with your SerpApi key
+- **Free Tier**: 250 searches/month (no credit card required)
+- **Sign Up**: https://serpapi.com/
+
+## API Basics
+
+**Base URL**: `https://serpapi.com/search`
+
+Every request requires these parameters:
+- `engine=google_trends`
+- `api_key` — your SerpApi private key
+- `q` — 1-5 comma-separated queries (max 100 chars each)
+- `data_type` — one of the types below
+
+## Data Types
+
+| Type | Max Queries | Purpose |
+|------|-------------|---------|
+| `RELATED_QUERIES` | 1 | Discover related search queries (rising + top) |
+| `RELATED_TOPICS` | 1 | Discover related topics searched by same users |
+| `TIMESERIES` | 5 | Track interest over time, compare terms |
+| `GEO_MAP_0` | 1 | Regional interest for a single query |
+| `GEO_MAP` | 5 | Regional comparison of multiple queries |
+
+## Common Parameters
+
+### Time Ranges (`date`)
+
+| Value | Period | Best For |
+|-------|--------|----------|
+| `today 3-m` | Past 3 months | Current trends, SEO research |
+| `today 12-m` | Past year | Trend validation |
+| `today 5-y` | Past 5 years | Seasonal patterns |
+| `now 7-d` | Last 7 days | Breaking trends |
+| `all` | 2004-present | Historical analysis |
+
+### Geographic (`geo`)
+
+- `""` (empty) = Worldwide
+- `US` = United States, `GB` = United Kingdom, `CA` = Canada
+- `US-CA` = California (state-level)
+
+### Region Granularity (`region`)
+
+`COUNTRY` | `REGION` | `DMA` | `CITY`
+
+### Platform (`gprop`)
+
+- *(empty)* = Web Search (default)
+- `youtube` | `news` | `images` | `froogle` (Shopping)
+
+## Making Requests
+
+### RELATED_QUERIES — Find related searches
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=kubernetes&data_type=RELATED_QUERIES&date=today+3-m&api_key=$SERPAPI_KEY"
+```
+
+**Response structure** — see [references/api-responses.md](references/api-responses.md) for full details:
+
+```json
+{
+  "related_queries": {
+    "rising": [
+      {"query": "kubernetes vs docker", "formatted_value": "Breakout"},
+      {"query": "kubernetes tutorial 2024", "formatted_value": "+180%"}
+    ],
+    "top": [
+      {"query": "kubernetes deployment", "value": 100}
+    ]
+  }
+}
+```
+
+- **"Breakout"** = 5000%+ growth — highest opportunity
+- **"+N%"** = year-over-year growth percentage
+
+### RELATED_TOPICS — Find related topics
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=kubernetes&data_type=RELATED_TOPICS&date=today+3-m&api_key=$SERPAPI_KEY"
+```
+
+Returns rising and top topics with titles and types.
+
+### TIMESERIES — Interest over time
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=react,vue,angular&data_type=TIMESERIES&date=today+12-m&api_key=$SERPAPI_KEY"
+```
+
+Supports up to 5 comma-separated queries for comparison. Returns timeline data with interest values (0-100 scale).
+
+### GEO_MAP_0 — Regional interest (single query)
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=kubernetes&data_type=GEO_MAP_0&geo=US&region=REGION&api_key=$SERPAPI_KEY"
+```
+
+### GEO_MAP — Regional comparison (multi-query)
+
+```bash
+curl -s "https://serpapi.com/search?engine=google_trends&q=react,vue&data_type=GEO_MAP&geo=US&region=REGION&api_key=$SERPAPI_KEY"
+```
+
+## Error Handling
+
+Always check `search_metadata.status` in the response:
+
+```python
+if response.get("search_metadata", {}).get("status") != "Success":
+    error = response.get("error", "Unknown error")
+    # Handle: invalid key, rate limit, malformed query, etc.
+```
+
+Common errors:
+- **"Invalid API key"** — check SERPAPI_KEY is set correctly
+- **"No results"** — query too niche, try broader terms
+- **"Monthly limit exceeded"** — 250 free searches used up
+
+## Rate Limit & Budget
+
+- **Free tier**: 250 searches/month
+- Failed searches are automatically refunded
+- No strict per-second rate limit, but space requests reasonably
+- Cache results for 7-14 days (trends don't change hourly)
+- Batch up to 5 queries in TIMESERIES/GEO_MAP calls to save credits
+
+## Example Script
+
+Run the discovery script for a quick keyword lookup:
+
+```bash
+python scripts/discover_keywords.py "your topic here"
+```
+
+See [scripts/discover_keywords.py](scripts/discover_keywords.py) for the full implementation.
+
+## References
+
+- [references/api-responses.md](references/api-responses.md) — Full response structures for all data types
+- [SerpApi Docs](https://serpapi.com/google-trends-api) — Official API documentation
+- [API Playground](https://serpapi.com/playground?engine=google_trends) — Test queries interactively
+- [Dashboard](https://serpapi.com/dashboard) — Track API usage

package/skills/google-trends-api-skills/google-trends-api/references/api-responses.md

@@ -0,0 +1,188 @@
+# API Response Structures
+
+Full response examples for each Google Trends data type.
+
+## RELATED_QUERIES
+
+```json
+{
+  "search_metadata": {
+    "status": "Success",
+    "id": "...",
+    "google_trends_url": "..."
+  },
+  "search_parameters": {
+    "engine": "google_trends",
+    "q": "sustainable fashion",
+    "data_type": "RELATED_QUERIES",
+    "date": "today 3-m"
+  },
+  "related_queries": {
+    "rising": [
+      {
+        "query": "eco friendly clothing brands",
+        "value": 345600,
+        "extracted_value": 345600,
+        "formatted_value": "Breakout"
+      },
+      {
+        "query": "sustainable fashion 2024",
+        "value": 18050,
+        "extracted_value": 18050,
+        "formatted_value": "+180%"
+      }
+    ],
+    "top": [
+      {
+        "query": "sustainable fashion brands",
+        "value": 100,
+        "extracted_value": 100
+      },
+      {
+        "query": "ethical fashion",
+        "value": 82,
+        "extracted_value": 82
+      }
+    ]
+  }
+}
+```
+
+### Key Fields
+
+- `rising[].formatted_value`:
+  - `"Breakout"` = 5000%+ growth (highest priority)
+  - `"+N%"` = year-over-year growth percentage
+- `top[].value`: Relative interest score (0-100 scale, 100 = most popular)
+
+## RELATED_TOPICS
+
+```json
+{
+  "search_metadata": {"status": "Success"},
+  "related_topics": {
+    "rising": [
+      {
+        "topic": {
+          "mid": "/m/...",
+          "title": "Organic Cotton",
+          "type": "Topic"
+        },
+        "value": 345600,
+        "formatted_value": "Breakout",
+        "link": "/trends/explore?..."
+      }
+    ],
+    "top": [
+      {
+        "topic": {
+          "mid": "/m/...",
+          "title": "Ethical Fashion",
+          "type": "Topic"
+        },
+        "value": 82,
+        "extracted_value": 82,
+        "link": "/trends/explore?..."
+      }
+    ]
+  }
+}
+```
+
+### Key Fields
+
+- `topic.title`: Human-readable topic name
+- `topic.type`: Usually "Topic" or a specific category
+- `formatted_value`: Same growth indicators as RELATED_QUERIES
+
+## TIMESERIES
+
+```json
+{
+  "search_metadata": {"status": "Success"},
+  "interest_over_time": {
+    "timeline_data": [
+      {
+        "date": "Jan 1 - 7, 2024",
+        "timestamp": "1704067200",
+        "values": [
+          {
+            "query": "react",
+            "value": "85",
+            "extracted_value": 85
+          },
+          {
+            "query": "vue",
+            "value": "32",
+            "extracted_value": 32
+          }
+        ]
+      },
+      {
+        "date": "Jan 8 - 14, 2024",
+        "timestamp": "1704672000",
+        "values": [
+          {
+            "query": "react",
+            "value": "88",
+            "extracted_value": 88
+          },
+          {
+            "query": "vue",
+            "value": "30",
+            "extracted_value": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Key Fields
+
+- `timeline_data[].date`: Human-readable date range
+- `timeline_data[].timestamp`: Unix timestamp
+- `values[].extracted_value`: Interest score (0-100, relative to peak)
+
+## GEO_MAP_0
+
+```json
+{
+  "search_metadata": {"status": "Success"},
+  "interest_by_region": [
+    {
+      "geo": "US-CA",
+      "location": "California",
+      "max_value_index": 0,
+      "value": 100,
+      "extracted_value": 100
+    },
+    {
+      "geo": "US-NY",
+      "location": "New York",
+      "max_value_index": 0,
+      "value": 85,
+      "extracted_value": 85
+    }
+  ]
+}
+```
+
+## GEO_MAP (multi-query)
+
+```json
+{
+  "search_metadata": {"status": "Success"},
+  "compared_breakdown_by_region": [
+    {
+      "geo": "US-CA",
+      "location": "California",
+      "values": [
+        {"query": "react", "value": "72%", "extracted_value": 72},
+        {"query": "vue", "value": "28%", "extracted_value": 28}
+      ]
+    }
+  ]
+}
+```