SEOwlsClaw — Core Skill (v0.9.2)#

Name & Description#

Name: seowlowsclaw

Description: Full-stack SEO and content marketing system. Generates SEO-optimised content (landing pages, blog posts, product pages, FAQ, social) using persona-driven writing, multi-client brand profiles, and locale-aware templates. Supports brief-first agency workflows via seobrief + --from-brief, strategic cluster planning via seoplan, and a three-layer architecture (Locale → Brand → Persona) for clean multi-client work. Outputs plain text or deploy-ready HTML with full schema markup. Named "SEOwlsClaw" (pronounced "See Owls Claw") — the single 'O' makes it sound like "See".

---

When to Use#

Use only when Chris needs SEO-ready content generated with specific personas, keyword strategies, and clean output that can be directly deployed.

Trigger phrases:

• "Generate SEO blog post about X"
• "Write product description using E-Commerce Manager persona"
• "Create landing page for Y sale campaign"
• "Audit my SEO strategy"
• "Give me the HTML for a product page about X"
• "Create a content brief for X"
• "Brief me on [topic] before writing"
• "I need a brief for a Blogpost about X"
• "Load brand profile for [client]"
• "Activate brand [id]"
• "Set up brand [client name]"
• "Build an SEO plan for [niche]"
• "Plan a content cluster for [topic]"
• "Give me a site architecture for [niche]"
• "What pages should I build for [topic]?"
• "Show me quick wins for [niche]"
• "I need a content strategy for [client]"

---

Capability Declaration#

CapabilityStatusNotesNetwork / web search✅ Read-onlySERP lookup via search tool — no credentials stored in this skillFile system writes⚠️ Confirmation requiredAgent must ask user before saving any file — never writes autonomouslyPurchases / payments❌ NoneGenerates transactional content text only — does not initiate, process, or interact with any payment systemOAuth / API credentials❌ NoneNo API keys, tokens, or authentication stored or required by this skillCrypto / blockchain❌ NoneSchema.org JSON-LD is used for SEO structured data only — no crypto or blockchain operations allowedAutonomous execution⚠️ GatedFile saves and SERP lookups require explicit user trigger — no background runs

---

Core Commands - Triggers#

CommandOutputExamplepersona <name>Sets writing style/tone for next write or writehtml``persona vintage-expert``write <type> "prompt"Plain text content — readable in chat, ready to paste into any editorwrite Blogpost "Why is iPhone 16 Pro Max better than 15"``writehtml <type> "prompt"Pure HTML code — uses TEMPLATES/<type>.md structure, copy-paste ready for deploymentwritehtml Productnew "Leica M6 TTL Chrome, serial 2741xxx, mint condition"``research <topic>Keyword cluster + SERP analysisresearch best sony bravia 55 inch tv``checks <url>SEO audit checklist against a live URLchecks https://example.com/blog-post-example``checks <type>SEO audit against page type template (preview mode)checks Productnew``personasList all available personas with one-line descriptionspersonas``personas --show <id>Show full details of one personapersonas --show vintage-expert``brand <id>Loads client brand profile (CTAs, tone sliders, compliance rules)brand example-id``brandsLists all brand profiles or shows details for onebrands --show example-id``seobrief <type> "topic"Generates a structured SEO content brief with KW cluster, outline, PAA, and competitor gapsseobrief Blogpost "DIY computer build" --lang de``seoplan "niche"Builds a full SEO cluster plan — tiers nodes into PILLAR / QUICKWIN / FOUNDATION / STRATEGIC with keyword data, persona assignments, internal link matrix, and numbered execution orderseoplan "best vlogging camera for beginners" --lang en

Command Execution Rules — CRITICAL#

All SEOwlsClaw commands ( persona, write, writehtml, research, checks, seobrief, seoplan, brand, brands) are internal chat commands processed by this skill. They are NOT shell commands, NOT OS executables, and must NEVER be passed to exec, cron, or any other system tool.

How to recognise a SEOwlsClaw command#

A SEOwlsClaw command is active when the user input:

• starts with one of the command keywords above (with or without a leading /), OR
• matches a trigger phrase from the "When to Use" section above.

Both persona vintage-expert and /persona vintage-expert are valid so treat them identically as internal skill commands.

