opencode-skills-collection 4.0.63 → 4.0.65

package/bundled-skills/seo-aeo-blog-writer/SKILL.md

@@ -1,93 +1,174 @@
 ---
 name: seo-aeo-blog-writer
-description: "Writes long-form blog posts with TL;DR block, definition sentence, comparison table, and 5-question FAQ for SEO ranking and AEO citation. Activate when the user wants to write a blog post, article, or long-form content piece."
+description: "Writes search-intent-led long-form articles with answer-first structure, FAQ coverage, internal links, and conversion paths for SEO and AEO."
 risk: safe
 source: community
 date_added: "2026-04-01"
 ---
 
-# SEO-AEO Blog Writer
+# Blog Writer Skill
+
+## Description
+Activate this skill when the user wants to write a blog post, article, or
+long-form content piece for SEO and AEO purposes. Trigger phrases include:
+"write a blog post", "create an article", "generate blog content",
+"write a long-form post about", "blog writer".
+
+## Input Format
+```json
+{
+  "topic": "string — the main subject of the article",
+  "primary_keyword": "string — exact keyword to rank for",
+  "secondary_keywords": ["string", "string"],
+  "target_audience": "string — who is reading this",
+  "tone": "informational | conversational | authoritative | persuasive",
+  "word_count": "integer — minimum 800, maximum 3000, default 1500",
+  "cluster_context": "string — optional, paste content cluster output here",
+  "internal_link_targets": ["string — page/post titles to link to"],
+  "product_cta": "string — optional CTA and destination",
+  "search_intent_evidence": "string — optional observed SERP/API evidence",
+  "distribution_platforms": ["string — optional external platforms"]
+}
+```
+
+Write to the dominant search intent, not merely the keyword. The article should solve a recognizable problem and make the next product action clear without turning an informational article into an unsupported sales pitch.
+
+## Output Structure
+
+The skill must always produce a blog post in this exact section order:
+```markdown
+# [H1: Primary Keyword-Optimised Title]
+
+> **TL;DR:** [2–3 sentence direct answer to the article's core question.
+> This is the AEO extraction block — write it to be lifted by AI engines.]
+
+## Introduction
+[Hook sentence. State the problem or question clearly in the first 2 lines.
+Mention the primary keyword naturally within the first 100 words.]
 
-## Overview
+---
+
+## [H2: What Is {Topic}]
+[Definition block — write a single, clean, extractable definition sentence
+as the very first line of this section. Follow with 2–3 paragraphs of context.]
+
+---
+
+## [H2: Why {Topic} Matters / The Core Problem]
+[Establish relevance. Use bullet points or a numbered list in this section.]
+
+---
+
+## [H2: How {Topic} Works / Main Body Section]
+[Deepest section. Use H3 subheadings for sub-concepts. Include at least
+one comparison block formatted as a table if comparing two or more things.]
+
+### [H3: Sub-concept 1]
+### [H3: Sub-concept 2]
+### [H3: Sub-concept 3]
+
+---
+
+## [H2: Practical Steps / How To Section — if applicable]
+[Numbered list of steps. Each step max 2 sentences. Scannable.]
+
+---
 
-Writes structured long-form blog posts (800–3000 words) that satisfy both SEO ranking signals and AEO citation requirements. Every post includes a TL;DR direct-answer block, a definition sentence, structured H2/H3 hierarchy, a comparison table where relevant, and exactly 5 FAQ entries written for AI extraction.
+## [H2: Common Mistakes / What To Avoid — if applicable]
+[Bullet list format. Short, punchy, extractable by AI.]
 
-Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).
+---
 
-## When to Use This Skill
+## Frequently Asked Questions
 
-- Use when writing a cluster article from a content cluster map
-- Use when creating a long-form guide to build topical authority
-- Use when you need content that can be cited by AI engines like Perplexity or ChatGPT
-- Use when you need a blog post that follows a consistent, auditable structure
+**Q: [Question using a long-tail keyword]**
+A: [Direct answer, 2–3 sentences max. No fluff.]
 
-## How It Works
+**Q: [Question using a secondary keyword]**
+A: [Direct answer.]
 
-### Step 1: Write the TL;DR Block First
-Write a 2–3 sentence direct answer to the article's core question. Place it immediately after the H1 in a blockquote. This is the first block AI engines attempt to extract.
+**Q: [Question the target audience commonly asks]**
+A: [Direct answer.]
 
-### Step 2: Build the Heading Skeleton
-Set H1, H2s (4–6), and H3s before writing any body content. The first H2 must be a "What Is" section with a clean definition sentence as its opening line.
+**Q: [Question about cost, time, or comparison]**
+A: [Direct answer.]
 
-### Step 3: Write Body Sections
-Follow the section order: What Is → Why It Matters → How It Works (with H3 sub-concepts) → Practical Steps → Common Mistakes → FAQ → Conclusion.
+**Q: [Question about a common misconception]**
+A: [Direct answer.]
 
-### Step 4: Write 5 FAQ Entries
-Use long-tail and secondary keywords as questions. Each answer must be under 50 words and self-contained — readable without any surrounding context.
+---
 
-### Step 5: Run AEO and SEO Checklists
-Verify TL;DR presence, definition sentence, FAQ count, keyword placement, and heading structure before outputting.
+## Conclusion
+[Restate the core answer from the TL;DR in new words.
+One call to action sentence at the end.]
 
-## Examples
+---
 
-### Example: TL;DR Block
-How to Manage a Remote Engineering Team
+## Internal Links
+[INTERNAL LINK: {internal_link_target_1}]
+[INTERNAL LINK: {internal_link_target_2}]
 
-TL;DR: Managing a remote engineering team requires async
-communication tools, clear documentation standards, and
-timezone-aware sprint planning. Teams that nail these three
-areas ship consistently regardless of where members are located.
+## External Links
+[EXTERNAL LINK: authoritative source relevant to primary keyword]
 
+## Product CTA
+[CTA: relevant product action and destination]
 
-### Example: FAQ Section
-Q: What is the biggest challenge of remote engineering teams?
-A: Async communication. Without shared hours, decisions slow down
-and context gets lost. Teams that document decisions in writing
-and use structured standup tools close this gap fastest.
-Q: How do you run a daily standup with a remote team?
-A: Use async video or text standups posted at the start of each
-member's day. Tools like Loom or Slack threads work well.
-Avoid live calls across more than 2 timezones.
+## External Distribution Notes
+- [Platform]: [adaptation angle, canonical-link decision, and backlink target]
+```
 
