@frase/agent-skills 0.3.0

package/README.md

@@ -0,0 +1,51 @@
+# @frase/agent-skills
+
+Agent skills for the [Frase](https://frase.io) SEO & GEO platform. These skills teach AI assistants (Claude Code, Cursor, Windsurf, Copilot, and 18+ other tools) how to use Frase effectively for content workflows.
+
+## What are Agent Skills?
+
+Agent Skills are markdown files that load into an AI assistant's context, teaching it domain-specific knowledge about how to use your tools correctly. Unlike MCP tools (which provide the _ability_ to call APIs), skills provide the _knowledge_ of how to use them together effectively.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `frase-content-pipeline` | End-to-end content workflow: research, brief, write, optimize, publish, monitor |
+| `frase-seo-audit` | Run and interpret SEO audits, prioritize fixes by traffic impact |
+| `frase-ai-visibility` | Track and improve brand visibility across AI search engines |
+| `frase-content-optimization` | Score, optimize, and improve content for SEO and GEO performance |
+
+## Installation
+
+### Via skills.sh (recommended)
+
+```bash
+npx skills add frase/frase-skills
+```
+
+This installs all Frase skills into your AI assistant's context.
+
+### Manual
+
+Copy any `.md` file from this package into your project's `.claude/` directory (for Claude Code) or equivalent context directory for your AI tool.
+
+## Prerequisites
+
+These skills work best with the [Frase MCP Server](https://www.npmjs.com/package/@frase/mcp-server) connected:
+
+```bash
+# Claude Code
+claude mcp add frase -- npx -y @frase/mcp-server --api-key sk_live_your_key
+
+# Cursor — add to .cursor/mcp.json
+# Windsurf — add to ~/.codeium/windsurf/mcp_config.json
+# VS Code Copilot — add to .vscode/settings.json
+```
+
+Get your API key at [next.frase.io/settings/api-keys](https://next.frase.io/settings/api-keys).
+
+## Related
+
+- [@frase/mcp-server](https://www.npmjs.com/package/@frase/mcp-server) — MCP server with 63 tools
+- [Frase API Docs](https://next.frase.io/api/docs) — Interactive API reference
+- [OpenAPI Spec](https://next.frase.io/openapi.json) — Machine-readable API schema

package/frase-ai-visibility/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: frase-ai-visibility
+description: Track and improve brand visibility across 8 AI search engines (ChatGPT, Perplexity, Claude, Google AI Overviews, Copilot, Grok, DeepSeek, Gemini) using Frase. Works via MCP or CLI.
+---
+
+# Frase AI Visibility (GEO/AEO)
+
+This skill teaches you how to track and improve brand visibility across AI search engines using Frase — covering GEO (Generative Engine Optimization) and AEO (Answer Engine Optimization).
+
+**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 published content
+- Professional plan or higher (for multi-platform tracking)
+
+## What is AI Visibility?
+
+AI search engines increasingly answer user queries directly instead of showing links. **AI Visibility** tracks whether these platforms cite YOUR content in their responses.
+
+Frase monitors citations across **8 platforms:**
+- ChatGPT
+- Perplexity
+- Claude
+- Google AI Overviews
+- Microsoft Copilot
+- Grok
+- DeepSeek
+- Gemini
+
+## Workflow
+
+### Step 1: Check Current Visibility
+
+**Via MCP:**
+```
+1. Use `get_ai_visibility` with site_id to see overall metrics:
+   - Citation count across platforms
+   - Share of voice vs competitors
+   - Trend direction (improving, declining, stable)
+```
+
+**Via CLI:**
+```bash
+frase aiv overview --site-id <id>
+```
+
+### Step 2: Set Up Monitoring
+
+Track specific keywords and queries that matter to your business.
+
+**Via MCP:**
+```
+1. Use `list_prompts` to check existing monitored queries
+2. Use `create_prompt` with:
+   - prompt_text: a natural question users might ask AI engines (required, min 10 chars)
+     Example: "What is the best SEO tool for content optimization?"
+   - target_brand: your brand name to track visibility for (required)
+     Example: "Frase"
+   - frequency: "daily" (default), "weekly", or "manual"
+   - platforms: optionally specify which AI platforms to track
+3. Frase monitors this query across selected AI platforms
+4. It tracks whether your brand/content is cited in responses
+```
+
+**Via CLI:**
+```bash
+frase aiv prompt create "What is the best SEO tool for content optimization?" --brand "Frase" --site-id <id>
+frase aiv prompts --site-id <id>        # list all monitored prompts
+```
+
+Monitor at least:
+- Your primary product/service keywords
+- Comparison queries ("X vs Y")
+- "Best of" and recommendation queries
+- Questions your target audience asks
+
+### Step 3: Analyze Results
+
+**Via MCP:**
+```
+1. Use `get_prompt` with a prompt ID to see:
+   - Which AI platforms cite you (and which don't)
+   - What competitors are cited instead
+   - The exact text AI engines use when citing you
+2. Use `get_insights` for actionable recommendations
+3. Use `get_competitors` to see competitor visibility
+```
+
+**Via CLI:**
+```bash
+frase aiv insights --site-id <id>
+frase aiv competitors --site-id <id>
+```
+
+### Step 4: Set Up Alerts
+
+**Via MCP:**
+```
+1. Use `get_alerts` to see alerts for:
+   - New citations (you started appearing in AI responses)
+   - Lost citations (you were dropped from AI responses)
+   - Competitor changes (competitors gained or lost visibility)
+```
+
+**Via CLI:**
+```bash
+frase aiv alerts --site-id <id>
+```
+
+### Step 5: Improve Visibility (GEO Optimization)
+
+When AI engines don't cite your content, optimize for GEO:
+
+**Via MCP:**
+```
+1. Use `start_optimization` on the relevant content
+2. Focus on GEO-specific suggestions:
+   - Add structured claims with citations
+   - Include statistics and data points
+   - Use clear, quotable statements
+   - Add FAQ sections with concise answers
+   - Structure content with clear headings and summaries
+3. Republish optimized content using `publish_content`
+4. Monitor changes in AI citations over the following weeks
+```
+
+**Via CLI:**
+```bash
+frase optimize start --content-id <id>
+frase optimize get <optimization-id>     # review GEO suggestions
+frase optimize apply <opt-id> --suggestion <sug-id>
+frase publish <content-id> --cms frase   # republish after optimization
+```
+
+### Step 6: Compare Against Competitors
+
+**Via MCP:**
+```
+1. Use `get_competitors` to see who appears in AI responses for your keywords
+2. Analyze what competitors do differently:
+   - Content structure and formatting
+   - Citation density and source quality
+   - Freshness and update frequency
+3. Apply insights to your own content strategy
+```
+
+**Via CLI:**
+```bash
+frase aiv competitors --site-id <id>
+frase competitive analyze "https://competitor.com/page"
+```
+
+## Key Principles
+
+1. **Monitor continuously** — AI search results change frequently
+2. **Track competitors** — understand who gets cited and why
+3. **Optimize for citations** — structure content so AI engines can quote it
+4. **Multi-platform tracking** — each AI engine has different citation preferences
+5. **Patience required** — AI search changes take weeks to appear as AI engines re-crawl
+6. **GEO + SEO together** — high SEO scores improve discoverability, high GEO scores improve citability
+
+## AI Platform Differences
+
+| Platform | Citation Style | What It Favors |
+|----------|---------------|----------------|
+| ChatGPT | Inline citations with links | Authoritative, well-structured content |
+| Perplexity | Explicit source attribution | Fresh content, multiple corroborating sources |
+| Claude | Context-based references | Detailed, nuanced content with clear claims |
+| Google AI Overviews | Extracted snippets | Concise answers, structured data |
+| Copilot | Link cards | Microsoft ecosystem content, recent sources |
+| Grok | Inline references | Real-time data, trending topics |
+| DeepSeek | Source attribution | Technical depth, data-heavy content |
+| Gemini | Knowledge panel style | Structured data, entity-rich content |
+
+## Gap Types to Diagnose
+
+When your content isn't getting cited, identify the gap type:
+
+- **Content gap** — topic not covered at all → create new content
+- **Authority gap** — content exists but lacks depth/citations → add data, sources, expert quotes
+- **Entity gap** — brand not recognized as authoritative → build topical authority with clusters
+- **Citation gap** — content exists but isn't structured for AI → restructure with claims, FAQs, summaries

package/frase-atomization/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: frase-atomization
+description: Break long-form content into atomic pieces (social posts, email snippets, ad copy, threads) using Frase — batch atomize, export, and repurpose across channels. Works via MCP or CLI.
+---
+
+# Frase Content Atomization
+
+This skill teaches you how to break long-form content into reusable atomic pieces using Frase — social posts, email snippets, ad copy, Twitter/X threads, LinkedIn posts, and more.
+
+**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 or draft content to atomize (use `list_content` / `frase content list`)
+
+## What is Content Atomization?
+
+Atomization breaks a single piece of long-form content (article, guide, report) into 10-30+ smaller pieces optimized for different channels. One 2000-word article becomes social posts, email snippets, ad copy, and more — without writing from scratch.
+
+## Workflow
+
+### Step 1: Select Content to Atomize
+
+**Via MCP:**
+```
+1. Use `list_content` to find published content
+2. Choose high-performing or evergreen pieces — they produce the best atoms
+3. Note the content_id
+```
+
+**Via CLI:**
+```bash
+frase content list --site-id <id>
+```
+
+### Step 2: Run Atomization
+
+**Via MCP:**
+```
+1. Use `create_atomization` with:
+   - content_id: the content to break apart (required)
+   - formats: array of desired output types (optional)
+     Options: social, email, ad, thread, summary
+   - tone: adjust tone for atoms (optional)
+     Options: professional, casual, technical
+2. Poll `get_job_status` until atomization completes
+```
+
+**Via CLI:**
+```bash
+frase atomize start <content-id> --type <type>
+# Types: linkedin_carousel, twitter_thread, newsletter, instagram_carousel
+frase job status <job-id>               # poll until ready
+```
+
+### Step 3: Review Atoms
+
+**Via MCP:**
+```
+1. Use `get_atomization` with the atomization ID
+2. Review generated atoms:
+   - Each atom has a unique ID, format type, and content
+   - Atoms are grouped by format (social, email, ad, etc.)
+   - Each includes suggested platform and character count
+```
+
+**Via CLI:**
+```bash
+frase atomize get <atomization-id>
+frase atomize get <atomization-id> --json   # full details
+```
+
+### Step 4: Export Atoms
+
+**Via MCP:**
+```
+1. Use `export_atomization` with:
+   - id: the atomization ID
+   - format: export format (csv, json, markdown)
+2. Use exported atoms in your social media scheduler, email tool, or ad platform
+```
+
+**Via CLI:**
+```bash
+frase atomize export <atomization-id> --format csv
+frase atomize export <atomization-id> --format markdown
+```
+
+### Step 5: Batch Atomize Multiple Articles
+
+For content libraries, atomize in bulk:
+
+**Via MCP:**
+```
+1. Use `batch_atomize` with:
+   - content_ids: array of content IDs to atomize
+   - formats: desired output types (applied to all)
+2. Poll `get_job_status` for the batch job
+3. Retrieve individual results with `get_atomization`
+```
+
+**Via CLI:**
+```bash
+frase atomize batch --content-ids <id1>,<id2>,<id3>
+frase job status <batch-job-id>
+```
+
+## Atom Types
+
+### MCP Formats
+
+| Format | Best For | Typical Length |
+|--------|----------|---------------|
+| social | Twitter/X, Facebook, LinkedIn | 140-600 chars |
+| email | Newsletter sections | 100-200 words |
+| ad | Google/Meta ad copy | 30-150 chars |
+| thread | Twitter/X threads | 5-10 tweets |
+| summary | Executive summaries | 2-3 sentences |
+
+### CLI Types
+
+| Type | Best For | Output |
+|------|----------|--------|
+| linkedin_carousel | LinkedIn carousel posts | Multi-slide content |
+| twitter_thread | Twitter/X threads | Tweet-sized segments |
+| newsletter | Email newsletters | Newsletter-ready sections |
+| instagram_carousel | Instagram carousel posts | Visual-first content |
+
+## Key Principles
+
+1. **Atomize high-performers first** — articles with proven engagement produce better atoms
+2. **Match tone to platform** — professional for LinkedIn, casual for Twitter, concise for ads
+3. **Batch for efficiency** — atomize 10+ articles at once to build a content bank
+4. **Export and schedule** — use CSV exports with your social media scheduler
+5. **Don't post all atoms at once** — spread across days/weeks for sustained engagement
+6. **Track which atoms perform** — identify formats and topics that resonate per platform

package/frase-cms-publishing/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: frase-cms-publishing
+description: Multi-platform publishing using Frase — FraseCMS, WordPress, Webflow, Sanity, scheduling, auto-optimization, and content versioning. Works via MCP or CLI.
+---
+
+# Frase CMS Publishing
+
+This skill teaches you how to publish content across multiple CMS platforms using Frase, including scheduling, auto-optimization (watchdog), and content versioning.
+
+**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 at least one CMS connection (check: `list_cms_connections` / `frase cms connections`)
+
+## Supported CMS Platforms
+
+| Platform | Connection Type | Features |
+|----------|----------------|----------|
+| FraseCMS | Built-in | Subdomain, custom domain, reverse proxy hosting |
+| WordPress | REST API | Posts, pages, Yoast/RankMath SEO meta support |
+| Webflow | API | Collections, asset management |
+| Sanity | API | Document types, custom schemas |
+
+## Workflow
+
+### Step 1: Check CMS Connections
+
+**Via MCP:**
+```
+1. Use `list_cms_connections` with site_id
+2. Review connected platforms and their status
+3. If no connections exist, set up via Frase dashboard or CLI
+```
+
+**Via CLI:**
+```bash
+frase cms connections --site-id <id>
+```
+
+### Step 2: Set Up a CMS Connection (if needed)
+
+**Via CLI:**
+```bash
+frase cms setup --site-id <id> --provider wordpress --config '{"url":"https://yoursite.com","api_key":"wp_key"}'
+frase cms setup --site-id <id> --provider frase
+frase cms setup --site-id <id> --provider webflow --config '{"api_token":"wf_token","site_id":"wf_site"}'
+frase cms setup --site-id <id> --provider sanity --config '{"project_id":"proj","dataset":"production","token":"sk_token"}'
+```
+
+### Step 3: Publish Content
+
+Only publish content that meets your optimization threshold (score >= 70 recommended).
+
+**Via MCP:**
+```
+1. Use `publish_content` with:
+   - content_id: the content to publish (required)
+   - destination: target CMS (frase_cms, wordpress, webflow, sanity)
+   - site_id: your site ID
+   - scheduled_at: ISO date for future publishing (optional)
+2. Confirm the published URL in the response
+```
+
+**Via CLI:**
+```bash
+frase publish <content-id> --cms frase --site-id <id>
+frase publish <content-id> --cms wordpress --site-id <id>
+frase publish <content-id> --cms webflow --site-id <id>
+# Scheduled publishing:
+frase publish <content-id> --cms frase --site-id <id> --schedule "2026-04-01T09:00:00Z"
+```
+
+### Step 4: Browse Published Content
+
+**Via CLI:**
+```bash
+frase cms posts --connection-id <connection-id>
+frase cms posts --connection-id <connection-id> --limit 50
+```
+
+### Step 5: Enable Auto-Optimization (Watchdog)
+
+Frase's watchdog monitors published content for decay signals and auto-applies safe optimization suggestions.
+
+**Decay signals monitored:**
+- Content age (staleness)
+- Traffic trend (declining visits)
+- Ranking trend (dropping positions)
+- Competitor activity (new competing content)
+
+**Safe auto-apply actions:**
+- Schema markup additions
+- Keyword optimization in headings/meta
+- Content enhancement suggestions
+- Internal link additions
+
+**Via MCP:**
+```
+1. Use `get_auto_optimization_status` with site_id to check current status
+2. Use `toggle_auto_optimization` with:
+   - site_id: your site ID
+   - enabled: true to enable, false to disable
+3. Watchdog runs automatically and creates optimization tasks
+4. Content is auto-snapshotted before any changes (enables undo)
+```
+
+**Via CLI:**
+```bash
+frase health overview --site-id <id>     # includes auto-optimization status
+```
+
+### Step 6: FraseCMS Configuration
+
+For FraseCMS-hosted sites, configure hosting mode:
+
+| Mode | How It Works | Best For |
+|------|-------------|----------|
+| Subdomain | `yourblog.frase.site` | Quick setup, testing |
+| Custom domain | `blog.yoursite.com` | Professional sites |
+| Reverse proxy | Content served at `yoursite.com/blog/*` | SEO (keeps domain authority) |
+
+## Publishing Checklist
+
+Before publishing any content, verify:
+
+1. **Optimization score >= 70** (or your target threshold)
+   ```bash
+   frase optimize start --content-id <id>
+   frase optimize get <optimization-id>
+   ```
+
+2. **Rules pass** (if using content rules)
+   ```bash
+   frase rules evaluate --content-id <id> --rule-set-id <rule-set-id>
+   ```
+
+3. **Meta tags set** (title, description)
+
+4. **Internal links included** (link to related content)
+
+5. **CMS connection active**
+   ```bash
+   frase cms connections --site-id <id>
+   ```
+
+## Key Principles
+
+1. **Optimize before publishing** — never publish content below your score threshold
+2. **Use scheduling** — queue content for optimal publish times (cron publishes every 5 minutes)
+3. **Enable auto-optimization** — let watchdog catch content decay early
+4. **Version snapshots** — Frase auto-snapshots before changes, enabling undo
+5. **One source of truth** — manage all publishing through Frase for consistent tracking
+6. **Monitor after publishing** — set up AI visibility tracking for published content