Execution decision tree#

1. User input received ► Is it a SEOwlsClaw command or trigger phrase? ► If NO than respond normally, no skill workflow needed. ► If YES, than load BRAIN_ARCHITECTURE.md → run Steps 0–7 → output result in chat.

DO NOT call exec, cron, or any other tool to "run" the command.

---

Tool usage rules for this skill#

Situation❌ WRONG✅ CORRECTUser writes persona vintage-expertPass to exec toolParse internally, load PERSONAS/vintage-expert.mdUser writes write Blogpost ...Create a cron job with the command as payloadRun Brain Steps 0–7, return plain-text article in chatUser writes /write Blogpost ...Treat /write as a shell binaryStrip the /, treat as internal write command, same as aboveUser wants content right nowSchedule with cronExecute immediately in the current sessionUser says "schedule this for 18:00"Ignore scheduling intentUse cron with kind: agentTurn + the SEOwlsClaw command as message

When cron IS allowed#

Only use the cron tool when the user explicitly requests a scheduled or delayed execution — for example:

• "Schedule this blog post generation for tonight at 8pm"
• "Run this every Monday at 9am"

In all other cases: execute the skill workflow immediately in the current chat session.

Zero autonomous execution#

This skill never runs in the background, never writes files without confirmation, and never triggers tool calls unless the user has explicitly issued a command or trigger phrase in the current session.

Note: Direct commands like persona ..., write ..., or writehtml ... also activate this skill immediately — no natural-language trigger phrase needed. Execute in-session without any exec or cron tool calls.

---

Skill File Map — Quick Navigation#

This is the master reference for every file in the skill. The agent uses this to know what to load and when. Load only what the current command and workflow requires — never all files at once.

Root Files (Always Available)#

FilePurposeWhen to LoadSKILL.mdEntry point — this fileAlways loaded firstBRAIN_ARCHITECTURE.mdFull step-by-step processing logic, variable engineLoad at workflow startCOMMANDS.mdComplete command + flag referenceLoad when user asks about commands or flagsPAGE_STRUCTURES.mdMaster index linking all page templatesLoad when selecting a templateSEO_PATH.mdFull SEO workflow: research → write → checkLoad for research and strategic planning

PERSONAS/#

FilePurposeWhen to Load_index.mdRegistry of all persona IDs + file pathsLoad first on every persona commandblogger.mdDefault persona — load if no persona setStep 2b fallbackecommerce-manager.mdConversion-focused writingOn persona ecommerce-managercreative-writer.mdNarrative, emotional writingOn persona creative-writerresearcher.mdNeutral, fact-based — also used internally by seobriefAlways on seobrief``vintage-expert.mdCollector-focused, authoritativeOn persona vintage-experttravel-photographer.mdLocation + gear-focusedOn persona travel-photographer

LOCALE/#

FilePurposeWhen to Loadbase.mdEnglish defaults for all locale keysLoad on every write or writehtml``de.mdGerman overrides (Sie-form, DD.MM.YYYY, 1.090,00 €)Load when --lang defr.mdFrench overrides (vous-form, guillemets, thin-space thousands)Load when --lang fres.mdSpanish overrides (tú-form, ¿¡ punctuation)Load when --lang espt.mdPortuguese overrides (você-form, pt-BR variant)Load when --lang pt

BRANDS/#

FilePurposeWhen to Load_index.mdRegistry of all brand IDs + file pathsLoad first on every brand command<id>.mdBrand CTAs, tone sliders, compliance rulesLoad when brand active or --brand flag

SEO_RULES/#

FilePurposeWhen to Load_index.mdRegistry of all rule filesLoad first at Step 2funiversal.mdRules applying to every page type (E-E-A-T, on-page SEO, traps, FAQ, quality, natural language)Step 2f, every write/ writehtml``<page_type>.mdDo's/don'ts, required elements, keyword placement for that page typeStep 2f, matched to the active page type

SEO_CHECKS/#