-## Best Practices
+---
 
-- ✅ **Do:** Write the TL;DR block before writing anything else — it anchors the article
-- ✅ **Do:** Make the "What Is" definition sentence extractable on its own — one clean sentence
-- ✅ **Do:** Use secondary keywords as FAQ questions to capture long-tail traffic
-- ❌ **Don't:** Write FAQ answers longer than 50 words — AI engines skip long answers
-- ❌ **Don't:** Use duplicate H2 headings anywhere in the article
-- ❌ **Don't:** Skip the comparison table if the topic involves comparing options
+## AEO Requirements
+Every blog post produced by this skill MUST contain:
 
-## Common Pitfalls
+- [ ] A TL;DR block immediately after the H1
+- [ ] A clean definition sentence as the first line of the "What Is" section
+- [ ] At least one comparison table (if topic involves comparing options)
+- [ ] Exactly 5 FAQ entries with direct, concise answers
+- [ ] Bullet or numbered lists in at least 2 sections
+- [ ] Primary keyword in: H1, first 100 words, at least one H2, meta description
+- [ ] A relevant product CTA or next step is present when the article supports conversion
+- [ ] Internal links connect the article to a foundational page and, where relevant, the product
 
-- **Problem:** TL;DR block is too vague to be extracted as a direct answer
-  **Solution:** The TL;DR must answer the article's core question in 2–3 sentences. If it doesn't answer a specific question, rewrite it.
+---
 
-- **Problem:** FAQ answers reference "as mentioned above" or other context
-  **Solution:** Every FAQ answer must stand completely alone — no references to other parts of the article.
+## SEO Requirements
 
-## Related Skills
+- H1: appears exactly once, contains primary keyword
+- H2s: 4–6 per article, no keyword stuffing
+- H3s: used only inside H2 sections, not standalone
+- Word count: stay within the range specified in input; default 1500 words
+- Keyword use: natural and intent-aligned; do not force a density percentage
+- No duplicate headings
 
-- `@seo-aeo-content-cluster` — provides the topic and keyword for this article
-- `@seo-aeo-content-quality-auditor` — audits the completed post for SEO and AEO signals
-- `@seo-aeo-internal-linking` — maps links between this post and related pages
+---
 
-## Additional Resources
+## Execution Steps
 
-- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
-- [Full Blog Writer SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/blog-writer/SKILL.md)
+1. Read `cluster_context` if provided — use it to decide which sub-topics
+   to cover and which to leave for linked cluster articles
+2. Review `search_intent_evidence` if provided and state the problem the article solves
+3. Write the TL;DR block first — this anchors the whole article's direction
+4. Build the heading skeleton before writing body content
+5. Write the definition block in the "What Is" section as a single sentence
+6. Write the FAQ section using long-tail and secondary keywords as questions
+7. Insert internal links at natural transition points, including a foundational page and product CTA where appropriate
+8. Add external-source suggestions only when they are authoritative and relevant
+9. Do a final keyword placement check against the SEO Requirements checklist
+10. Do a final AEO, conversion, and claim-verification pass before outputting
+
+---
+
+## Connected Skills
+- Receives output from: `seo-aeo-content-cluster`
+- Feeds output to: `seo-aeo-content-quality-auditor`, `seo-aeo-internal-linking`
+
+## When to Use
+
+Use when creating or revising a long-form article intended to capture a specific search intent and guide readers toward a relevant next step.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- Search performance depends on the actual site, competition, content quality, and indexing; this skill cannot guarantee rankings or traffic.

package/bundled-skills/seo-aeo-content-cluster/SKILL.md

@@ -1,94 +1,213 @@
 ---
 name: seo-aeo-content-cluster
-description: "Builds a topical authority map with a pillar page, prioritised cluster articles, content types, internal link map, and content gap analysis. Activate when the user wants to build a content cluster, topic map, or content strategy."
+description: "Builds a topical authority map from business goals, search intent, existing content, and gaps, then prioritises foundational and supporting pages."
 risk: safe
 source: community
 date_added: "2026-04-01"
 ---
 
-# SEO-AEO Content Cluster
+# Content Cluster Skill
 
-## Overview
+## Description
+Activate this skill when the user wants to build topical authority around
+a subject by mapping out a pillar page and its supporting cluster articles.
+Trigger phrases include: "build a content cluster", "create a topic map",
+"content pillar strategy", "what should I write about for [topic]",
+"cluster: [topic]", "generate a content strategy for [niche]".
 
