# SKILL.md — HeyCMO MCP skills

This file describes the MCP (Model Context Protocol) tools HeyCMO exposes for AI agent consumption. It's the skills.sh manifest format — register the repo with `npx skills add` to surface these on https://skills.sh.

- **Server:** `https://heycmo.ai/mcp/sse`
- **Server card (live):** <https://heycmo.ai/.well-known/mcp/server-card.json>
- **Server card (mirror):** <https://heycmo.ai/api/public/agent-card>
- **Auth:** query parameter `?token=hcmo_live_*` (obtain at <https://heycmo.ai/signin>)
- **Transport:** SSE (Server-Sent Events). HTTP fallback: `/mcp/message`.
- **Rate limit:** 30 requests/minute per customer.
- **Source of truth:** `apps/api/agent/agent.config.ts` (`mcpTools` array) and `apps/api/agent/mcp-server.ts` (tool registrations).

## Capability areas

### Workflow + agent orchestration
- `run_research` — Run the daily research pipeline (keywords, competitors, trends, prioritised ideas). Emits real-time progress notifications.
- `research_progress` — Get current progress of a research-pipeline run by `runId`.
- `run_content_creation` — Create content from research-pipeline ideas. Suspends for human approval before publishing.
- `resume_workflow` — Resume a suspended workflow run (typically after human approval).
- `resume_research` — Resume a suspended research pipeline run.
- `run_engagement_check` — Check and respond to comments / DMs across connected social platforms.
- `run_analytics` — Trigger an analytics report for the customer for a given period.
- `run_optimization` — Run the weekly self-optimisation loop.
- `run_launch_plan` — Generate a launch plan for a product or campaign.
- `run_product_content` — Generate content from a product URL or product spec.
- `ask_cmo` — Ask the CMO agent (Sam) a strategic marketing question.

### Content + creative
- `generate_carousel` — Multi-slide carousel image with consistent brand voice and design.
- `generate_reel` — Vertical-video reel script + scene plan for Reels / TikTok / YouTube Shorts.
- `generate_image` — Single AI image from a prompt with brand-aware styling.
- `compose_image` — Compose multiple layers (background, product, text, overlay) into a final image.
- `generate_meme` — Meme using a known template plus brand-relevant copy.
- `list_meme_templates` — List available meme templates.
- `get_brand_context` — Return the customer's saved brand kernel (voice, audience, positioning, palette).
- `get_content_calendar` — Return the customer's scheduled and pending content calendar.
- `schedule_content` — Schedule a piece of content for publication on a target platform / time.
- `list_pending_approvals` — List content pieces awaiting human approval.
- `list_content` — List all content pieces (filterable by status, platform, date).
- `find_recyclable_content` — Find evergreen pieces eligible for republishing.
- `recycle_content` — Republish an evergreen piece, optionally with platform-specific adaptation.
- `list_workflow_runs` — List recent workflow runs (filterable by status, workflow, date).

### Brand + onboarding
- `analyze_brand_url` — Analyse a URL to extract brand voice, audience, positioning, and key facts.
- `onboard_from_url` — Run the full onboarding flow starting from a URL.

### CRO + experimentation
- `cro_audit` — Run a conversion-rate-optimisation audit on a URL; returns ranked experiment ideas.
- `track_experiment` — Record an experiment definition + hypothesis + start state.

### Sales + lead-gen
- `generate_sales_content` — Generate sales-enablement assets (decks, one-pagers, proposals).
- `generate_lead_magnet` — Generate a lead magnet (ebook outline, checklist, ROI calculator) tied to a target ICP.
- `log_lead` — Log a new lead into the customer's CRM with intent + fit scores.
- `search_lead_intel` — Search for intelligence about a lead (company facts, recent news, signals).

### Schema + SEO + AI search
- `generate_schema_markup` — Generate JSON-LD schema markup for a page (Organization, Product, FAQ, etc.).
- `ai_seo_audit` — Run an AI-search-readiness audit on a URL; returns prioritised checklist.
- `generate_llms_txt` — Generate a high-quality llms.txt file for a URL based on its content.
- `check_ai_visibility` — Check whether a brand or page appears in ChatGPT / Perplexity / Gemini / AI Overviews.

### Social + analytics
- `publish_to_social` — Publish or schedule a post to a connected social platform.
- `social_connections` — List the customer's connected social platforms and their auth status.
- `social_post_analytics` — Fetch analytics for a published social post (impressions, engagement, clicks).

### Competitive + research
- `research_competitor` — Run a deep-research pass on a named competitor.
- `analyze_competitor` — Analyse a competitor URL (positioning, content cadence, keywords, social).
- `track_competitor_changes` — Track a competitor URL for changes over time; alerts on diff.

### Podcast + product
- `process_podcast` — Process a podcast episode — transcript, key quotes, derived posts.
- `scrape_product_url` — Extract product details (name, description, price, features) from a URL.

### Analytics + revenue
- `query_ga4` — Query Google Analytics 4 for a metric over a date range.
- `track_revenue` — Record or query revenue events tied to attribution.

### Localisation
- `translate_content` — Translate content into a target language with brand-aware tone preservation.
- `detect_language` — Detect the language of a text snippet.

### Budget controls
- `check_budget` — Check whether a planned spend fits within the customer's configured budget caps.
- `get_budget_status` — Get current spend vs cap for daily / weekly / monthly windows.
- `record_spend` — Record an actual spend amount against a category.

### Autonomy controls
- `get_autonomy_levels` — Get the per-skill autonomy level configuration (L1–L5).
- `set_autonomy_level` — Set the autonomy level for a skill, category, or globally.

### Skills (read-only)
- `list_installed_skills` — List the dynamic skills currently installed for the customer.
- `get_skill_info` — Get details on a specific installed skill.
- `execute_skill` — Execute an installed skill by id with input.

### Performance / learning
- `capture_performance_snapshot` — Capture a snapshot for the daily / weekly self-improvement loop.
- `get_performance_trend` — Fetch the performance trend over a window.
- `get_learning_insights` — Fetch the system's learned insights from past performance.

### Advanced creative
- `hashtag_analytics` — Hashtag performance analytics for a topic / platform.
- `list_industry_packs` — Industry-specific creative + content packs.
- `get_industry_templates` — Templates for a specific industry pack.
- `plan_video_scenes` — Plan a video scene-by-scene (script + visual notes + duration).
- `generate_video` — Generate a video from a scene plan.
- `generate_video_ad` — Generate a video ad creative.
- `generate_product_video` — Generate a product video (B-roll + voice-over + captions).
- `generate_avatar_video` — Generate an avatar-fronted video (script-to-talking-head).
- `add_background_music` — Add background music to a video.
- `list_music_tracks` — Available background music tracks.
- `generate_product_photoshoot` — AI product photoshoot images (multiple angles, scenes, styles).

## Usage example

```bash
# 1. Get an API key
open https://heycmo.ai/signin

# 2. Connect from Claude Desktop / Cursor / any MCP client
#    Add to your MCP config:
{
  "mcpServers": {
    "heycmo": {
      "url": "https://heycmo.ai/mcp/sse?token=hcmo_live_YOUR_KEY"
    }
  }
}
```

## See also

- `AGENTS.md` — coding-agent guidance for working in this repo
- `llms.txt` — agent-facing product description
- `openapi.json` — REST API specification (OpenAPI 3.1)
- <https://docs.heycmo.ai/docs/api> — full API documentation