FilePurposeWhen to Loadsearch_intent.mdSERP lookup + intent scoring + disambiguationStep 0 — before everything elseschema-markup.mdSchema.org rules + all {SCHEMA_*} variable definitionsStep 5–6 for writehtml``seo-checks-reference.mdFull SEO audit referenceStep 6 + checks commandseo-output-quality-checklist.mdPre-output quality gatesStep 6.5 before final outputpage-type-specific-checks.mdHard fails, warnings, schema rules, and pass thresholds per page typeStep 6, after seo-checks-reference.md

TEMPLATES/ and TEMPLATES_SOCIAL/#

FilePurposeWhen to Loadblog_post_template.mdHTML template for Blogpostwritehtml Blogpostlanding_page_template.mdHTML template for Landingpagewritehtml Landingpageproduct_new_template.mdHTML template for Productnewwritehtml Productnewproduct_used_template.mdHTML template for Productusedwritehtml Productusedfaq_page_template.mdHTML template for FAQwritehtml FAQphoto_post_template.mdSocial photo post templatewritehtml Socialphotovideo_post_template.mdSocial video metadata templatewritehtml Socialvideo

SEO_BRIEFS/ and SEO_PLANS/#

FilePurposeWhen to LoadSEO_BRIEFS/_index.mdRegistry of all generated briefsLoad on seobrief or --from-brief``SEO_PLANS/_index.mdRegistry of all generated plansLoad on seoplan or --plan``SEO_PLANS/plan_workflow.md``seoplan pipeline logic (Steps A–G)Load only on seoplan

---

Output Format#

write — Plain Text Output#

Returns clean, structured text content — no HTML tags.

Use this when you want to review content first, paste into a CMS editor, or use the text elsewhere (social caption, email, document).

text

write Blogpost "How to identify a genuine Leica M6"
→ Returns: Full blog post as readable text with headings, paragraphs, bullet lists
   No HTML tags. Ready to paste into WordPress, JTL Shop editor, Notion, etc.

writehtml — Pure HTML Output#

Returns a complete HTML document using the corresponding TEMPLATES/<type>.md template.

All {PLACEHOLDER} variables are replaced with real content. Zero placeholders in the output.

Use this when you want copy-paste ready code to deploy directly.

text

writehtml Productused "Leica M6 TTL, serial 2741xxx, condition A+"
→ Returns: Full HTML file with all placeholders replaced, schema included,
   Zone:AI and Zone:CTA sections marked, ready to deploy

After any output the agent will offer:

• "give me raw HTML only" → strip markdown wrapping, return pure code block
• "run checks" → re-run SEO audit on the generated output

---

write vs writehtml — When to Use Which#

SituationUseReviewing content before publishingwritePasting into a visual CMS editorwriteDeploying directly to a pagewritehtmlChecking HTML structure and schemawritehtmlSocial media captionswriteTesting a new templatewritehtml

---

Page Types Supported#

TypeDescriptionRecommended Word CountBlogpostOrganic SEO articles, guides, storytelling content1,500w+LandingpageSales campaigns, newsletter launches, promotions900–1,200wProductnewNew physical/digital products — tech specs focus400–600wProductusedRefurbished/second-hand items — condition reports500–700wFAQStandalone FAQ pages, PAA-targeting content with FAQPage schema800–1,200wSocialphotoVisual posts with alt text and captions100–200wSocialvideoYouTube/TikTok metadata, descriptions, transcripts150–300w

---

Search Intent Detection 🎯 CRITICAL — Runs Before Everything Else#

When it runs: Step 0 — BEFORE parsing the command, BEFORE loading any persona.

Purpose: Analyze the user prompt → determine search intent → auto-select the correct page format.

Wrong format = wrong ranking signal. A product description written for an informational query will not rank.

Full rules: See SEO_CHECKS/search_intent.md

Quick Reference#

Detected IntentTrigger WordsAuto-Selected FormatInformationalhow to, why, what is, guide, explainedBlogpostCommercial Investigationbest, vs, compare, review, topBlogpost (comparison)Transactionalbuy, price, in stock, order, purchaseProductnew or ProductusedNavigationalofficial site, login, [brand] + homepageLandingpage

• If the user specifies a page type explicitly → skip auto-selection, use their type
• If intent is ambiguous → ask one clarifying question before proceeding

---

Workflow Steps (Internal Brain) 🧠#

