@opendirectory.dev/skills 0.1.0

package/skills/meeting-brief-generator/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: meeting-brief-generator
+description: Takes a company name and optional contact, runs targeted research via Tavily, synthesizes a 1-page pre-call brief with Gemini, and optionally saves it to Notion. Use when asked to prepare for a meeting, research a prospect before a call, generate a company brief, create a pre-call summary, or write a meeting prep doc. Trigger when a user says "prepare me for a meeting with", "research this company before my call", "generate a meeting brief for", "I have a call with X tomorrow", or "create a prospect brief for".
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: OpenDirectory
+version: 1.0.0
+---
+
+# Meeting Brief Generator
+
+Take a company name and optional contact. Research the company via Tavily. Synthesize a 1-page pre-call brief with Gemini. Optionally save to Notion.
+
+---
+
+**Critical rule:** DO NOT INVENT SPECIFICS. Every fact, number, and claim in the brief must come from a Tavily search result. Mark any section with no search data as "Limited public information found." Never fabricate funding amounts, employee counts, or product details.
+
+---
+
+## Step 1: Setup Check
+
+Confirm required env vars:
+
+```bash
+echo "TAVILY_API_KEY: ${TAVILY_API_KEY:+set}"
+echo "GEMINI_API_KEY: ${GEMINI_API_KEY:+set}"
+echo "NOTION_TOKEN: ${NOTION_TOKEN:-not set}"
+echo "NOTION_DATABASE_ID: ${NOTION_DATABASE_ID:-not set}"
+```
+
+**If TAVILY_API_KEY is missing:**
+Stop. Tell the user: "TAVILY_API_KEY is required. Get it at app.tavily.com. Add it to your .env file."
+
+**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 NOTION_TOKEN or NOTION_DATABASE_ID is missing:**
+Continue. The brief will be output as text only. Notion saving is skipped.
+
+**Confirm input is present.**
+The user must provide at minimum a company name. If not provided, ask: "Which company are you meeting with?"
+
+---
+
+## Step 2: Gather Context
+
+Collect the following. Ask only for what is missing.
+
+Required:
+- Company name (or domain/URL if provided)
+- Meeting date
+
+Optional (do not block if missing):
+- Contact name and title
+- Meeting type (discovery, demo, follow-up, QBR)
+- Any specific topics or goals the user wants to cover
+
+If the user provides a company URL or domain, use it to make Tavily queries more precise (e.g. `site:example.com` or include the domain in search terms).
+
+---
+
+## Step 3: Research with Tavily
+
+Run these searches in sequence. Each targets one section of the brief. Save the top results from each (title, url, content snippet, score).
+
+Keep results with score >= 0.5. If a search returns 0 qualifying results, mark that section as "Limited public information found."
+
+**Search 1: Company overview**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"COMPANY\" overview founded employees headquarters",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+**Search 2: Recent news (last 30 days)**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"COMPANY\" news announcement",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true,
+    "topic": "news",
+    "time_range": "month"
+  }'
+```
+
+**Search 3: Tech stack**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"COMPANY\" technology stack engineering infrastructure tools",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+**Search 4: Product and pricing**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"COMPANY\" product features pricing use case",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+**Search 5: Competitors**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"COMPANY\" competitors alternatives vs",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+**Search 6: Funding and growth**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"COMPANY\" funding raised valuation growth",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+**If contact name is provided, run two more searches:**
+
+**Search 7: Contact profile**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"CONTACT_NAME\" \"COMPANY\" role title",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+**Search 8: Contact background**
+```bash
+curl -s -X POST "https://api.tavily.com/search" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key": "'"$TAVILY_API_KEY"'",
+    "query": "\"CONTACT_NAME\" background career LinkedIn",
+    "search_depth": "advanced",
+    "max_results": 5,
+    "include_answer": true
+  }'
+```
+
+---
+
+## Step 4: Synthesize with Gemini
+
+Read `references/brief-format.md` in full. Read `references/output-template.md` and use the template.
+
+Write the Gemini request to a temp file:
+
+```bash
+cat > /tmp/meeting-brief-request.json << 'ENDJSON'
+{
+  "system_instruction": {
+    "parts": [{
+      "text": "You are a GTM research analyst preparing a 1-page pre-call brief for a sales or business development meeting. Rules: Every claim must cite a source URL from the provided research. Use the format 'Because [finding from research], mention [point] to [goal]' for talking points. No invented data. If a section has no research data, write 'Limited public information found.' No em dashes. No banned words. Under 400 words total. The brief must be scannable in 3 minutes."
+    }]
+  },
+  "contents": [{
+    "parts": [{
+      "text": "RESEARCH_RESULTS_AND_INSTRUCTIONS_HERE"
+    }]
+  }],
+  "generationConfig": {
+    "temperature": 0.3,
+    "maxOutputTokens": 2500
+  }
+}
+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/meeting-brief-request.json \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
+```
+
+Replace `RESEARCH_RESULTS_AND_INSTRUCTIONS_HERE` with:
+- All Tavily search results (title, url, content snippet per result)
+- The brief template structure from output-template.md
+- The company name, contact name (if provided), meeting date, meeting type (if provided)
+
+---
+
+## Step 5: Self-QA
+
+Check before presenting:
+
+- [ ] No invented data. Every fact has a source URL from Tavily results.
+- [ ] Talking points use "Because [finding], mention [point] to [goal]" format
+- [ ] No em dashes in any line
+- [ ] No banned words
+- [ ] Brief is under 400 words
+- [ ] Decision Maker section says "Not specified" if no contact was provided
+- [ ] Sections with no data say "Limited public information found" rather than guessing
+- [ ] Open questions are specific to this company, not generic
+
+Fix any violation before presenting.
+
+---
+
+## Step 6: Output or Save to Notion
+
+Present the full brief in a code block.
+
+If NOTION_TOKEN and NOTION_DATABASE_ID are both set, ask: "Save this brief to Notion?"
+
+On confirmation:
+
+```bash
+cat > /tmp/notion-brief-payload.json << 'ENDJSON'
+{
+  "parent": { "database_id": "NOTION_DATABASE_ID_HERE" },
+  "properties": {
+    "Name": {
+      "title": [{ "text": { "content": "Meeting Brief: COMPANY, DATE" } }]
+    },
+    "Date": {
+      "date": { "start": "YYYY-MM-DD" }
+    }
+  },
+  "children": [
+    {
+      "object": "block",
+      "type": "paragraph",
+      "paragraph": {
+        "rich_text": [{ "type": "text", "text": { "content": "BRIEF_CONTENT_HERE" } }]
+      }
+    }
+  ]
+}
+ENDJSON
+curl -s -X POST "https://api.notion.com/v1/pages" \
+  -H "Authorization: Bearer $NOTION_TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Notion-Version: 2022-06-28" \
+  -d @/tmp/notion-brief-payload.json
+```
+
+After posting: "Brief saved to Notion. Check your database."
+
+If Notion is not configured: present the brief only. Do not mention Notion.
+
+

package/skills/meeting-brief-generator/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "meeting-brief-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Prepare me for a meeting with Acme Corp on April 15. I'm meeting Jordan Lee, their VP Engineering. It's a discovery call.",
+      "expected_output": "Agent checks TAVILY_API_KEY and GEMINI_API_KEY — both set. Confirms company name, contact, date, and meeting type from the prompt. Runs 8 Tavily searches (overview, news, tech stack, product, competitors, funding, contact profile, contact background). Filters results with score >= 0.5. Synthesizes 1-page brief with Gemini using brief-format.md rules. Brief includes all 7 sections: Company Snapshot, Recent News, Decision Maker (Jordan Lee details), Tech Stack Signals, Competitive Context, Talking Points (3-5 bullets using Because/mention/to formula), Open Questions (2-3 company-specific). Every fact has a source URL. Under 400 words. Asks if user wants to save to Notion.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Generate a meeting brief for Stripe. Meeting is tomorrow.",
+      "expected_output": "Agent detects no contact name and no meeting type in the prompt. Runs 6 Tavily searches (skips contact-specific searches). Produces complete brief with all sections. Decision Maker section reads 'Not specified.' Talking points are based on company-level research (not contact-specific). Open questions are relevant to Stripe's public situation. Agent does not ask for more info before proceeding — proceeds with available data. Brief is under 400 words.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Create a meeting brief for my call with Linear next week",
+      "expected_output": "Agent checks TAVILY_API_KEY — it is missing from environment. Agent stops immediately at Step 1. Tells the user: 'TAVILY_API_KEY is required. Get it at app.tavily.com. Add it to your .env file.' Does not run any searches or generate any content.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Prepare a brief for Vercel and save it to Notion. Meeting is April 20.",
+      "expected_output": "Agent runs full research workflow. Produces brief. Asks: 'Save this brief to Notion?' On user confirmation, writes payload to /tmp/notion-brief-payload.json and POSTs to https://api.notion.com/v1/pages with Authorization header, Notion-Version header, parent database_id, title property 'Meeting Brief: Vercel — 2026-04-20', and brief content as paragraph blocks. Reports 'Brief saved to Notion.' If NOTION_TOKEN or NOTION_DATABASE_ID are not set, agent skips the Notion prompt and outputs text only.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Prepare a brief for a company called NicheStartupXYZ123. Meeting is April 22.",
+      "expected_output": "Agent runs all 6 Tavily searches. Most return 0 or very low-score results. Agent does not invent content for empty sections. Company Snapshot reads what was found or 'Limited public information found.' Recent News reads 'No news found in the last 30 days.' Tech Stack Signals reads 'No public tech stack data found.' Talking points are based only on what search results returned. Brief is still presented (not aborted). Agent does not apologize or over-explain the lack of data.",
+      "files": []
+    }
+  ]
+}

package/skills/meeting-brief-generator/references/brief-format.md

@@ -0,0 +1,114 @@
+# Brief Format Guide
+
+## Purpose
+
+A meeting brief gives you the 3 minutes of research that makes a 30-minute call feel like you have been following this company for months. It is a reference document, not a report. Every section answers one question a prepared seller asks before a call.
+
+---
+
+## Structure (fixed, one template)
+
+```
+# Meeting Brief: {Company} — {Date}
+
+## Company Snapshot
+## Recent News
+## Decision Maker
+## Tech Stack Signals
+## Competitive Context
+## Talking Points
+## Open Questions
+```
+
+---
+
+## Section Rules
+
+### Company Snapshot
+One or two sentences maximum. Cover: what the company does, when it was founded, where it is based, approximate size (employees or revenue range), and funding stage if known. Cite the source URL inline.
+
+Do not write a paragraph. One sentence per data point is enough.
+
+Example:
+- Acme Corp builds developer tooling for Kubernetes observability, founded 2019, 120 employees, Series B ($28M, Bessemer, 2024). [Source](https://example.com)
+
+### Recent News
+Last 30 days only. Three bullets maximum. Each bullet states the event and why it matters for the call.
+
+Format: `[Event]. Source: [URL]`
+
+Skip this section entirely if no news was found in the last 30 days. Write "No news found in the last 30 days."
+
+Do not include news older than 30 days unless it is a major funding round within the last 90 days.
+
+### Decision Maker
+Name, title, tenure at the company, and one notable background fact (prior company, published work, area of focus). Cite sources.
+
+If no contact was provided: write "Not specified."
+
+Do not speculate about seniority or buying authority. Only state what research confirms.
+
+### Tech Stack Signals
+Bullet list of tools, platforms, or infrastructure visible from public sources (job postings, engineering blog, GitHub, BuiltWith-style data). Each bullet names the tool and where it was spotted.
+
+Format: `{Tool} — spotted in {job posting / engineering blog / GitHub}`
+
+If nothing was found: "No public tech stack data found."
+
+### Competitive Context
+Two to four bullets. Name the competitors and state one observable differentiator or weakness per competitor. Use research data, not assumptions.
+
+Format: `vs. {Competitor}: {one observable difference}`
+
+### Talking Points
+Three to five bullets. Each follows this exact formula from the GTM playbook:
+
+`Because [specific finding from research], mention [your point] to [goal for the conversation].`
+
+Every talking point must trace to a specific Tavily result. Do not write a talking point without a "Because" clause grounded in research.
+
+Examples:
+- Because Acme raised a Series B in January and posted 12 backend engineering roles, mention your enterprise onboarding package to understand their scaling timeline.
+- Because their engineering blog mentions a migration from monolith to microservices, mention your observability tooling to open a conversation about their infra complexity.
+
+### Open Questions
+Two to three questions specific to this company's situation. They should open discovery, not pitch. Generic questions ("What are your goals?") are not acceptable here.
+
+Format: `{Question} (based on {finding})`
+
+Examples:
+- With the recent Series B, what is the 12-month engineering headcount plan? (based on 12 open backend roles)
+- The engineering blog mentions moving to microservices last year. How is observability handled across services currently? (based on engineering blog post)
+
+---
+
+## Length and Format Rules
+
+- Under 400 words total
+- No paragraphs in the brief body (bullets and one-liners only)
+- No em dashes anywhere
+- No banned words: incredible, amazing, leveraging, game-changing, groundbreaking, pivotal, utilize, disruptive, transformative, unlock, seamless, robust
+- Every claim has a source URL
+- Sections with no data say "Limited public information found" or "Not specified" (never leave blank)
+
+---
+
+## Citation Rule
+
+Every data point must be followed by a source URL in parentheses or as a markdown link. This is non-negotiable. If you cannot cite it, do not include it.
+
+Acceptable: `120 employees ([LinkedIn](https://linkedin.com/company/acme))`
+Not acceptable: `approximately 100-150 employees`
+
+---
+
+## Validation Checklist
+
+- [ ] Under 400 words
+- [ ] Every section present (or explicitly marked as "Not found")
+- [ ] No em dashes
+- [ ] No banned words
+- [ ] Every claim has a source URL
+- [ ] Talking points use "Because/mention/to" formula
+- [ ] Open questions are company-specific, not generic
+- [ ] Decision Maker section says "Not specified" if no contact provided

package/skills/meeting-brief-generator/references/output-template.md

@@ -0,0 +1,150 @@
+# Output Template
+
+One template. The brief format is fixed. Replace every [BRACKETED SLOT] with content from Tavily results. Never leave bracket text in the output. Skip a slot with "Limited public information found" if no data exists for it.
+
+---
+
+## Template
+
+```markdown
+# Meeting Brief: [COMPANY NAME] — [MEETING DATE]
+
+Meeting type: [MEETING TYPE or "Not specified"]
+Contact: [CONTACT NAME, TITLE or "Not specified"]
+
+---
+
+## Company Snapshot
+
+[One sentence: what the company does, founded year, HQ, size, funding stage. Source URL in parentheses.]
+
+---
+
+## Recent News
+
+[Bullet 1: Event + why it matters for the call. Source URL.]
+[Bullet 2: Event + why it matters. Source URL.]
+[Bullet 3: Event + why it matters. Source URL.]
+
+(If no news found in the last 30 days, write: "No news found in the last 30 days.")
+
+---
+
+## Decision Maker
+
+[NAME]: [Title], [tenure at company]. [One background fact: prior company, area of focus, or notable work]. ([Source URL])
+
+(If no contact provided, write: "Not specified.")
+
+---
+
+## Tech Stack Signals
+
+- [Tool or platform] — spotted in [source: job posting / engineering blog / GitHub / BuiltWith] ([URL])
+- [Tool or platform] — spotted in [source] ([URL])
+
+(If nothing found, write: "No public tech stack data found.")
+
+---
+
+## Competitive Context
+
+- vs. [Competitor 1]: [One observable difference or weakness] ([URL])
+- vs. [Competitor 2]: [One observable difference] ([URL])
+
+---
+
+## Talking Points
+
+- Because [specific finding from research], mention [your point] to [goal for the conversation].
+- Because [specific finding], mention [point] to [goal].
+- Because [specific finding], mention [point] to [goal].
+
+---
+
+## Open Questions
+
+- [Question specific to this company]? (based on [finding and source])
+- [Question specific to this company]? (based on [finding and source])
+- [Question specific to this company]? (based on [finding and source])
+```
+
+---
+
+## Worked Example
+
+Company: Acme Corp (acmecorp.io)
+Contact: Jordan Lee, VP Engineering
+Meeting date: 2026-04-15
+Meeting type: Discovery
+
+```markdown
+# Meeting Brief: Acme Corp — 2026-04-15
+
+Meeting type: Discovery
+Contact: Jordan Lee, VP Engineering
+
+---
+
+## Company Snapshot
+
+Acme Corp builds Kubernetes observability tooling for platform engineering teams, founded 2019, headquartered in San Francisco, 120 employees, Series B ($28M led by Bessemer Venture Partners, January 2026). ([TechCrunch](https://techcrunch.com/acme-series-b))
+
+---
+
+## Recent News
+
+- Raised $28M Series B in January 2026 to expand enterprise sales and double engineering headcount. ([TechCrunch](https://techcrunch.com/acme-series-b))
+- Posted 12 backend engineering roles focused on Go and distributed systems in March 2026. ([Acme Careers](https://acmecorp.io/careers))
+- Published an engineering blog post on migrating their internal monolith to microservices. ([Acme Blog](https://acmecorp.io/blog/microservices))
+
+---
+
+## Decision Maker
+
+Jordan Lee: VP Engineering, joined Acme Corp in 2023. Previously Staff Engineer at Datadog for 4 years, focused on metrics ingestion pipelines. Active on LinkedIn writing about platform engineering and internal developer platforms. ([LinkedIn](https://linkedin.com/in/jordan-lee))
+
+---
+
+## Tech Stack Signals
+
+- Kubernetes — core product is built on top of it; mentioned in all job postings ([Acme Careers](https://acmecorp.io/careers))
+- Go — primary backend language, referenced in 12 open engineering roles ([Acme Careers](https://acmecorp.io/careers))
+- Prometheus — mentioned in engineering blog as current metrics stack ([Acme Blog](https://acmecorp.io/blog/microservices))
+- AWS — referenced in infrastructure job descriptions ([Acme Careers](https://acmecorp.io/careers))
+
+---
+
+## Competitive Context
+
+- vs. Datadog: Acme focuses specifically on Kubernetes-native observability vs Datadog's broader APM suite; Acme markets on lower cost and fewer agents to deploy. ([G2 Comparison](https://g2.com/compare/acme-vs-datadog))
+- vs. Grafana: Grafana requires more manual setup; Acme's value prop is opinionated defaults for platform teams. ([Acme Blog](https://acmecorp.io/blog/vs-grafana))
+
+---
+
+## Talking Points
+
+- Because Acme raised a Series B in January and posted 12 backend engineering roles, mention your enterprise onboarding package to understand their scaling timeline and whether they are building infrastructure ahead of the hire or after.
+- Because their engineering blog describes a recent monolith-to-microservices migration, mention your service mesh observability features to open a conversation about how they are currently tracking latency across services.
+- Because Jordan Lee previously worked at Datadog, mention your pricing model comparison to acknowledge they have deep familiarity with enterprise observability tooling and will ask sharp questions about cost.
+
+---
+
+## Open Questions
+
+- With 12 open backend roles and a Series B closed in January, what does the engineering headcount look like 12 months from now? (based on Acme Careers page and TechCrunch funding report)
+- The engineering blog mentions the microservices migration is ongoing. How are service-to-service latency and error rates currently tracked? (based on Acme Blog post on microservices)
+- Jordan came from Datadog. What gaps in the current observability setup prompted the search for a new tool? (based on LinkedIn profile and Acme's founding story)
+```
+
+---
+
+## Fill-In Rules
+
+1. Replace every [BRACKETED SLOT] with content from Tavily results
+2. Never leave bracket text in the output
+3. Source every claim with a URL in parentheses
+4. Skip sections with no data using "Limited public information found" or "Not specified"
+5. Talking points must follow the "Because/mention/to" formula exactly
+6. Open questions must reference a specific finding in parentheses
+7. Word count must stay under 400 words

package/skills/meta-ads-skill/README.md

@@ -0,0 +1,100 @@
+# Meta Ads Agentic Skill
+
+<img width="1376" height="768" alt="meta-ads-skill" src="https://github.com/user-attachments/assets/baf2509b-0ee0-41ca-9555-3ad350a6824c" />
+
+## Overview
+
+The **Meta Ads Skill** is a comprehensive, production-ready OpenCode skill designed to give LLMs and AI agents expert-level capabilities to orchestrate the [Varnan-Tech Meta Ads MCP Server](https://github.com/Varnan-Tech/Meta-Ads-MCP). 
+
+By using this skill, an agent transforms into an **Expert Media Buyer**. It will know exactly how to safely authenticate, explore ad structures, troubleshoot campaign performance (like CPA spikes), discover new audiences, and format massive Meta APIs JSON payloads into beautiful, readable markdown reports.
+
+---
+
+## For Agents: How to Use This Skill Efficiently
+
+This skill is designed using a **Progressive Disclosure (Hub-and-Spoke)** architecture to maximize context window efficiency:
+
+1. **The Hub (`SKILL.md`)**: The primary entry point. It provides strict guardrails, safety protocols, and the authentication troubleshooting workflow.
+2. **The Spokes (`references/` & `scripts/`)**: 
+   - When you need to perform a specific task (e.g., investigating a CPA spike), read `references/workflows.md` for the exact step-by-step orchestration strategy.
+   - When presenting data to the user, read `references/report_templates.md` to strictly follow the required Markdown layout.
+   - **Data Parsing**: Meta Ads JSON responses are massive. *Always* use the provided `scripts/formatters.py` to condense raw JSON from `get_campaigns`, `get_adsets`, or `get_insights` into clean markdown tables before reasoning over them.
+
+###  Strict Agent Guardrails
+* **Context Protection**: ALWAYS default to `time_range="last_7d"` for insights. ALWAYS use `limit=10` for listing campaigns/adsets initially.
+* **Safety First**: NEVER execute state-changing tools (`create_campaign`, `update_campaign`, `clear_database`, `reset_database`) without explicitly showing the parameters to the user and waiting for their affirmative confirmation.
+
+---
+
+## Installation & Setup of the Meta Ads MCP
+
+To use this skill, the host machine must have the Varnan-Tech Meta Ads MCP Server installed and running. 
+
+### 1. Prerequisites
+- **Python 3.10+**
+- A **Meta Developer Account** with a configured App.
+
+### 2. Configure the Meta App
+1. Go to the [Facebook Developers Portal](https://developers.facebook.com/).
+2. Create an App and add the **Marketing API** product.
+3. Under the Facebook Login settings, add `http://localhost:8000/auth/facebook/callback` to the **Valid OAuth Redirect URIs**.
+4. Retrieve your **App ID** and **App Secret**.
+
+### 3. Server Setup
+Clone the MCP repository:
+```bash
+git clone https://github.com/Varnan-Tech/Meta-Ads-MCP.git
+cd Meta-Ads-MCP
+pip install -r requirements.txt
+```
+
+Create a `.env` file in the root of the MCP server:
+```env
+FB_APP_ID="your_facebook_app_id"
+FB_APP_SECRET="your_facebook_app_secret"
+FB_OAUTH_ENABLED="true"
+FB_REDIRECT_URI="http://localhost:8000/auth/facebook/callback"
+DATABASE_URL="sqlite:///.meta-ads-mcp/oauth.db"
+```
+
+---
+
+## Authentication Workflow
+
+The server uses OAuth backed by a local SQLite database to seamlessly pass tokens to the MCP context.
+
+1. **Start the local Auth Server**:
+   ```bash
+   python src/auth/run_web_server.py
+   ```
+2. **Authenticate**: Open `http://localhost:8000/auth/facebook` in your web browser.
+3. **Grant Permissions**: Click "Connect Facebook" and approve the `ads_management`, `ads_read`, and `read_insights` permissions.
+4. **Completion**: The OAuth token is saved securely to the SQLite DB. The agent can now use the MCP tools automatically without needing the token pasted into the prompt.
+
+*If an agent encounters an Auth Error during operation, it is instructed by this skill to guide the user back through this exact login flow.*
+
+---
+
+## Skill Repository Structure
+
+When you deploy this skill, the structure will look like this:
+
+```text
+meta-ads-skill/
+ SKILL.md                          # The core router & guardrails
+ references/
+    report_templates.md           # Standardized markdown report structures
+    workflows.md                  # Orchestration strategies (e.g., CPA troubleshooting)
+ scripts/
+     auth_check.py                 # Diagnostic script for token status
+     formatters.py                 # JSON -> Markdown table utilities
+```
+
+## Supported Tools (via MCP)
+
+Through the underlying MCP, this skill orchestrates:
+* **Account Management**: `get_ad_accounts()`, `get_account_info()`
+* **Campaigns & Ads**: `get_campaigns()`, `get_adsets()`, `get_ads()`, `create_campaign()`, `update_campaign()`
+* **Analytics**: `get_insights()`, `analyze_campaigns()`
+* **Targeting**: `search_interests()`, `search_demographics()`, `estimate_audience_size()`
+* **Database**: `token_status()`, `clear_database()`, `reset_database()`

package/skills/meta-ads-skill/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: meta-ads-skill
+description: A skill for meta-ads-skill
+author: OpenDirectory
+version: 1.0.0
+---
+