-Maps out a complete topical authority structure around a pillar keyword. Produces a pillar page definition, 8–15 cluster articles sorted into Priority 1/2/3 tiers, a content type for each, an internal link map, and a content gap analysis identifying AEO opportunities competitors are missing.
+---
+
+## Input Format
+```json
+{
+  "pillar_topic": "string — the main subject to build authority around",
+  "primary_keyword": "string — the keyword the pillar page targets",
+  "target_audience": "string — who this content is for",
+  "existing_content": ["string — titles of pages/posts already published"],
+  "target_keywords": ["string — additional keywords to work into the cluster"],
+  "cluster_size": "integer — foundational pages to generate, 5–10, default 10",
+  "search_intent_evidence": "string — optional browser/API research",
+  "conversion_goal": "string — what the content should move readers to do"
+}
+```
+
+For a new website, produce 5–10 foundational pages, defaulting to 10 only when there are at least 10 distinct, defensible search intents. Do not create near-duplicate pages to hit the default. Every page must solve a problem, own a query, and lead to a relevant product or next step.
+
+---
+
+## Output Structure
+
+The skill must always produce output in this exact format:
+```markdown
+## Pillar Page
+
+| Field              | Value                                      |
+|--------------------|--------------------------------------------|
+| Title              | [Pillar page title with primary keyword]   |
+| Primary Keyword    | [keyword]                                  |
+| Search Intent      | informational / transactional / commercial |
+| Target Audience    | [audience]                                 |
+| Page Type          | Pillar — comprehensive, high-level guide   |
+| Word Count Target  | 2500–4000 words                            |
+| AEO Priority       | High — this page anchors the whole cluster |
+
+---
+
+## Cluster Articles
+
+### Priority 1 — Write These First
+These articles build the foundation. High search volume, clear intent.
+
+| # | Title                        | Target Keyword       | Intent          | Content Type     | Links To         |
+|---|------------------------------|----------------------|-----------------|------------------|------------------|
+| 1 | [Article title]              | [keyword]            | informational   | how-to guide     | Pillar Page      |
+| 2 | [Article title]              | [keyword]            | informational   | explainer        | Pillar Page      |
+| 3 | [Article title]              | [keyword]            | commercial      | comparison       | Pillar Page      |
+
+---
+
+### Priority 2 — Write These Second
+These deepen authority. Medium volume, long-tail focus.
+
+| # | Title                        | Target Keyword       | Intent          | Content Type     | Links To         |
+|---|------------------------------|----------------------|-----------------|------------------|------------------|
+| 4 | [Article title]              | [keyword]            | informational   | listicle         | Art. 1, Pillar   |
+| 5 | [Article title]              | [keyword]            | transactional   | case study       | Art. 3, Pillar   |
+| 6 | [Article title]              | [keyword]            | informational   | FAQ page         | Art. 1, Art. 2   |
+
+---
 
-Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).
+### Priority 3 — Write These Last
+Long-tail reinforcement. Lower volume, high conversion intent.
 
-## When to Use This Skill
+| # | Title                        | Target Keyword       | Intent          | Content Type     | Links To         |
+|---|------------------------------|----------------------|-----------------|------------------|------------------|
+| 7 | [Article title]              | [keyword]            | transactional   | review           | Pillar Page      |
+| 8 | [Article title]              | [keyword]            | informational   | glossary         | Art. 2, Art. 4   |
 
-- Use when building topical authority around a new subject
-- Use when you need to know what to write next to support a pillar page
-- Use when planning a content calendar for a niche
-- Use when you want to identify AEO content gaps competitors are missing
+---
+
+## Internal Link Map
+
+Pillar Page
+├── Article 1 → links back to Pillar
+├── Article 2 → links back to Pillar
+├── Article 3 → links back to Pillar, links to Article 1
+├── Article 4 → links to Article 1, Pillar
+├── Article 5 → links to Article 3, Pillar
+├── Article 6 → links to Article 1, Article 2
+├── Article 7 → links to Pillar
+└── Article 8 → links to Article 2, Article 4
+
+Rule: Every cluster article must link back to the Pillar Page.
+Rule: No orphan articles — every article links to at least one other article.
+
+## Foundational Page Plan
+
+| # | Page / Article | Problem Solved | Primary Query | Intent | Product CTA | Supporting Links |
+|---|----------------|----------------|---------------|--------|-------------|------------------|
+| 1 | [title] | [problem] | [query] | [intent] | [CTA] | [targets] |
+
+Use this section for the first publishing wave. The landing page, foundational pages, and later cluster articles must not compete for the same intent.
+
+## 20-Day Editorial Calendar
+
+| Day | Topic / Title | Target Query | Search Intent | Article Format | Internal Link Target | External Distribution Candidate |
+|-----|---------------|--------------|---------------|----------------|----------------------|--------------------------------|
+| 1 | [title] | [query] | [intent] | [format] | [page] | [Medium/Hashnode/dev.to/other] |
 
-## How It Works
+Create 20 distinct topics after the foundation is mapped. Prefer topics that answer real questions, solve problems, support the product, and can be linked back to a foundational page.
 
-### Step 1: Define the Pillar Page
-Set the primary keyword, target audience, and word count target (2500–4000 words) for the pillar page that anchors the cluster.
+---
 
-### Step 2: Generate Cluster Articles
-Produce 8–15 subtopics sorted into three priority tiers:
-- **Priority 1** — High volume, clear intent. Write these first.
-- **Priority 2** — Medium volume, long-tail focus. Write second.
-- **Priority 3** — Low volume, high conversion intent. Write last.
+## Content Gap Analysis
 
-Assign each article a unique keyword, content type, search intent, and link map.
+Topics the cluster covers that competitors likely miss:
+- [Gap 1 — underserved angle on the pillar topic]
+- [Gap 2 — long-tail question with no strong existing answer]
+- [Gap 3 — AEO opportunity: question AI engines commonly surface]
 
-### Step 3: Build Internal Link Map
-Every cluster article must link back to the pillar page. No orphan articles. Show the full tree of relationships.
+Topics to deliberately exclude from this cluster
+(belong to a different cluster):
+- [Out-of-scope topic 1]
+- [Out-of-scope topic 2]
 
-### Step 4: Run Content Gap Analysis
-Identify angles that competitors likely miss — especially question-based AEO opportunities that AI engines commonly surface.
+---
 
-## Examples
+## AEO Cluster Signals
 
-### Example: Automated Budgeting Cluster
-Pillar: The Complete Guide to Automated Budgeting
-Priority 1:
+At least 2 cluster articles must be structured as direct-answer pages:
+- One FAQ page targeting 8–10 questions around the pillar topic
+- One "What Is" explainer with a clean definition as the opening sentence
 
-How to Build a Budget That Actually Works | how-to guide
-Best Budgeting Apps Compared | comparison
-What Is Zero-Based Budgeting? | explainer ← AEO priority
+These two articles have the highest probability of being
+extracted by AI engines.
 
-Priority 2:
-4. How to Automate Your Savings in 3 Steps | how-to guide
-5. Budgeting for Millennials: What Nobody Tells You | opinion
-Link Map:
-Pillar ← Article 1, 2, 3, 4, 5
-Article 1 ↔ Article 4
-Article 2 → Article 3
-AEO Priority:
-★ Article 3 — "What Is" format has highest AI extraction probability
-★ Article 2 — comparison table will be lifted for product queries
+---
 
-## Best Practices
+## Cluster Health Checklist
+
+- [ ] Pillar page defined with clear keyword and intent
+- [ ] 5–10 foundational pages generated, default 10 when justified
+- [ ] Every article has a unique target keyword (no overlap)
+- [ ] Every article assigned a content type
+- [ ] Every article linked back to the Pillar Page
+- [ ] No orphan articles in the link map
+- [ ] At least one FAQ page in the cluster
+- [ ] At least one comparison or case study article
+- [ ] Content gap section completed
+- [ ] Every foundational page has a distinct search intent and conversion path
+- [ ] 20-day editorial calendar completed without cannibalizing existing pages
+```
 