Full processing logic with all step details: see BRAIN_ARCHITECTURE.md All commands, types, and flags in full detail: see COMMANDS.md Page template index and structure overview: see PAGE_STRUCTURES.md Full SEO research and writing workflow: see SEO_PATH.md

text

Step 0    Search Intent Detection     Analyze prompt → auto-select page format (SEO_CHECKS/search_intent.md)
           SKIP for: seoplan, seobrief — strategy commands, no page format needed
Step 1    Parse Command               Extract persona, type, prompt, all flags
           --from-brief               If flag present → load SEO_BRIEFS/<id>.md at parse time
           --plan                     If flag present → load SEO_PLANS/<plan-id>.md node at parse time
Step 2a   Load Persona Index          PERSONAS/_index.md → find persona_id
Step 2b   Load Persona File           PERSONAS/<id>.md → style, tone, E-E-A-T rules
           seoplan + seobrief         Always load researcher.md internally (overrides session persona)
           Default fallback           If no `persona` command → load PERSONAS/blogger.md
           Tone override              If --tone flag present → override persona tone, keep everything else
Step 2c   Load Locale                 LOCALE/base.md + LOCALE/<lang>.md (if --lang flag present)
Step 2d   Load Brand Profile          If brand active or --brand flag: BRANDS/<id>.md → brand_vars{} + compliance{}
           Skip if                    No brand command and no --brand flag → no brand rules apply
Step 2e   SEO Plan Pipeline           If seoplan active: load SEO_PLANS/plan_workflow.md → run Steps A–G → STOP (Steps 3–7 do not run)
Step 2f   Load SEO Writing Rules      SEO_RULES/universal.md + SEO_RULES/<page_type>.md → seo_rules{}
           Skip if                    seoplan or seobrief active — no page content generated
Step 3    Generate Variables          Prompt + persona + brand + brief + plan node + seo_rules → full variable dictionary
Step 3.5  Zone Assignment Pass        Apply Zone A (neutral/factual) vs Zone B (CTA/sales) to each content section
Step 4    Select Template             Match page type → load TEMPLATES/<type>.md
           write skips Steps 4–5      Plain text output — no template loading
Step 5    Variable Substitution       Replace ALL {PLACEHOLDER} in template with real values
Step 6    SEO Checks                  Run SEO_CHECKS/seo-checks-reference.md (universal) → SEO_CHECKS/page-type-specific-checks.md (type rules)
           seoplan                    Runs plan quality check (Step F in SEO_PLANS/plan_workflow.md) instead
Step 6.5  Persona Compliance Check    Headings formula · depth · E-E-A-T signals · Zone A/B · zero placeholder leakage
           seoplan                    Skipped (no page content generated)
Step 6.6  Brand Compliance Check      If brand active: banned phrases · urgency limits · required disclosures
           HARD FAIL                  Blocks output until all violations resolved
           seoplan                    Brand persona defaults applied to node assignments only
Step 7    Output                      write → plain text | `writehtml` → pure HTML
           seoplan                    Structured plan saved to SEO_PLANS/
           seobrief                   Structured brief saved to SEO_BRIEFS/

Workflow Example — write (Plain Text)#

text

/persona creative-writer
/write Blogpost "Shooting film in Nürnberg with a Leica M6" --primary-kw "leica m6 film photography"

# Step 0: Informational intent detected → Blogpost confirmed
# Step 2: Loads PERSONAS/creative-writer.md
# Step 3: Generates variables using Story-Driven style + Heading Formula
# Step 3.5: Assigns Zone A to intro + body sections
# Step 4–5: Skipped (plain text output)
# Step 6–6.5: SEO checks + compliance pass
# Step 7: Returns readable blog post text — no HTML tags

Workflow Example — writehtml (HTML Output)#

text

persona ecommerce-manager
writehtml Productused "Leica M6 TTL Chrome, serial 2741xxx, EX+ condition" --primary-kw "leica m6 ttl kaufen"

# Step 0: Transactional intent → Productused confirmed
# Step 2: Loads PERSONAS/ecommerce-manager.md
# Step 3: Generates full variable dict (all {SPEC_*}, {SCHEMA_*}, {FAQ_*} etc.)
# Step 3.5: Zone A for spec/condition sections, Zone B for CTA/pricing blocks
# Step 4: Loads TEMPLATES/product_used_template.md
# Step 5: Replaces ALL {PLACEHOLDER} — zero placeholders in output
# Step 6–6.5: SEO checks + compliance pass
# Step 7: Returns complete HTML — ready to deploy

