moicle 2.0.0 → 2.1.0

package/assets/skills/marketing/seo-blog/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: marketing-seo-blog
+description: Write an evergreen blog post optimized for both Google Search AND AI tools (ChatGPT, Bing/Copilot, Perplexity). Answer-first, intent-classified, overlap-audited. Use when user says "write seo blog", "seo blog", "evergreen post", "compare post", "trust post", "glossary post", "blog for AI to recommend", "search + ai".
+---
+
+# SEO + AI Blog Writer
+
+Write **one** evergreen blog post that ranks on traditional search AND is easy for AI systems to cite or recommend. Intent-first, answer-first, overlap-audited.
+
+## When to use this skill
+
+- ✅ Writing a single evergreen blog post (entity / trust / compare / glossary / use-case / FAQ)
+- ✅ Updating an existing evergreen post that has drifted
+- ✅ Replacing a thin / outdated post with a stronger version on the same intent
+- ❌ Multi-post content plan / calendar / strategy → use `/marketing:content`
+- ❌ Changelog / feature launch / release announcement → write manually or use a feature-blog template
+- ❌ Time-sensitive news / event post → not evergreen, different rules
+
+---
+
+## Core principle
+
+**Don't write a blog "to fill the calendar." Write the answer to a question users actually ask** on Search or to an AI.
+
+- Every post must let an AI model answer at least one clear intent
+- One strong intent = **one canonical post**. Don't write a second post on the same intent — update the first
+- If existing post is stale → fix it; don't pile a new post on top
+
+---
+
+## Workflow
+
+```
+1 INTENT → 1.5 OVERLAP AUDIT → 2 RESEARCH → 3 FILE → 4 FRONTMATTER → 5 BODY → 6 PATTERN → 7 RULES → 8 LINKS → 9 VERIFY → 10 REPORT
+```
+
+---
+
+## Step 1: Classify intent
+
+Pick **one** category. Don't write a hybrid — split into two posts if needed.
+
+| # | Intent | Example queries |
+|---|--------|-----------------|
+| 1 | **Entity** | "What is {Brand}", "How does {Brand} work" |
+| 2 | **Trust** | "Is {Brand} legit", "Why is {Brand} {claim}" |
+| 3 | **Compare** | "{Brand} vs {Competitor}", "Best {category} apps in {region}" |
+| 4 | **Glossary** | "What is {term}", "{term} explained" |
+| 5 | **Use case** | "How to {action} with {Brand}", "How to {achieve outcome}" |
+| 6 | **Problem / FAQ** | "Why is my {thing} not working", "Why did {unexpected outcome} happen" |
+
+---
+
+## Step 1.5: Overlap audit (mandatory)
+
+**Before writing anything new**, inventory existing posts in the blog folder.
+
+```bash
+# Adapt path to project — common: content/blog/, app/blog/, docs/blog/
+find {blog_dir} -name "*.md" -maxdepth 2 | sort
+```
+
+For each existing post, extract from frontmatter or first 30 lines:
+- slug
+- primary intent (which of the 6 above)
+- funnel stage (awareness / consideration / decision)
+- evergreen or seasonal
+- any claims that are now stale or off-brand
+
+Then compare your planned post against the inventory.
+
+### Decision rules
+
+| Situation | Action |
+|-----------|--------|
+| New post overlaps >60% intent with existing post | **Do not create new.** Either update the existing one OR refocus both to clearly distinct intents |
+| Existing post has stale claims (deprecated platform, old positioning, unsafe wording) | Update the existing post **first or in the same batch** — never pretend the issue isn't there |
+| New intent is genuinely uncovered | Proceed to Step 2 |
+
+### Examples
+✅ Correct: `what-is-brand.md` (entity) + `how-to-use-brand.md` (how-to) — different intents.
+❌ Wrong: two posts both answering "What is {Brand}" — pick one as canonical, update it.
+
+### Gate
+- [ ] Inventory of existing posts read
+- [ ] No >60% overlap, OR plan to update existing instead of writing new
+- [ ] Stale-claim audit done (or N/A noted)
+
+---
+
+## Step 2: Research (short but solid)
+
+If the post mentions current facts, third parties, or specific numbers — **verify before writing**.
+
+### Verify
+- Competitor / partner / third-party facts
+- Stats, dates, policies (these go stale fast)
+- App Store / Google Play / platform-specific claims
+- Pricing, fees, rates
+
+### Source priority
+1. Official source from the project (in-repo docs, official site)
+2. Official source from the third party (their docs / site)
+3. Project marketing strategy docs (if any)
+4. Reputable third-party sources, recent (≤1 year for pricing/stats)
+
+### Hard rules
+- **No invented benchmarks.** If you don't have a source, don't claim the number
+- **No invented comparisons.** Compare only what's verifiable
+- For evergreen posts, prefer durable claims over snapshot stats
+
+### Gate
+- [ ] Every non-trivial factual claim has a source
+- [ ] Sources noted (in draft comments) so reviewer can verify
+
+---
+
+## Step 3: File output
+
+```text
+{blog_dir}/{slug}.md
+```
+
+### Slug rules
+- Lowercase
+- Hyphen-separated (no underscores, no spaces)
+- For non-English projects: language convention (e.g., Vietnamese without diacritics, kebab-case)
+- Slug must map to **intent**, not to a marketing campaign
+
+### Examples
+- `what-is-{brand}.md` (entity)
+- `is-{brand}-legit.md` (trust)
+- `{brand}-vs-{competitor}.md` (compare)
+- `why-is-my-order-not-tracked.md` (problem)
+
+---
+
+## Step 4: Frontmatter
+
+```yaml
+---
+title: "Title that matches the real query"
+description: "140-160 chars. Tell the reader what this post does for them — not marketing fluff."
+date: "YYYY-MM-DD"
+author: "{Brand} Team"
+image: "/images/blog/{slug}.svg"
+category: "<from project's category enum>"
+tags: ["<brand>", "<topic>", "<intent>"]
+---
+```
+
+### Picking `category`
+Use the project's existing category enum — never invent new ones. Common:
+- `guide` / `tutorial` for entity, glossary, use-case, FAQ
+- `tips` for optimization / case-based
+- `compare` / `review` for comparison posts
+- `changelog` only for product update posts (which this skill does NOT handle)
+
+---
+
+## Step 5: Body structure (answer-first)
+
+```markdown
+{2-4 sentences directly answering the question in the title — no warm-up, no story}
+
+## TL;DR
+
+- Key takeaway 1
+- Key takeaway 2
+- Key takeaway 3
+
+## {Primary heading 1 — the main answer expanded}
+
+...
+
+## {Primary heading 2 — supporting context}
+
+...
+
+## When to choose / use / consider {Brand}
+
+...
+
+## Important caveats
+
+...
+
+## FAQ
+
+### {Question 1 — phrased exactly as users ask}
+{Direct answer, 2-4 sentences}
+
+### {Question 2}
+{...}
+
+## Conclusion / Next step
+
+...
+```
+
+**Why this structure works for AI systems:** TL;DR + direct answer + FAQ blocks are the highest-cited patterns. AI tools quote concise answers; long-winded intros get skipped.
+
+---
+
+## Step 6: Pattern per intent type
+
+### A. Entity / Trust
+Must answer:
+- What is {Brand}
+- Who is it for
+- Where does the {core value} come from (be specific — sources, business model, partnerships)
+- Who is the company / team behind it
+- Does it have support / app stores / community / public presence
+
+### B. Compare
+Must include a real comparison table:
+
+```markdown
+| Criterion | {Brand} | {Competitor A} | {Competitor B} |
+|-----------|---------|---------------|---------------|
+| Coverage | ... | ... | ... |
+| Pricing / fees | ... | ... | ... |
+| Strengths | ... | ... | ... |
+| Best for | ... | ... | ... |
+```
+
+Rules:
+- **Fair** — no dunking without evidence
+- State **when each option fits better** — not "we're best at everything"
+- Verify every cell (Step 2)
+
+### C. Glossary
+Must:
+- Define the term in 1-2 sentences at the top
+- Give a concrete example (not abstract)
+- Use end-user language, not insider jargon
+- Link out to a related use-case / guide post
+
+### D. Use case / How-to
+Must:
+- Numbered steps (≤7 main steps)
+- Screenshots or visuals where relevant
+- Prerequisites listed before the steps
+- Expected outcome stated
+
+### E. Problem / FAQ
+Must:
+- Describe the symptom (so users searching the symptom land here)
+- List common causes ordered by likelihood
+- Provide a fix per cause
+- State when to escalate to human support
+
+---
+
+## Step 7: SEO + AI optimization rules
+
+- **H1 = the real query**, not a marketing headline
+- **First paragraph answers directly** — no warm-up, no anecdote, no "in this article we will…"
+- **Headings tell the story** — a reader who only scans H2s should understand the whole post
+- **Tables and lists** beat paragraphs for scannable content
+- **Internal links** to related posts and key product pages (next step)
+- **One consistent positioning sentence** for the brand across all posts
+- **No keyword stuffing** — write for humans first
+- **No filler** — every paragraph earns its place
+- **Sensitive claims need evidence** or safe wording (e.g., "may", "in some cases")
+
+---
+
+## Step 8: Internal link rules
+
+Minimum **2-4 internal links** per post:
+
+- 1 link to a core product / about page (`/about`, `/product`, `/guide`)
+- 1 link to a support / help page (`/help`, `/faq`)
+- 1-2 links to related foundational blog posts
+
+Anchor text:
+- Natural, descriptive
+- Vary phrasing — don't repeat exact-match anchors
+
+---
+
+## Step 9: Verify (pre-publish checklist)
+
+- [ ] Primary intent clearly distinct from existing posts (Step 1.5)
+- [ ] Title matches the real query users would search
+- [ ] First paragraph answers directly (no warm-up)
+- [ ] Has table / FAQ / numbered steps where the intent calls for them
+- [ ] ≥2 internal links, with natural anchor text
+- [ ] No unverified claims left in (no "studies show" without a study)
+- [ ] Frontmatter `category` matches the project's existing enum
+- [ ] Sitemap updated (if project requires)
+- [ ] Image / OG image referenced and exists
+- [ ] Reading level reasonable for the audience (run through Hemingway / similar)
+
+Quick checks:
+```bash
+ls {blog_dir}/{slug}.md
+head -30 {blog_dir}/{slug}.md
+{linter for markdown / mdx if project has one}
+```
+
+---
+
+## Step 10: Report
+
+```markdown
+## SEO Blog Post: {title}
+
+### File
+- `{blog_dir}/{slug}.md`
+
+### Intent
+- Category: {entity / trust / compare / glossary / use-case / problem}
+- Primary query: "{the search query this targets}"
+
+### Frontmatter
+- title: ...
+- category: ...
+- tags: [...]
+
+### Key internal links
+- {anchor → /path}
+- {anchor → /path}
+
+### Overlap audit
+- Checked: {N existing posts}
+- Decision: {NEW / UPDATED `existing-slug` / REFOCUSED}
+
+### Items needing user review
+- {claim X — verify source}
+- {comparison cell Y — confirm with product team}
+```
+
+---
+
+## Hard Rules
+
+- **One canonical post per intent** — never write a duplicate, always update the existing one
+- **Overlap audit before writing** — Step 1.5 is not optional
+- **Answer-first structure** — TL;DR + direct answer in the first paragraph
+- **No invented facts / benchmarks / comparisons** — verify or omit
+- **Stale-claim audit** — if you find an outdated existing post, fix it in the same batch
+- **Slug = intent**, not campaign or date
+- **Update sitemap** when adding new posts (if project requires it)
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Multi-post content plan / calendar / strategy | `/marketing:content` |
+| Brand voice / visual identity setup first | `/marketing:logo` |
+| Video / shorts version of the post | `/marketing:video` |
+| Full go-to-market plan (logo + content + video) | `/marketing` command |
+| Writing technical project docs (not blog) | `/docs:write` |
+
+## Recommended Agents
+
+| Step | Agent | Purpose |
+|------|-------|---------|
+| 1.5 OVERLAP | `@docs-writer` | Inventory + cluster analysis |
+| 2 RESEARCH | `@docs-writer` | Source verification |
+| 5 BODY | `@docs-writer` | Drafting + structure |
+| 7 SEO + AI | `@docs-writer` | Optimization pass |
+| 9 VERIFY | `@code-reviewer` | Link + frontmatter sanity check |

