@frase/agent-skills 0.3.0

package/frase-competitive-intelligence/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: frase-competitive-intelligence
+description: Deep competitive analysis, opportunity detection, and topic clustering using Frase — analyze competitors, score opportunities, and organize content into topical clusters. Works via MCP or CLI.
+---
+
+# Frase Competitive Intelligence
+
+This skill teaches you how to analyze competitors, detect content opportunities, and organize topics into clusters using Frase.
+
+**Works with:** Frase MCP server (`@frase/mcp-server`) OR Frase CLI (`@frase/cli`)
+
+## Prerequisites
+
+- Frase MCP server connected OR `frase` CLI installed (`npx @frase/cli`)
+- `FRASE_API_KEY` environment variable set (get from https://next.frase.io/settings/api)
+- A Frase site with Google Search Console connected (for opportunity detection)
+
+## Workflow
+
+### Step 1: Analyze a Competitor Page
+
+Crawl any URL and analyze it against SERP competitors.
+
+**Via MCP:**
+```
+1. Use `start_competitive_analysis` with:
+   - url: the page URL to analyze (required)
+   - competitor_urls: array of up to 3 competitor URLs for direct comparison (optional)
+   - site_id: associate with a tracked site (optional)
+   - location_name: location for localized SERP results (optional, use `search_locations` to find exact values)
+   - industry: industry context for more targeted analysis (optional)
+2. This is async — poll with `get_competitive_analysis` using the returned ID
+3. Returns gap analysis:
+   - Missing topics the competitor covers that you don't
+   - Thin sections where you need more depth
+   - Structural gaps (missing FAQs, tables, comparison sections)
+   - Content quality comparison
+```
+
+**Via CLI:**
+```bash
+frase competitive analyze "https://competitor.com/their-article"
+frase competitive analyze "https://competitor.com/page" --competitor-urls "https://rival.com/page"
+```
+
+### Step 2: Get Detailed Analysis
+
+**Via MCP:**
+```
+1. Use `get_competitive_analysis` with the analysis ID
+2. Review detailed findings:
+   - Topic coverage comparison (your content vs theirs)
+   - Word count and depth analysis
+   - Heading structure comparison
+   - Internal/external link analysis
+```
+
+**Via CLI:**
+```bash
+frase competitive get <analysis-id>
+frase competitive get <analysis-id> --json   # full details
+```
+
+### Step 3: List Past Analyses
+
+**Via MCP:**
+```
+1. Use `list_competitive_analyses` with site_id
+2. Review historical competitive analyses
+3. Track how competitors evolve over time
+```
+
+**Via CLI:**
+```bash
+frase competitive list --site-id <id>
+```
+
+### Step 4: Detect Opportunities
+
+Frase unifies opportunity detection from multiple signals: GSC data, competitor gaps, content decay, and programmatic patterns.
+
+**Via MCP:**
+```
+1. Use `list_opportunities` with:
+   - site_id: your site ID
+   - view: "quick-wins" | "growth" | "strategic" | "all" (optional filter, default: "all")
+2. Each opportunity includes a composite score:
+   - Impact (35%): traffic potential via CTR modeling by position
+   - Effort (25%): implementation difficulty
+   - Speed (20%): estimated time to rank
+   - Strategic (20%): business value alignment
+3. Views filter by effort level:
+   - quick-wins: low effort, proven demand
+   - growth: medium effort, validated gaps
+   - strategic: high effort, high reward
+```
+
+**Via CLI:**
+```bash
+frase opportunities list --site-id <id>
+frase opportunities list --site-id <id> --view quick-wins
+frase opportunities list --site-id <id> --view growth
+frase opportunities list --site-id <id> --view strategic
+```
+
+### Step 5: Act on Opportunities
+
+**Via MCP:**
+```
+1. Use `get_opportunity` with the opportunity ID for full details
+2. Use `create_from_opportunity` to generate a brief automatically:
+   - Pulls in keyword data, competitor analysis, and gap insights
+   - Creates a pre-populated brief ready for content generation
+3. Follow the content pipeline: generate → optimize → publish
+```
+
+**Via CLI:**
+```bash
+frase opportunities get <opportunity-id>
+frase opportunities create-brief <opportunity-id> --site-id <id>
+# Then follow the content pipeline:
+frase content create --brief-id <new-brief-id>
+frase optimize start --content-id <content-id>
+```
+
+### Step 6: Organize with Topic Clusters
+
+Group content into topical clusters for authority building.
+
+**Via MCP:**
+```
+1. Use `list_clusters` to see existing topic clusters
+2. Use `create_cluster` with:
+   - name: cluster name (required)
+   - pillar_topic: main pillar topic (required)
+   - site_id: associate with a site (optional)
+3. Use `assign_to_cluster` to add content to a cluster:
+   - cluster_id: the cluster ID
+   - content_id or brief_id: what to assign
+   - role: "pillar" or "supporting"
+4. Use `suggest_clusters` with site_id for AI-powered cluster suggestions
+```
+
+**Via CLI:**
+```bash
+frase cluster list --site-id <id>
+frase cluster create "Content Marketing" --site-id <id>
+frase cluster assign <cluster-id> --content-id <id> --role supporting
+frase cluster suggest --site-id <id>      # AI-powered suggestions
+```
+
+## Opportunity Scoring Methodology
+
+| Factor | Weight | What It Measures |
+|--------|--------|------------------|
+| Impact | 35% | Traffic potential — CTR modeling by current/target position, search volume |
+| Effort | 25% | Implementation difficulty — content exists? competitors strong? |
+| Speed | 20% | Time to rank — domain authority vs competition, keyword difficulty |
+| Strategic | 20% | Business value — commercial intent, conversion potential |
+
+**Composite score:** 0-100. Higher = better opportunity.
+
+## Cluster Strategy
+
+Topic clusters build topical authority:
+
+```
+                    ┌────────────────┐
+                    │  Pillar Page   │
+                    │ "SEO Guide"   │
+                    └───────┬────────┘
+              ┌─────────────┼─────────────┐
+              ▼             ▼             ▼
+     ┌────────────┐ ┌────────────┐ ┌────────────┐
+     │ Supporting  │ │ Supporting  │ │ Supporting  │
+     │ "On-Page"  │ │ "Technical" │ │ "Link      │
+     │            │ │            │ │  Building"  │
+     └────────────┘ └────────────┘ └────────────┘
+```
+
+- **Pillar pages** cover a broad topic comprehensively
+- **Supporting pages** dive deep into subtopics
+- Internal links connect supporting pages to pillar and vice versa
+- Clusters signal topical authority to search engines and AI engines
+
+## Key Principles
+
+1. **Analyze competitors regularly** — the SERP landscape changes constantly
+2. **Act on quick wins first** — low effort, high impact opportunities compound
+3. **Use clusters for authority** — scattered content dilutes topical signals
+4. **Create from opportunities** — let data drive content creation, not guesses
+5. **Track competitor evolution** — re-analyze quarterly to catch shifts
+6. **Connect clusters to GEO** — topical authority improves AI citation rates

package/frase-content-optimization/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: frase-content-optimization
+description: Score and optimize content for SEO and GEO performance using Frase — SERP-based scoring, prioritized suggestions, and iterative improvement. Works via MCP or CLI.
+---
+
+# Frase Content Optimization
+
+This skill teaches you how to score and optimize content for SEO and GEO performance using Frase. Frase analyzes your content against top SERP competitors and provides actionable suggestions.
+
+**Works with:** Frase MCP server (`@frase/mcp-server`) OR Frase CLI (`@frase/cli`)
+
+## Prerequisites
+
+- Frase MCP server connected OR `frase` CLI installed (`npx @frase/cli`)
+- `FRASE_API_KEY` environment variable set (get from https://next.frase.io/settings/api)
+- Existing content to optimize (use `list_content` / `frase content list`)
+
+## Workflow
+
+### Step 1: Start Optimization
+
+**Via MCP:**
+```
+1. Use `start_optimization` with the content_id
+2. Frase analyzes the content against top SERP competitors
+3. Poll `get_job_status` until analysis completes (usually 15-30 seconds)
+```
+
+**Via CLI:**
+```bash
+frase optimize start --content-id <id>
+frase job status <job-id>               # poll until ready
+```
+
+### Step 2: Review Score and Suggestions
+
+**Via MCP:**
+```
+1. Use `get_optimization` with the optimization ID
+2. Review:
+   - SEO score and GEO score
+   - Suggestions count and applied count
+   - Individual suggestions grouped by type, each with an ID
+   - Priority levels (critical, high, medium, low)
+```
+
+**Via CLI:**
+```bash
+frase optimize get <optimization-id>
+frase optimize get <optimization-id> --json   # full details
+```
+
+### Step 3: Apply Suggestions Selectively
+
+**Not all suggestions are equal.** Prioritize based on impact.
+
+**Via MCP:**
+```
+1. Apply critical and high-priority suggestions first using `apply_optimization` with:
+   - id: the optimization session ID
+   - suggestion_id: the specific suggestion ID to apply (apply one at a time)
+2. Re-score after applying suggestions
+3. Skip low-priority suggestions that would compromise readability
+```
+
+**Via CLI:**
+```bash
+frase optimize apply <optimization-id> --suggestion <suggestion-id>
+```
+
+Suggestion types and how to handle them:
+- **Missing topics:** Add paragraphs covering these topics — HIGH IMPACT
+- **Topic depth:** Expand existing sections with more detail — MEDIUM IMPACT
+- **Heading structure:** Reorganize headings for better hierarchy — MEDIUM IMPACT
+- **Word count:** Extend or trim content — CONTEXT-DEPENDENT
+- **Meta tags:** Update title/description — QUICK WIN
+
+### Step 4: Re-Score After Changes
+
+**Via MCP:**
+```
+1. Use `start_optimization` again with the same content_id
+2. Compare the new score to the previous one
+3. If still below target, apply more suggestions
+4. Repeat up to 3 times (diminishing returns after that)
+```
+
+**Via CLI:**
+```bash
+frase optimize start --content-id <id>   # re-score after applying suggestions
+frase optimize get <new-optimization-id>
+```
+
+### Step 5: Dismiss Irrelevant Suggestions
+
+**Via MCP:**
+```
+1. Use `dismiss_optimization` for suggestions that don't apply
+2. This improves future optimization accuracy
+```
+
+**Via CLI:**
+```bash
+frase optimize dismiss <optimization-id> --suggestion <suggestion-id>
+```
+
+### Step 6: Cross-Content Insights
+
+**Via MCP:**
+```
+1. Use `get_optimization_insights` to see patterns across all your content:
+   - Common issues appearing in multiple articles
+   - Opportunities that affect many pages
+   - Overall content health trends
+```
+
+**Via CLI:**
+```bash
+frase optimize insights --site-id <id>
+```
+
+## Score Interpretation
+
+| Score Range | Meaning | Action |
+|-------------|---------|--------|
+| 80-100 | Excellent | Publish confidently. Minor tweaks only. |
+| 70-79 | Good | Competitive with top results. Consider a few more improvements. |
+| 50-69 | Needs work | Missing important topics. Apply high-priority suggestions. |
+| 30-49 | Significant gaps | Major revision needed. Consider regenerating from a fresh brief. |
+| 0-29 | Not competitive | Start over with research and a new brief. |
+
+## Target Scores by Content Value
+
+- **High-value keywords** (commercial intent, high volume): Target 80+
+- **Competitive keywords** (many strong competitors): Target 75+
+- **Standard keywords** (moderate competition): Target 70+
+- **Long-tail keywords** (low competition): Target 60+
+
+## Key Principles
+
+1. **Score before publishing** — never publish un-optimized content
+2. **Apply selectively** — prioritize high-impact suggestions
+3. **Re-score after changes** — verify improvements
+4. **Don't over-optimize** — readability matters more than a perfect score
+5. **Use insights** — patterns across content reveal systemic issues
+6. **SEO + GEO together** — optimize for both traditional search and AI engine citation
+
+## Common Mistakes
+
+- Applying ALL suggestions blindly (some may hurt readability)
+- Optimizing once and never re-checking after edits
+- Ignoring meta tags (quick win with high SEO impact)
+- Targeting 100 score (diminishing returns past 80, can hurt natural flow)
+- Not using insights to spot recurring issues across content
+- Ignoring GEO score (AI engines increasingly drive traffic)

package/frase-content-pipeline/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: frase-content-pipeline
+description: End-to-end content workflow using Frase — research, brief, generate, optimize, publish, and monitor AI visibility. Works via MCP tools or CLI.
+---
+
+# Frase Content Pipeline
+
+This skill teaches you the correct end-to-end content workflow using Frase. Follow these steps in order for best results.
+
+**Works with:** Frase MCP server (`@frase/mcp-server`) OR Frase CLI (`@frase/cli`)
+
+## Prerequisites
+
+- Frase MCP server connected OR `frase` CLI installed (`npx @frase/cli`)
+- `FRASE_API_KEY` environment variable set (get from https://next.frase.io/settings/api)
+- A Frase site created (check: `list_sites` / `frase sites list`)
+
+## Workflow
+
+### Step 1: Research Before Writing
+
+**Never skip research.** Always start with SERP analysis before creating content.
+
+**Via MCP:**
+```
+1. Use `start_research` with your topic to gather AI-powered insights
+2. Use `analyze_serp` with your target keyword to see what ranks
+3. Use `get_search_intent` to understand query intent (informational, transactional, etc.)
+4. Use `analyze_competitors` to identify content gaps in top-ranking pages
+```
+
+**Via CLI:**
+```bash
+frase research start "your topic"
+frase serp analyze "target keyword"
+frase serp intent "target keyword"
+frase competitive analyze "https://competitor.com/page"
+```
+
+Research tells you what topics to cover, what questions to answer, and what angle will differentiate your content.
+
+### Step 2: Create a Brief (Don't Write from Scratch)
+
+**Always create a brief before generating content.** Briefs contain SERP-driven outlines that ensure comprehensive topic coverage.
+
+**Via MCP:**
+```
+1. Use `create_brief` with:
+   - topic: your target keyword or title
+   - generate_outline: true (this triggers SERP research and auto-outline)
+   - content_type: blog | guide | listicle | comparison | landing | product
+   - site_id: your site ID
+   - target_language / target_country: for regional targeting
+2. Poll `get_job_status` with the brief ID until status is "ready"
+3. Use `get_brief` to retrieve the complete outline with SERP data
+```
+
+**Via CLI:**
+```bash
+frase brief create "target keyword" --generate-outline --type blog --site-id <id>
+frase brief status <brief-id>          # poll until ready
+frase brief get <brief-id>             # view full outline
+```
+
+The brief includes: suggested outline, SERP competitor analysis, People Also Ask questions, and AI Overview data.
+
+### Step 3: Generate Content from the Brief
+
+**Via MCP:**
+```
+1. Use `generate_content` with the brief_id
+2. Poll `get_job_status` until content generation completes
+3. Use `get_content` to retrieve the generated article
+```
+
+**Via CLI:**
+```bash
+frase content create --brief-id <brief-id>
+frase content status <content-id>       # poll until ready
+frase content get <content-id>
+```
+
+Content is generated based on the brief's outline, ensuring it covers all identified topics.
+
+### Step 4: Optimize Iteratively (Target Score > 70)
+
+**Don't publish without optimizing.** Frase scores content against SERP competitors using SEO + GEO scoring.
+
+**Via MCP:**
+```
+1. Use `start_optimization` with the content_id
+2. Wait for analysis, then use `get_optimization` to see suggestions
+3. Apply high-priority suggestions using `apply_optimization`
+4. Re-run optimization to check the new score
+5. Repeat until score >= 70 (or >= 80 for high-value keywords)
+```
+
+**Via CLI:**
+```bash
+frase optimize start --content-id <content-id>
+frase optimize get <optimization-id>
+frase optimize apply <optimization-id> --suggestion <suggestion-id>
+frase optimize start --content-id <content-id>   # re-score
+```
+
+Scoring guidelines:
+- **< 50:** Significant gaps — missing key topics that competitors cover
+- **50-69:** Decent coverage but room for improvement
+- **70-79:** Good — competitive with top-ranking content
+- **80+:** Excellent — likely to outperform most competitors
+
+### Step 5: Publish to CMS
+
+Only publish when the optimization score meets your threshold.
+
+**Via MCP:**
+```
+1. Use `list_cms_connections` with the site_id to check available platforms
+2. Use `publish_content` with content_id, destination, and site_id
+3. Confirm the published URL
+```
+
+**Via CLI:**
+```bash
+frase cms connections --site-id <id>
+frase publish <content-id> --cms frase   # or wordpress, webflow, sanity
+```
+
+### Step 6: Set Up AI Visibility Monitoring (GEO/AEO)
+
+After publishing, track how AI search engines reference your content across 8 platforms.
+
+**Via MCP:**
+```
+1. Use `create_prompt` with prompt_text and target_brand
+2. Monitors citations across ChatGPT, Perplexity, Claude, Google AI Overviews, Copilot, Grok, DeepSeek, Gemini
+3. Check results with `get_prompt` and `get_ai_visibility`
+```
+
+**Via CLI:**
+```bash
+frase aiv prompt create "What is the best tool for content optimization?" --brand "YourBrand" --site-id <id>
+frase aiv overview --site-id <id>
+frase aiv insights --site-id <id>
+```
+
+## Key Principles
+
+1. **Research before writing** — SERP data drives content quality
+2. **Briefs before content** — Outlines ensure comprehensive coverage
+3. **Optimize before publishing** — Score >= 70 is the minimum bar
+4. **Monitor after publishing** — Track both Google rankings and AI citations
+5. **Use site_id consistently** — Associate all content with a site for proper organization
+
+## Common Mistakes to Avoid
+
+- Generating content without a brief (produces generic, un-optimized content)
+- Publishing without checking the optimization score
+- Skipping AI visibility monitoring (you won't know if AI engines cite you)
+- Not specifying target_language/target_country for non-English markets

package/frase-geo-optimization/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: frase-geo-optimization
+description: Optimize content for AI engine citation (GEO/AEO) using Frase — quotability scoring, content structuring, cross-platform citation analysis, and gap diagnosis. Works via MCP or CLI.
+---
+
+# Frase GEO/AEO Optimization
+
+This skill teaches you how to optimize content so AI search engines (ChatGPT, Perplexity, Claude, Google AI Overviews, Copilot, Grok, DeepSeek, Gemini) cite it in their responses. GEO (Generative Engine Optimization) and AEO (Answer Engine Optimization) are the next evolution beyond traditional SEO.
+
+**Works with:** Frase MCP server (`@frase/mcp-server`) OR Frase CLI (`@frase/cli`)
+
+## Prerequisites
+
+- Frase MCP server connected OR `frase` CLI installed (`npx @frase/cli`)
+- `FRASE_API_KEY` environment variable set (get from https://next.frase.io/settings/api)
+- Published content to optimize (check: `list_content` / `frase content list`)
+- AI Visibility monitoring set up (see `frase-ai-visibility` skill)
+
+## Why GEO/AEO Matters
+
+Traditional SEO gets you ranked in Google. GEO/AEO gets you **cited by AI engines**. As users shift to AI-powered search, content that AI engines quote drives increasing traffic and brand awareness.
+
+**Key difference:** SEO optimizes for ranking signals. GEO optimizes for **quotability** — making your content easy for AI models to extract, attribute, and cite.
+
+## Workflow
+
+### Step 1: Baseline Your AI Visibility
+
+Before optimizing, measure where you stand.
+
+**Via MCP:**
+```
+1. Use `get_ai_visibility` with site_id for overall metrics
+2. Use `list_prompts` to see monitored queries
+3. Note which platforms cite you and which don't
+```
+
+**Via CLI:**
+```bash
+frase aiv overview --site-id <id>
+frase aiv prompts --site-id <id>
+```
+
+### Step 2: Identify Citation Gaps
+
+**Via MCP:**
+```
+1. Use `get_insights` for AI-specific recommendations
+2. Use `get_competitors` to see who gets cited instead of you
+3. Categorize gaps:
+   - Content gap: topic not covered at all
+   - Authority gap: content exists but lacks depth/citations
+   - Entity gap: brand not recognized as authoritative
+   - Citation gap: content exists but isn't structured for AI
+```
+
+**Via CLI:**
+```bash
+frase aiv insights --site-id <id>
+frase aiv competitors --site-id <id>
+```
+
+### Step 3: Optimize Content for Quotability
+
+For each piece of content with low GEO scores:
+
+**Via MCP:**
+```
+1. Use `start_optimization` with the content_id
+2. Use `get_optimization` to review suggestions
+3. Focus on GEO-specific improvements:
+   a. Add structured claims with citations (e.g., "According to [source], X increases Y by Z%")
+   b. Include statistics and data points with sources
+   c. Write clear, quotable one-sentence statements
+   d. Add FAQ sections with concise 2-3 sentence answers
+   e. Use clear H2/H3 headings that match common queries
+   f. Add a summary/TL;DR section at the top or bottom
+   g. Include comparison tables for "vs" queries
+4. Apply suggestions using `apply_optimization`
+```
+
+**Via CLI:**
+```bash
+frase optimize start --content-id <id>
+frase optimize get <optimization-id>
+frase optimize apply <opt-id> --suggestion <sug-id>
+```
+
+### Step 4: Structure Content for AI Extraction
+
+AI engines extract information differently than traditional search. Structure your content with these patterns:
+
+**Claim + Evidence pattern:**
+```
+[Clear statement]. According to [source], [supporting data]. This means [implication].
+```
+
+**FAQ pattern:**
+```
+## Frequently Asked Questions
+
+### [Question matching user query]?
+[Concise 2-3 sentence answer with a specific fact or number].
+```
+
+**Comparison pattern:**
+```
+## [Product A] vs [Product B]
+| Feature | Product A | Product B |
+|---------|-----------|-----------|
+| [Feature] | [Value] | [Value] |
+```
+
+**Definition pattern:**
+```
+## What is [Term]?
+[Term] is [concise definition in one sentence]. [Elaboration with specific details].
+```
+
+### Step 5: Republish and Monitor
+
+**Via MCP:**
+```
+1. Use `publish_content` to push optimized content live
+2. Wait 2-4 weeks for AI engines to re-crawl
+3. Use `get_ai_visibility` to check for citation changes
+4. Use `get_alerts` for new/lost citation notifications
+```
+
+**Via CLI:**
+```bash
+frase publish <content-id> --cms frase
+# Wait 2-4 weeks
+frase aiv overview --site-id <id>
+frase aiv alerts --site-id <id>
+```
+
+### Step 6: Iterate Across Content Library
+
+**Via MCP:**
+```
+1. Use `get_optimization_insights` to find patterns across all content
+2. Prioritize pages by traffic potential × citation gap size
+3. Batch optimize: start with highest-impact pages first
+4. Track improvements over time with `get_ai_visibility`
+```
+
+**Via CLI:**
+```bash
+frase optimize insights --site-id <id>
+```
+
+## GEO Score Interpretation
+
+| Score | Meaning | Action |
+|-------|---------|--------|
+| 70+ | Well-structured for AI citation | Maintain and monitor |
+| 50-69 | Some AI-readiness but gaps exist | Apply GEO suggestions |
+| < 50 | Not structured for AI engines | Major restructuring needed |
+
+## Content Elements That Improve GEO
+
+| Element | Impact | Why |
+|---------|--------|-----|
+| Structured claims with sources | High | AI engines prefer citable statements |
+| Statistics and data points | High | Concrete numbers are easy to extract |
+| FAQ sections | High | Direct answer to user queries |
+| Clear H2/H3 headings | Medium | Helps AI identify relevant sections |
+| Comparison tables | Medium | Structured data for "vs" queries |
+| Summary/TL;DR | Medium | Quick extraction point |
+| Lists and bullet points | Medium | Easy to parse and cite |
+| Author credentials | Low-Medium | Signals authority to some AI engines |
+
+## Key Principles
+
+1. **Quotability over keyword density** — write sentences AI engines want to cite
+2. **Structure over length** — well-organized 1500 words beats unstructured 3000 words
+3. **Facts over opinions** — AI engines cite verifiable claims with sources
+4. **Answer the question directly** — don't bury the answer in paragraph 5
+5. **Multi-format content** — tables, lists, FAQs, and prose give AI multiple extraction points
+6. **Monitor and iterate** — GEO optimization is ongoing, not one-time