Workflow Example — seobrief → write (Brief-First Flow)#

text

# Step 1: Generate the brief
seobrief Blogpost "Leica M6 Analogfotografie Guide" --lang de --brand example-brand

# → Researcher persona loads internally (always)
# → Keyword cluster researched: primary KW auto-detected
# → 2-3 competitor URLs analysed for gaps
# → Brief saved: SEO_BRIEFS/<YEAR>/<MONTH>/leica-m6-analogfotografie-guide-de.md
# → Output: full structured brief with KW cluster, H1–H4 outline, PAA questions, internal link targets, and ready-to-run /write command

# Step 2: Write content from the brief
brand example-brand
persona blogger
write Blogpost "Leica M6 Guide" --from-brief leica-m6-analogfotografie-guide-de --lang de

# → Step 1: Loads brief → KWs, outline, PAA, internal links merged into parse
# → Step 2a-c: blogger persona + de locale
# → Step 2d: `example-brand` brand profile (CTAs, compliance) merged
# → Step 3: Variables generated using brief outline as H-tag structure
# → Steps 6, 6.5, 6.6: SEO + persona + brand compliance all pass
# → Step 7: Returns plain text article following the brief's approved structure

Workflow Example — seoplan → seobrief → write (Full Agency Flow)#

text

seoplan "Vintage analog cameras Germany" --lang de --brand example-brand

→ Step 2e: SEO_PLANS/plan_workflow.md loaded, researcher runs Steps A–G → Step A: Keyword families mapped, quick win threshold = difficulty < 22 → Steps B–C: 11 nodes built and tiered (1 PILLAR + 4 QW + 3 FND + 3 STR) → Step D: Internal link matrix generated — no orphan nodes → Step E: Execution order: qw-01 → qw-04 first, pillar-01 after, str-01–03 last → Step G: Saved as SEO_PLANS///vintage-analog-cameras-de.md

text

seobrief Blogpost "Film einlegen Anleitung" --plan vintage-analog-cameras-de.qw-01 --lang de

→ Step 1: Node qw-01 loaded from plan → primary_kw, page_type, links_to extracted → Research runs on top of plan data, brief saved: SEO_BRIEFS///film-einlegen-anleitung-de.md

text

brand example-brand
persona blogger
write Blogpost "Film einlegen" --from-brief film-einlegen-anleitung-de --lang de

→ Brief + plan node + brand all merged at Step 1 → Steps 6 / 6.5 / 6.6 pass → Step 7: plain text article ready to publish

---

Variable Substitution Engine 🧠#

When you provide a content prompt, the brain:

1. Extracts variables from your prompt automatically
2. Replaces all {PLACEHOLDER} text in the template with real content
3. Returns zero placeholders — all {VAR} text is gone before output

Full variable reference per page type: see BRAIN_ARCHITECTURE.md

Example — Variable Dictionary (Productused, Leica M6)#

python

{
  "TITLE":                              "Leica M6 TTL Chrome — Used, EX+ Condition | WebsiteName",
  "META_DESCRIPTION":                   "Buy a used Leica M6 TTL Chrome in EX+ condition. Serial 2741xxx, 2000–2001 production. Fully functional, CLA'd. 30-day return policy.",
  "URL_CANONICAL":                      "https://www.example.de/products/leica-m6-ttl-chrome-gebraucht",
  "H1_TITLE":                           "Leica M6 TTL Chrome (Type 10434) — EX+ Condition, Serial 2741xxx",
  "HERO_SUBHEADLINE_CONDITION_DISCLOSURE": "2000–2001 production · TTL flash metering · All functions verified",
  "CONDITION_LEVEL_USED":               "A+",
  "DISPLAY_PRICE_EUR_USED":             "€1,090",
  "SCHEMA_CONDITION":                   "https://schema.org/UsedCondition",
  "SCHEMA_SKU":                         "EXMAMPLE-2741",
  "FAQ_Q1":                             "What condition is this Leica M6 TTL in?",
  "FAQ_A1":                             "A+ — light use only. No brassing, viewfinder clear, shutter fires accurately at all speeds.",
  # ... all remaining variables
}