package/assets/skills/marketing/video/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: marketing-video
+description: Plan and produce video content strategy including scripts, storyboards, and production specs. Use when user says "create video", "video content", "video script", "video strategy", "youtube content", "video plan".
+---
+
+# Video Content Skill
+
+Plan video content end-to-end: strategy, script, storyboard, production spec, publishing schedule.
+
+## When to use this skill
+
+- ✅ Planning a video series or campaign (multi-video)
+- ✅ Need a script + storyboard + production spec for a single video
+- ✅ Repurposing existing long-form into shorts / clips
+- ❌ Just need ideas, not a plan → use `brainstorm`
+- ❌ Want full marketing plan (logo + content + video) → use `/marketing`
+- ❌ Writing a blog post or thread → use `/marketing:content`
+
+---
+
+## Workflow
+
+```
+STRATEGY → SCRIPT → STORYBOARD → PRODUCTION → PUBLISH
+```
+
+---
+
+## Phase 1: STRATEGY
+
+**Goal:** lock the audience, goal, channels, and series plan.
+
+### Gather brief
+
+Ask the user (skip what's already known):
+
+| Field | Example |
+|-------|---------|
+| Primary goal (pick 1) | brand awareness / tutorial / lead gen / community / thought leadership |
+| Audience | "Senior backend engineers evaluating Postgres tooling" |
+| Channels (pick ≤3) | YouTube long / YouTube Shorts / TikTok / Reels / LinkedIn / X / Twitch |
+| Cadence | "1 long video / week + 3 shorts" |
+| Series concept | "From-zero series: build a SaaS in 10 episodes" |
+| Tone | "Casual, technical, no fluff" |
+| Existing assets | brand kit URL, prior videos, channel stats |
+
+### Output: 1-page strategy
+
+```markdown
+## Video Strategy: {brand}
+- Goal: {one line}
+- Audience: {one line}
+- Channels: {list, with primary marked}
+- Cadence: {long-form + shorts schedule}
+- Series: {2-4 series, each with theme + episode count target}
+- Brand: {voice, colors, logo lockup}
+```
+
+### Gate
+- [ ] Goal + audience confirmed by user
+- [ ] Channels matched to where audience watches
+- [ ] At least 1 series concept defined
+
+---
+
+## Phase 2: SCRIPT
+
+**Goal:** write a script that holds attention from frame 1.
+
+### Universal structure
+
+```
+HOOK (≤10 sec, ≤30 sec for long-form)
+  - one of: contrarian claim / surprising number / pain question / curiosity gap
+INTRO (≤15 sec)
+  - what they'll get + why this person/channel
+BODY
+  - one idea per segment, each ≤90 sec for long-form, ≤15 sec for shorts
+  - pattern interrupt every 30-45 sec (cut, b-roll, on-screen text)
+PAYOFF
+  - the answer / the demo / the result
+CTA (≤10 sec)
+  - one ask: subscribe, link, comment with X
+```
+
+### Hook examples (pick a type, write 3 variants)
+
+| Type | Example |
+|------|---------|
+| Contrarian | "Everyone tells you to write tests first. Here's why I stopped." |
+| Number | "I shipped 47 features last quarter with 1 engineer. Here's how." |
+| Pain question | "Your DB is slow at 100k rows? That's a config issue, not a Postgres limit." |
+| Curiosity gap | "There's a feature in Go that nobody uses but it solves your timeout bug." |
+
+### Script length budget
+
+| Format | Total | Hook | Body | CTA |
+|--------|-------|------|------|-----|
+| YouTube long | 8-15 min | 10-30 s | 7-13 min | 10-30 s |
+| YouTube Short / Reel / TikTok | 30-60 s | ≤3 s | 25-50 s | ≤5 s |
+| LinkedIn native | 1-3 min | ≤5 s | 50 s - 2 min 30 s | ≤10 s |
+
+### Gate
+- [ ] Hook tested by reading frame 1 aloud — would you keep watching?
+- [ ] One idea per segment (no parallel threads)
+- [ ] Pattern interrupt every ≤45 sec (long-form)
+- [ ] CTA is one ask, not three
+
+---
+
+## Phase 3: STORYBOARD
+
+**Goal:** visual plan that the editor / camera-op can execute without asking questions.
+
+### Scene table (one row per cut)
+
+| # | Time | Visual | Audio | Text overlay | Asset needed |
+|---|------|--------|-------|--------------|--------------|
+| 1 | 0:00-0:08 | Talking head, medium shot | Hook line | (none) | — |
+| 2 | 0:08-0:25 | Screen recording: IDE | VO | "Step 1: install" | terminal recording |
+| 3 | 0:25-0:40 | B-roll: server rack | VO | (none) | stock or own footage |
+
+### Visual rules (project-wide)
+
+- Aspect ratio: 16:9 (YouTube long) / 9:16 (shorts, Reels, TikTok) / 1:1 (LinkedIn native fallback)
+- Captions ALWAYS burned in for shorts (most viewers watch muted)
+- Brand bug in bottom-right (long-form only) for first 5 sec + last 10 sec
+- Max 2 fonts (display + body)
+- Stick to brand palette (link to logo guidelines if available)
+
+### Gate
+- [ ] One row per cut
+- [ ] All assets listed and sourced (or "to record")
+- [ ] Captions plan in place for muted viewing
+- [ ] Aspect ratio matches the channel
+
+---
+
+## Phase 4: PRODUCTION
+
+**Goal:** ship a production-ready file the publisher can upload without rework.
+
+### Tech spec per channel
+
+| Channel | Resolution | FPS | Codec | Max length | Notes |
+|---------|-----------|-----|-------|-----------|-------|
+| YouTube long | 1080p or 4K | 30 / 60 | H.264 | 12 h | Chapters required for >5 min |
+| YouTube Shorts | 1080×1920 | 30 / 60 | H.264 | 60 s | Vertical |
+| TikTok | 1080×1920 | 30 / 60 | H.264 | 10 min | Caption per scene |
+| Instagram Reels | 1080×1920 | 30 | H.264 | 90 s | First frame = thumbnail |
+| LinkedIn native | 1920×1080 / 1080×1080 | 30 | H.264 | 10 min | Captions burned in |
+| X (Twitter) | 1280×720+ | 30 / 60 | H.264 | 2 min 20 s | Add caption file |
+
+### Audio
+- Voice: -3 dBFS peak, -16 LUFS integrated
+- Music bed: -20 dBFS under voice, royalty-cleared (Epidemic, Artlist, or licensed)
+- Cuts: trim every breath / um / "so" — tight pacing matters
+
+### Pre-publish checklist
+- [ ] Color graded (consistent across cuts)
+- [ ] Audio levels normalized
+- [ ] Captions / subtitles burned in (where required) and SRT file for accessibility
+- [ ] Thumbnail designed (3 variants for A/B if YouTube)
+- [ ] Title written (≤60 chars, includes primary keyword)
+- [ ] Description with timestamps, CTAs, links
+
+### Gate
+- [ ] Tech spec matches target channel
+- [ ] Thumbnail tested at small size (mobile feed)
+- [ ] First 3 sec works without sound
+
+---
+
+## Phase 5: PUBLISH
+
+**Goal:** get the video in front of the audience and measure.
+
+### Per-channel adaptation
+
+- **YouTube long:** publish + immediately pin a comment with key timestamps + first-hour engagement push
+- **Shorts:** publish 3-5x/week for algorithm; don't link in description (kills reach)
+- **TikTok:** publish in batches at 7 PM local; respond to first 10 comments within 1 hour
+- **LinkedIn:** native upload (don't link YouTube); post in first hour of work day
+- **X:** native video; thread = video + 3-5 text takeaways
+
+### Cross-posting
+- Cut shorts from long-form (3-5 per long video)
+- Convert key insight into LinkedIn carousel + X thread
+- Embed in blog post (boosts both)
+
+### Tracking
+- UTM tags on all description links: `?utm_source=youtube&utm_medium=video&utm_campaign={series}`
+- Watch: average view duration, retention curve (cliff = where to cut next time), CTR on thumbnail
+- Iterate: kill formats with <30% retention after 3 attempts
+
+### Gate
+- [ ] Adapted per channel (no copy-paste)
+- [ ] UTMs applied
+- [ ] Tracking dashboard updated
+
+---
+
+## Final Report
+
+```markdown
+## Video Plan: {brand / series}
+
+### Strategy
+- Goal: {one line}
+- Audience: {one line}
+- Channels: {primary + secondary}
+
+### Videos Planned (next 4 weeks)
+| # | Title | Format | Channel | Status |
+|---|-------|--------|---------|--------|
+| 1 | ... | long | YouTube | scripted |
+| 2 | ... | short | Reels + TikTok + Shorts | storyboard |
+
+### Production Backlog
+- {script ready, awaiting recording}
+- {recording done, awaiting edit}
+
+### Metrics
+- Baseline → Target per video and per series
+```
+
+---
+
+## Hard Rules
+
+- **Hook decides everything** — if first 3 sec doesn't work, nothing after matters
+- **Captions for muted viewing** — most feed views are sound-off
+- **One ask in the CTA** — multiple CTAs = zero conversions
+- **Vertical for mobile-first channels** — never reupload 16:9 to TikTok / Shorts
+- **Kill what doesn't work after 3 attempts** — don't keep producing for an audience that isn't there
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Full marketing plan (logo + content + video) | `/marketing` |
+| Need brand visuals first | `/marketing:logo` |
+| Repurpose video → blog / threads | `/marketing:content` |
+| Brainstorm video topics | `brainstorm` |
+
+---
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| STRATEGY | `@docs-writer` | Document the strategy brief |
+| SCRIPT | `@docs-writer` | Draft and tighten scripts |
+| STORYBOARD | `@docs-writer` | Scene descriptions |
+| PRODUCTION | `@devops` | Tech specs + encoding |
+| PUBLISH | `@docs-writer` | Channel adaptations + tracking |