From 699ceabd577062394f24b8352eb741103e53fd5e Mon Sep 17 00:00:00 2001 From: sck_0 Date: Mon, 26 Jan 2026 08:26:16 +0100 Subject: [PATCH] fix(skills): correct YAML frontmatter syntax and remove debris from PR #30 --- skills/programmatic-seo/SKILL.md | 195 +++++++++++++++---------------- skills/schema-markup/SKILL.md | 169 +++++++++++++-------------- skills/seo-fundamentals/SKILL.md | 29 +++-- 3 files changed, 190 insertions(+), 203 deletions(-) diff --git a/skills/programmatic-seo/SKILL.md b/skills/programmatic-seo/SKILL.md index 0aa9f991..25379c8d 100644 --- a/skills/programmatic-seo/SKILL.md +++ b/skills/programmatic-seo/SKILL.md @@ -1,4 +1,3 @@ -```yaml --- name: programmatic-seo description: > @@ -9,8 +8,9 @@ description: > This skill focuses on feasibility, strategy, and page system design—not execution unless explicitly requested. --- -``` + --- + # Programmatic SEO You are an expert in **programmatic SEO strategy**—designing systems that generate @@ -18,10 +18,10 @@ You are an expert in **programmatic SEO strategy**—designing systems that gene Your responsibility is to: -* Determine **whether programmatic SEO should be done at all** -* Score the **feasibility and risk** of doing it -* Design a page system that scales **quality, not thin content** -* Prevent doorway pages, index bloat, and algorithmic suppression +- Determine **whether programmatic SEO should be done at all** +- Score the **feasibility and risk** of doing it +- Design a page system that scales **quality, not thin content** +- Prevent doorway pages, index bloat, and algorithmic suppression You do **not** implement pages unless explicitly requested. @@ -44,7 +44,7 @@ The Feasibility Index answers one question: ### Total Score: **0–100** This is a **diagnostic score**, not a vanity metric. -A high score indicates *structural suitability*, not guaranteed rankings. +A high score indicates _structural suitability_, not guaranteed rankings. --- @@ -66,9 +66,9 @@ A high score indicates *structural suitability*, not guaranteed rankings. #### 1. Search Pattern Validity (0–20) -* Clear repeatable keyword pattern -* Consistent intent across variations -* Sufficient aggregate demand +- Clear repeatable keyword pattern +- Consistent intent across variations +- Sufficient aggregate demand **Red flags:** isolated keywords, forced permutations @@ -76,9 +76,9 @@ A high score indicates *structural suitability*, not guaranteed rankings. #### 2. Unique Value per Page (0–25) -* Pages can contain **meaningfully different information** -* Differences go beyond swapped variables -* Conditional or data-driven sections exist +- Pages can contain **meaningfully different information** +- Differences go beyond swapped variables +- Conditional or data-driven sections exist **This is the single most important factor.** @@ -86,33 +86,33 @@ A high score indicates *structural suitability*, not guaranteed rankings. #### 3. Data Availability & Quality (0–20) -* Data exists to populate pages -* Data is accurate, current, and maintainable -* Data defensibility (proprietary > public) +- Data exists to populate pages +- Data is accurate, current, and maintainable +- Data defensibility (proprietary > public) --- #### 4. Search Intent Alignment (0–15) -* Pages fully satisfy intent (informational, local, comparison, etc.) -* No mismatch between query and page purpose -* Users would reasonably expect many similar pages to exist +- Pages fully satisfy intent (informational, local, comparison, etc.) +- No mismatch between query and page purpose +- Users would reasonably expect many similar pages to exist --- #### 5. Competitive Feasibility (0–10) -* Current ranking pages are beatable -* Not dominated by major brands with editorial depth -* Programmatic pages already rank in SERP (signal) +- Current ranking pages are beatable +- Not dominated by major brands with editorial depth +- Programmatic pages already rank in SERP (signal) --- #### 6. Operational Sustainability (0–10) -* Pages can be maintained and updated -* Data refresh is feasible -* Scale will not create long-term quality debt +- Pages can be maintained and updated +- Data refresh is feasible +- Scale will not create long-term quality debt --- @@ -135,23 +135,23 @@ If the verdict is **Do Not Proceed**, stop and recommend alternatives. ### 1. Business Context -* Product or service -* Target audience -* Role of these pages in the funnel -* Primary conversion goal +- Product or service +- Target audience +- Role of these pages in the funnel +- Primary conversion goal ### 2. Search Opportunity -* Keyword pattern and variables -* Estimated page count -* Demand distribution -* Trends and seasonality +- Keyword pattern and variables +- Estimated page count +- Demand distribution +- Trends and seasonality ### 3. Competitive Landscape -* Who ranks now -* Nature of ranking pages (editorial vs programmatic) -* Content depth and differentiation +- Who ranks now +- Nature of ranking pages (editorial vs programmatic) +- Content depth and differentiation --- @@ -181,10 +181,10 @@ Weaker data requires **stronger editorial value**. ### 3. URL & Architecture Discipline -* Prefer subfolders by default -* One clear page type per directory -* Predictable, human-readable URLs -* No parameter-based duplication +- Prefer subfolders by default +- One clear page type per directory +- Predictable, human-readable URLs +- No parameter-based duplication --- @@ -192,10 +192,10 @@ Weaker data requires **stronger editorial value**. Each page must fully satisfy the intent behind its pattern: -* Informational -* Comparative -* Local -* Transactional +- Informational +- Comparative +- Local +- Transactional Partial answers at scale are **high risk**. @@ -213,16 +213,16 @@ Scaling pages does **not** lower the bar for quality. Avoid: -* Doorway pages -* Auto-generated filler -* Near-duplicate content -* Indexing pages with no standalone value +- Doorway pages +- Auto-generated filler +- Near-duplicate content +- Indexing pages with no standalone value --- ## The 12 Programmatic SEO Playbooks -*(Strategic patterns, not guaranteed wins)* +_(Strategic patterns, not guaranteed wins)_ 1. Templates 2. Curation @@ -245,29 +245,29 @@ Only use playbooks supported by **data + intent + feasibility score**. ### 1. Keyword Pattern Definition -* Pattern structure -* Variable set -* Estimated combinations -* Demand validation +- Pattern structure +- Variable set +- Estimated combinations +- Demand validation --- ### 2. Data Model -* Required fields -* Data sources -* Update frequency -* Missing-data handling +- Required fields +- Data sources +- Update frequency +- Missing-data handling --- ### 3. Template Specification -* Mandatory sections -* Conditional logic -* Unique content mechanisms -* Internal linking rules -* Index / noindex criteria +- Mandatory sections +- Conditional logic +- Unique content mechanisms +- Internal linking rules +- Index / noindex criteria --- @@ -275,18 +275,17 @@ Only use playbooks supported by **data + intent + feasibility score**. ### Indexation Rules -* Not all generated pages should be indexed -* Index only pages with: - - * Demand - * Unique value - * Complete intent match +- Not all generated pages should be indexed +- Index only pages with: + - Demand + - Unique value + - Complete intent match ### Crawl Management -* Avoid crawl traps -* Segment sitemaps by page type -* Monitor indexation rate by pattern +- Avoid crawl traps +- Segment sitemaps by page type +- Monitor indexation rate by pattern --- @@ -294,11 +293,11 @@ Only use playbooks supported by **data + intent + feasibility score**. ### Pre-Index Checklist -* Unique value demonstrated -* Intent fully satisfied -* No near-duplicates -* Performance acceptable -* Canonicals correct +- Unique value demonstrated +- Intent fully satisfied +- No near-duplicates +- Performance acceptable +- Canonicals correct --- @@ -306,10 +305,10 @@ Only use playbooks supported by **data + intent + feasibility score**. If triggered, **halt indexing or roll back**: -* High impressions, low engagement at scale -* Thin content warnings -* Index bloat with no traffic -* Manual or algorithmic suppression signals +- High impressions, low engagement at scale +- Thin content warnings +- Index bloat with no traffic +- Manual or algorithmic suppression signals --- @@ -319,36 +318,34 @@ If triggered, **halt indexing or roll back**: **Feasibility Index** -* Overall Score: XX / 100 -* Verdict: Strong Fit / Moderate Fit / High Risk / Do Not Proceed -* Category breakdown with brief rationale +- Overall Score: XX / 100 +- Verdict: Strong Fit / Moderate Fit / High Risk / Do Not Proceed +- Category breakdown with brief rationale **Opportunity Summary** -* Keyword pattern -* Estimated scale -* Competition overview +- Keyword pattern +- Estimated scale +- Competition overview **Page System Design** -* URL pattern -* Data requirements -* Template outline -* Indexation rules +- URL pattern +- Data requirements +- Template outline +- Indexation rules **Risks & Mitigations** -* Thin content risk -* Data quality risk -* Crawl/indexation risk +- Thin content risk +- Data quality risk +- Crawl/indexation risk --- ## Related Skills -* **seo-audit** – Audit programmatic pages post-launch -* **schema-markup** – Add structured data to templates -* **copywriting** – Improve non-templated sections -* **analytics-tracking** – Measure performance and validate value - -``` +- **seo-audit** – Audit programmatic pages post-launch +- **schema-markup** – Add structured data to templates +- **copywriting** – Improve non-templated sections +- **analytics-tracking** – Measure performance and validate value diff --git a/skills/schema-markup/SKILL.md b/skills/schema-markup/SKILL.md index d7ffd6b8..76bc067a 100644 --- a/skills/schema-markup/SKILL.md +++ b/skills/schema-markup/SKILL.md @@ -1,4 +1,3 @@ -```yaml --- name: schema-markup description: > @@ -9,7 +8,6 @@ description: > safely according to Google guidelines. allowed-tools: Read, Glob, Grep --- -``` --- @@ -20,11 +18,11 @@ You are an expert in **structured data and schema markup** with a focus on Your responsibility is to: -* Determine **whether schema markup is appropriate** -* Identify **which schema types are valid and eligible** -* Prevent invalid, misleading, or spammy markup -* Design **maintainable, correct JSON-LD** -* Avoid over-markup that creates false expectations +- Determine **whether schema markup is appropriate** +- Identify **which schema types are valid and eligible** +- Prevent invalid, misleading, or spammy markup +- Design **maintainable, correct JSON-LD** +- Avoid over-markup that creates false expectations You do **not** guarantee rich results. You do **not** add schema that misrepresents content. @@ -69,9 +67,9 @@ This is a **diagnostic score**, not a promise of rich results. #### 1. Content–Schema Alignment (0–25) -* Schema reflects **visible, user-facing content** -* Marked entities actually exist on the page -* No hidden or implied content +- Schema reflects **visible, user-facing content** +- Marked entities actually exist on the page +- No hidden or implied content **Automatic failure** if schema describes content not shown. @@ -79,41 +77,41 @@ This is a **diagnostic score**, not a promise of rich results. #### 2. Rich Result Eligibility (0–25) -* Schema type is **supported by Google** -* Page meets documented eligibility requirements -* No known disqualifying patterns (e.g. self-serving reviews) +- Schema type is **supported by Google** +- Page meets documented eligibility requirements +- No known disqualifying patterns (e.g. self-serving reviews) --- #### 3. Data Completeness & Accuracy (0–20) -* All required properties present -* Values are correct, current, and formatted properly -* No placeholders or fabricated data +- All required properties present +- Values are correct, current, and formatted properly +- No placeholders or fabricated data --- #### 4. Technical Correctness (0–15) -* Valid JSON-LD -* Correct nesting and types -* No syntax, enum, or formatting errors +- Valid JSON-LD +- Correct nesting and types +- No syntax, enum, or formatting errors --- #### 5. Maintenance & Sustainability (0–10) -* Data can be kept in sync with content -* Updates won’t break schema -* Suitable for templates if scaled +- Data can be kept in sync with content +- Updates won’t break schema +- Suitable for templates if scaled --- #### 6. Spam / Policy Risk (0–5) -* No deceptive intent -* No over-markup -* No attempt to game rich results +- No deceptive intent +- No over-markup +- No attempt to game rich results --- @@ -136,21 +134,21 @@ If verdict is **Do Not Implement**, stop and explain why. ### 1. Page Type -* What kind of page is this? -* Primary content entity -* Single-entity vs multi-entity page +- What kind of page is this? +- Primary content entity +- Single-entity vs multi-entity page ### 2. Current State -* Existing schema present? -* Errors or warnings? -* Rich results currently shown? +- Existing schema present? +- Errors or warnings? +- Rich results currently shown? ### 3. Objective -* Which rich result (if any) is targeted? -* Expected benefit (CTR, clarity, trust) -* Is schema *necessary* to achieve this? +- Which rich result (if any) is targeted? +- Expected benefit (CTR, clarity, trust) +- Is schema _necessary_ to achieve this? --- @@ -158,39 +156,39 @@ If verdict is **Do Not Implement**, stop and explain why. ### 1. Accuracy Over Ambition -* Schema must match visible content exactly -* Do not “add content for schema” -* Remove schema if content is removed +- Schema must match visible content exactly +- Do not “add content for schema” +- Remove schema if content is removed --- ### 2. Google First, Schema.org Second -* Follow **Google rich result documentation** -* Schema.org allows more than Google supports -* Unsupported types provide minimal SEO value +- Follow **Google rich result documentation** +- Schema.org allows more than Google supports +- Unsupported types provide minimal SEO value --- ### 3. Minimal, Purposeful Markup -* Add only schema that serves a clear purpose -* Avoid redundant or decorative markup -* More schema ≠ better SEO +- Add only schema that serves a clear purpose +- Avoid redundant or decorative markup +- More schema ≠ better SEO --- ### 4. Continuous Validation -* Validate before deployment -* Monitor Search Console enhancements -* Fix errors promptly +- Validate before deployment +- Monitor Search Console enhancements +- Fix errors promptly --- ## Supported & Common Schema Types -*(Only implement when eligibility criteria are met.)* +_(Only implement when eligibility criteria are met.)_ ### Organization @@ -221,9 +219,9 @@ Use for: SaaS apps and tools Use only when: -* Questions and answers are visible -* Not used for promotional content -* Not user-generated without moderation +- Questions and answers are visible +- Not used for promotional content +- Not user-generated without moderation --- @@ -231,8 +229,8 @@ Use only when: Use only for: -* Genuine step-by-step instructional content -* Not marketing funnels +- Genuine step-by-step instructional content +- Not marketing funnels --- @@ -252,9 +250,9 @@ Use for: real, physical business locations **Strict rules:** -* Reviews must be genuine -* No self-serving reviews -* Ratings must match visible content +- Reviews must be genuine +- No self-serving reviews +- Ratings must match visible content --- @@ -270,9 +268,9 @@ Use `@graph` when representing multiple entities. Rules: -* One primary entity per page -* Others must relate logically -* Avoid conflicting entity definitions +- One primary entity per page +- Others must relate logically +- Avoid conflicting entity definitions --- @@ -280,17 +278,17 @@ Rules: ### Required Tools -* Google Rich Results Test -* Schema.org Validator -* Search Console Enhancements +- Google Rich Results Test +- Schema.org Validator +- Search Console Enhancements ### Common Failure Patterns -* Missing required properties -* Mismatched values -* Hidden or fabricated data -* Incorrect enum values -* Dates not in ISO 8601 +- Missing required properties +- Mismatched values +- Hidden or fabricated data +- Incorrect enum values +- Dates not in ISO 8601 --- @@ -298,19 +296,19 @@ Rules: ### Static Sites -* Embed JSON-LD in templates -* Use includes for reuse +- Embed JSON-LD in templates +- Use includes for reuse ### Frameworks (React / Next.js) -* Server-side rendered JSON-LD -* Data serialized directly from source +- Server-side rendered JSON-LD +- Data serialized directly from source ### CMS / WordPress -* Prefer structured plugins -* Use custom fields for dynamic values -* Avoid hardcoded schema in themes +- Prefer structured plugins +- Use custom fields for dynamic values +- Avoid hardcoded schema in themes --- @@ -318,9 +316,9 @@ Rules: ### Schema Strategy Summary -* Eligibility Index score + verdict -* Supported schema types -* Risks and constraints +- Eligibility Index score + verdict +- Supported schema types +- Risks and constraints ### JSON-LD Implementation @@ -338,10 +336,10 @@ Where and how to add it ### Validation Checklist -* [ ] Valid JSON-LD -* [ ] Passes Rich Results Test -* [ ] Matches visible content -* [ ] Meets Google eligibility rules +- [ ] Valid JSON-LD +- [ ] Passes Rich Results Test +- [ ] Matches visible content +- [ ] Meets Google eligibility rules --- @@ -357,11 +355,6 @@ Where and how to add it ## Related Skills -* **seo-audit** – Full SEO review including schema -* **programmatic-seo** – Templated schema at scale -* **analytics-tracking** – Measure rich result impact - -``` - -Just say the word. -``` +- **seo-audit** – Full SEO review including schema +- **programmatic-seo** – Templated schema at scale +- **analytics-tracking** – Measure rich result impact diff --git a/skills/seo-fundamentals/SKILL.md b/skills/seo-fundamentals/SKILL.md index 950aa928..66999355 100644 --- a/skills/seo-fundamentals/SKILL.md +++ b/skills/seo-fundamentals/SKILL.md @@ -1,4 +1,3 @@ -```yaml --- name: seo-fundamentals description: > @@ -7,14 +6,13 @@ description: > *why* SEO works, not how to execute specific optimizations. allowed-tools: Read, Glob, Grep --- -``` --- # SEO Fundamentals > **Foundational principles for sustainable search visibility.** -> This skill explains *how search engines evaluate quality*, not tactical shortcuts. +> This skill explains _how search engines evaluate quality_, not tactical shortcuts. --- @@ -46,9 +44,9 @@ Core Web Vitals measure **how users experience a page**, not whether it deserves **Important context:** -* CWV rarely override poor content -* They matter most when content quality is comparable -* Failing CWV can *hold back* otherwise good pages +- CWV rarely override poor content +- They matter most when content quality is comparable +- Failing CWV can _hold back_ otherwise good pages --- @@ -125,17 +123,17 @@ Search engines evaluate **output quality**, not authorship method. ### Effective Use -* AI as a drafting or research assistant -* Human review for accuracy and clarity -* Original insights and synthesis -* Clear accountability +- AI as a drafting or research assistant +- Human review for accuracy and clarity +- Original insights and synthesis +- Clear accountability ### Risky Use -* Publishing unedited AI output -* Factual errors or hallucinations -* Thin or duplicated content -* Keyword-driven text with no value +- Publishing unedited AI output +- Factual errors or hallucinations +- Thin or duplicated content +- Keyword-driven text with no value --- @@ -171,6 +169,5 @@ SEO fundamentals should be validated using **multiple signals**, not single metr --- > **Key Principle:** -> Sustainable SEO is built on *useful content*, *technical clarity*, and *trust over time*. +> Sustainable SEO is built on _useful content_, _technical clarity_, and _trust over time_. > There are no permanent shortcuts. -