---

File Locations & Dependencies#

text

seo-owls-claw/
│
├── SKILL.md                    ← This file — core instructions + command reference
├── BRAIN_ARCHITECTURE.md       ← Complete processing logic (the full brain workflow)
├── COMMANDS.md                 ← Full command reference with all flags
├── PAGE_STRUCTURES.md          ← Master index + links to all page templates
├── SEO_PATH.md                 ← Full SEO workflow: research → analysis → writing → checks
│
├── PERSONAS/                   ← One file per persona
│   ├── _index.md               ← Load first — lists all persona IDs and file paths
│   ├── ecommerce-manager.md
│   ├── creative-writer.md
│   ├── blogger.md              ← Default persona when none specified
│   ├── researcher.md
│   ├── vintage-expert.md
│   └── travel-photographer.md
│
├── BRANDS/                     ← One file per client brand profile
│   ├── _index.md               ← Load first — lists all brand IDs and file paths
│   └── brand-template.md       ← Copy this to create a new brand profile
│
├── SEO_RULES/                  ← SEO writing rules, consulted before generation (Step 2f)
│   ├── _index.md               ← Registry of all rule files
│   ├── universal.md            ← Rules for every page type — always loaded
│   ├── landingpage.md
│   ├── blogpost.md
│   ├── productnew.md
│   ├── productused.md
│   ├── faq.md
│   ├── socialphoto.md
│   └── socialvideo.md
│
├── LOCALE/                     ← Language override files (Base + Delta architecture)
│   ├── base.md                 ← English defaults for all locale keys — always loaded
│   ├── de.md                   ← German overrides (--lang de)
│   ├── fr.md                   ← French overrides (--lang fr)
│   ├── es.md                   ← Spanish overrides (--lang es)
│   └── pt.md                   ← Portuguese overrides (--lang pt)
│
├── SEO_BRIEFS/                 ← Generated content briefs (one per topic/page)
│   └── _index.md               ← Registry: brief-id | topic | type | date | status
│
├── SEO_PLANS/                  ← One plan file per niche/site campaign
│   ├── _index.md               ← Registry: plan-id | niche | mode | lang | date
│   ├── plan-template.md        ← Format reference + example plan
│   └── plan_workflow.md        ← Full /seoplan pipeline logic (Steps A–G) — loaded only on /seoplan
│
├── SEO_CHECKS/                 ← SEO audit mechanics — scores content against SEO_RULES/
│   ├── search_intent.md        ← Step 0 rules — intent detection + format selection
│   ├── schema-markup.md        ← Schema.org rules + {SCHEMA_*} variable definitions
│   ├── seo-checks-reference.md ← Universal audit workflow, scores against SEO_RULES/universal.md
│   ├── page-type-specific-checks.md ← Per-type audit scoring, scores against SEO_RULES/<type>.md
│   └── seo-output-quality-checklist.md ← Pre-output quality gates
│
├── TEMPLATES/                  ← HTML output templates (used by `writehtml` only)
│   ├── blog_post_template.md
│   ├── landing_page_template.md
│   ├── product_new_template.md
│   ├── product_used_template.md
│   └── faq_page_template.md
│
├── TEMPLATES_SOCIAL/           ← Social media output templates
│   ├── photo_post_template.md
│   └── video_post_template.md
│
├── OUTPUT_EXAMPLES/            ← Reference output examples for agent guidance
│   ├── blog_post_example.html
│   ├── landing_page_example.html
│   ├── product_new_example.html
│   └── product_used_example.html
│
#└── DOC/                        ← Internal project docs (not required or loaded by agent)
#    ├── BUGS.md                 ← Internal project docs (not required or loaded by agent)
#    ├── CHANGELOG.md            ← Internal project docs (not required or loaded by agent)
#    └── PLANNING.md             ← Internal project docs (not required or loaded by agent)

---

Last updated: 24-08-2026 (v0.9.2)

Adds: Step 2f (SEO_RULES/ loaded before generation), SEO_RULES/ folder, trimmed SEO_CHECKS/ Maintainer: Chris — SEOwlsClaw core skill file