-- ✅ **Do:** Assign every cluster article a unique target keyword — no overlap
-- ✅ **Do:** Include at least one FAQ page and one comparison article in every cluster
-- ✅ **Do:** Flag the 2 highest AEO-opportunity articles for priority writing
-- ❌ **Don't:** Let any article become an orphan — every article links to at least one other
-- ❌ **Don't:** Target the same keyword on both the pillar and a cluster article
+---
 
-## Common Pitfalls
+## Content Types Available
 
-- **Problem:** Cluster articles all target similar keywords and cannibalise each other
-  **Solution:** Run a uniqueness check — every article needs a distinct keyword with no semantic overlap.
+When assigning content types, use only from this list:
 
-- **Problem:** No AEO content in the cluster
-  **Solution:** At least 2 articles must be structured as direct-answer pages (FAQ or "What Is" explainer).
+| Type           | Best For                                        |
+|----------------|-------------------------------------------------|
+| how-to guide   | step-by-step processes                          |
+| explainer      | concept definitions and overviews               |
+| listicle       | roundups, tools, resources                      |
+| comparison     | X vs Y, best options                            |
+| case study     | real-world application, results                 |
+| FAQ page       | question clusters, AEO targeting                |
+| review         | product or service evaluation                   |
+| glossary       | terminology, definitions, long-tail keywords    |
+| opinion/take   | thought leadership, contrarian angles           |
 
-## Related Skills
+---
 
-- `@seo-aeo-keyword-research` — provides the keyword foundation for the cluster
-- `@seo-aeo-blog-writer` — writes the Priority 1 cluster articles
-- `@seo-aeo-internal-linking` — builds the detailed link map from cluster output
+## Execution Steps
+
+1. Read `existing_content` — mark any titles that already exist
+   so the cluster doesn't duplicate them
+2. Identify the pillar topic's full semantic territory —
+   what questions, angles, and sub-topics surround it
+3. Run a content gap pass — what angles are underserved
+   or missing entirely in this space
+4. Assign each subtopic a unique keyword with no overlap
+   between articles or with the pillar keyword
+5. Classify each subtopic's search intent before assigning content type
+6. Sort all subtopics into Priority 1, 2, and 3 tiers
+   based on search volume and foundational relevance
+7. Build the 5–10-page foundational plan before expanding to the 20-day calendar
+8. Build the internal link map — verify no orphan articles exist
+9. Flag the 2 highest AEO-opportunity articles in the cluster
+10. Complete the content gap section and editorial calendar before outputting
 
-## Additional Resources
+---
+
+## Connected Skills
+- Receives output from: `seo-aeo-keyword-research`
+- Feeds output to: `seo-aeo-blog-writer`, `seo-aeo-internal-linking`
 
-- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
-- [Full Content Cluster SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/content-cluster/SKILL.md)
+## When to Use
+
+Use when planning a pillar page, foundational pages, and supporting articles around a product, service, or topic.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- A content map is a prioritisation aid, not measured demand or a guarantee that every proposed topic will rank.