content-creator

Content Creator

Self-configuring content creation pipeline. Creates SEO & GEO-optimized content matched to your project and brand voice, then validates with geo-lint until clean.

For project-specific rules (components, file naming, categories), the skill generates a local content-config skill on first use via the setup workflow.

Command Router

Parse $ARGUMENTS and route to the matching workflow:

Argument	Workflow
setup	Auto-discover project, questionnaire, generate content-config
create [blog|page|project]	Full content creation pipeline
voice	Analyze and configure brand voice
calendar	Plan monthly content calendar
refresh	Re-scan project, update content-config
(no args)	If no config exists → auto-trigger setup. Otherwise show commands.

Pre-Flight Check

Before any workflow except setup:

1. Check if .claude/skills/content-config/SKILL.md exists in the project root.
2. If missing → inform the user: "No project content config found. Running setup first..." Then auto-trigger the setup workflow.
3. If found → read it into context and proceed with the requested workflow.

---

Workflow: setup

Three phases: auto-discover → questionnaire → generate.

Phase 1: Auto-Discovery

Run these steps silently, collecting results into a discovery report:

1. Framework Detection

• Read package.json dependencies and devDependencies for: next, astro, @astrojs/*, gatsby, hugo, nuxt, vite, remix, @11ty/eleventy
• Check for config files: next.config.*, astro.config.*, nuxt.config.*, gatsby-config.*, .eleventy.js
• Record: framework name + version

2. Content Directories

• Search for common patterns: content/, src/content/, posts/, blog/, pages/, articles/, src/pages/
• If geo-lint.config.ts exists → read its contentPaths
• Record: all content directories and file extensions (.md, .mdx, .astro, .html)

3. Frontmatter Schema

• Read 5–10 representative content files across detected directories
• Parse YAML frontmatter (lines between --- delimiters)
• Compute the union of all field names; classify each as required (present in >80% of files) or optional
• Record: field schema with types inferred from values

4. Categories

• Extract unique values from category and categories frontmatter fields across all content
• Cross-reference with geo-lint.config.ts categories array if present
• Record: canonical category list

5. Authors

• Extract unique author values from all content frontmatter
• Record: author names

6. Locales & i18n

• Detect from: frontmatter locale fields, file naming patterns (.de.mdx, .en.mdx), directory patterns (/de/, /en/)
• Check geo-lint.config.ts i18n config if present
• Record: locales and default locale

7. Site URL

• Check in order: geo-lint.config.ts siteUrl → package.json homepage → framework config site/url field
• Record: URL or "not found"

8. Image Directories

• Search for: public/images/, static/images/, assets/images/, src/assets/
• Record: directories found

9. Components (MDX projects only)

• If .mdx files exist → scan for JSX component usage patterns (<ComponentName)
• Exclude standard HTML tags
• Record: component names found

Phase 2: Questionnaire

Present the discovery summary as a formatted table. Then use AskUserQuestion to gather:

1. Confirm discoveries — "Here's what I found about your project: [table]. Is this correct? Any corrections?"
2. Brand voice archetype — Options from references/brand_guidelines.md: The Expert, The Friend, The Innovator, The Guide, The Motivator. Allow primary + secondary selection.
3. Tone attributes — Pick 3–5 from: Authoritative, Friendly, Innovative, Trustworthy, Inspiring, Educational, Witty
4. Target audience — Free text (e.g., "B2B decision-makers in manufacturing, CTOs")
5. Content goals — Free text (e.g., "thought leadership, lead generation, brand awareness")

Phase 3: Generation

1. Generate .claude/skills/content-config/SKILL.md in the project root using the Content-Config Template below. Fill all [placeholders] with discovered and questionnaire data.

2. geo-lint.config.ts — if it does not exist:

   • Generate it with discovered siteUrl, contentPaths, categories, and geo.brandName if known
   • Install @ijonis/geo-lint as a devDependency if not present

3. geo-lint.config.ts — if it exists but is missing discovered data:

   • Propose additions (new categories, new contentPaths) for user confirmation

4. Validation test — run npx geo-lint --format=json to confirm config loads correctly

5. Report: "Setup complete. Your content pipeline is ready. Run /content-creator create to start."

---

Workflow: create

Full content creation pipeline with built-in validation.

Step 1: Load Project Config

Read .claude/skills/content-config/SKILL.md for project-specific rules: content schema, brand voice, categories, components, file naming conventions, languages.

Step 2: Topic & Type

Ask the user for:

• Topic or title for the new content piece
• Content type — blog, page, or project (default: blog)

Step 3: Duplicate & Overlap Gate (MANDATORY)

Scan ALL existing content (titles, slugs, descriptions) before proceeding:

Finding	Action
Exact duplicate (same topic + angle)	Stop. Suggest updating the existing post instead.
Substantial overlap (same topic, different angle)	Stop. Propose a clearly differentiated angle. Get user approval before proceeding.
Tangential overlap (related topic, distinct focus)	Proceed. Note the related post for cross-linking.
No overlap	Proceed.

Report which existing posts were checked and the gate result.

Step 4: Keyword & Search Research (MANDATORY)

Use WebSearch to research the topic. Follow the purchase-intent-first strategy:

1. Search for trending angles, competitor coverage, and keyword variations
2. Identify: 1 primary keyword, 3–5 secondary keywords, 10–15 LSI keywords
3. Explicitly mine for purchase-intent keywords (e.g., +pricing/cost, +provider/agency, +comparison/vs/alternative; for German markets also +Kosten, +Anbieter, +Vergleich)
4. Run the SERP Viability Filter for the primary keyword:
   • Authority Check — are top results Wikipedia/Forbes (red flag) or mid-size blogs (green flag)?
   • Intent Check — are ranking results blog posts (match) or product pages (mismatch)?
   • Coverage Check — does the site already rank for this? (site:domain "[keyword]")
   • Long-Tail Check — does a long-tail variant have community demand?
5. Document: confirmed primary keyword with 2–3 sentence rationale, intent classification, differentiation angle

Step 5: Select Template

Load references/content_frameworks.md. Choose the best template for the topic:

• How-To Guide — prerequisites → steps → troubleshooting → results
• Listicle — introduction → items → action plan
• Case Study — challenge → solution → results → takeaways
• Thought Leadership — current state → trend → implications → recommendations

Step 6: Write Content

Follow the project schema from content-config:

• Use correct frontmatter fields (all required fields populated)
• Follow file naming conventions (locale suffixes if bilingual)
• Apply brand voice (archetypes, tone attributes, target audience)
• Use available MDX components where they enhance the content (if applicable)
• SEO targets: keyword density 1–3%, proper heading hierarchy (one H1, no skipped levels), 1,500–2,500 words for blog posts
• Add 2–3 internal links to related existing posts
• Add 1–2 external links to authoritative sources

Step 7: Validate (MANDATORY)

Run the geo-lint validation loop:

npx geo-lint --format=json --root=.

1. Filter violations to the newly created file
2. Fix ALL violations — errors first, then warnings
3. Re-run the linter after fixes
4. Repeat until zero violations for the new post
5. Maximum 5 fix passes — if violations remain after 5 passes, report which rules still fail and why

Rules that require human input (do NOT fix, report to user):

• geo-low-citation-density — requires real statistics; never fabricate
• image-not-found — image file must exist on disk
• broken-internal-link — target page may not exist
• category-invalid — must use configured categories

Step 8: Cross-Link

• Update 1–2 existing related posts with links to the new content
• Verify internal links resolve correctly

Step 9: Report

Summary: files created, content type, primary keyword, violations fixed, internal links added, any items requiring human attention.

---

Workflow: voice

Analyze and configure brand voice settings.

1. If Python is available → run the brand voice analyzer from the skill's install directory (~/.claude/skills/content-creator/scripts/brand_voice_analyzer.py) on 3–5 recent content files
2. Display current voice profile: formality spectrum, tone attributes, perspective, readability score
3. Compare against the configured voice in .claude/skills/content-config/SKILL.md
4. If adjustments needed → ask user via AskUserQuestion with archetype and tone options
5. Update .claude/skills/content-config/SKILL.md with new voice preferences

If Python is not available, analyze voice manually by reading content and assessing tone, formality, and perspective.

---

Workflow: calendar

Plan a monthly content calendar.

1. Load assets/content_calendar_template.md as the base template
2. Read existing content to identify: publishing cadence, topic gaps, category distribution, seasonal patterns
3. Use WebSearch to research trending topics in the project's domain and industry
4. Generate a monthly calendar with: topics, target keywords, content types, suggested templates, publishing dates
5. Follow the 40/25/25/10 content pillar ratio: Educational / Inspirational / Conversational / Promotional
6. Save to a location the user chooses (default: docs/content-calendar.md)

---

Workflow: refresh

Re-scan the project and update content-config.

1. Re-run all auto-discovery steps from the setup Phase 1
2. Read existing .claude/skills/content-config/SKILL.md
3. Compute diff: new categories, new authors, new components, new locales, new content types, changed directories
4. Present changes as a before/after comparison table
5. If user approves → update content-config, preserving user-customized sections (brand voice, audience, goals)
6. If geo-lint.config.ts also needs updates (new categories, new contentPaths) → propose those changes separately
7. Report what changed

---

Content-Config Template

The setup workflow generates .claude/skills/content-config/SKILL.md in the user's project. The agent fills [placeholders] with discovered and questionnaire data:

---
name: content-config
description: [ProjectName]-specific content creation rules. Defines content schemas,
  categories, brand voice, and geo-lint validation workflow. Generated by
  /content-creator setup — edit freely to refine.
---

# [ProjectName] Content Config

Generated by `/content-creator setup`. Extends the global `content-creator` skill
with project-specific rules. Edit this file to refine your content pipeline.

## Brand Identity

### Brand Voice
- **Archetypes:** [Primary] (primary) + [Secondary] (secondary)
- **Tone:** [3-5 chosen attributes, comma-separated]
- **Target Audience:** [from questionnaire]
- **Content Goals:** [from questionnaire]

### Authors
| Author | Focus Areas |
|--------|------------|
| [Name] | [inferred from existing content topics, or "General"] |

## Content Schema

### Framework
[Framework name] [version]

### Content Types
| Type | Directory | URL Prefix | Extensions |
|------|-----------|------------|------------|
| [type] | [dir] | [prefix] | [.mdx, .md] |

### Required Frontmatter
[List fields present in >80% of files, with inferred types]

### Optional Frontmatter
[List fields present in <80% of files]

### Canonical Categories
[Comma-separated list, or "None configured — add to geo-lint.config.ts"]

## File Naming
[Convention discovered — e.g., "kebab-case.mdx" or "slug.de.mdx / slug.en.mdx"]

## Languages
[Locales discovered + default locale, or "Single language"]

## Components
[MDX component names found, or "N/A — no MDX components detected"]

## Content Creation Workflow

1. **Duplicate check** — scan existing content for topic overlap before writing
2. **Keyword research** — use WebSearch, purchase-intent first
3. **Write** — follow schema above, apply brand voice, use components where appropriate
4. **Validate** — run `npx geo-lint --format=json`, filter to new file
5. **Fix all violations** — errors AND warnings, max 5 passes
6. **Cross-link** — add 2-3 internal links, update 1-2 existing posts

New content MUST ship with zero geo-lint violations.

## Validation Commands

npx geo-lint --format=json        # Full project lint (JSON output)
npx geo-lint --root=.             # Full project lint (human-readable)
npx geo-lint --rules              # Show all 92 rules with fix strategies

---

Reference Guides

Load these on demand — do not read them all into context at once:

Reference	When to load
references/brand_guidelines.md	During setup (voice selection) and voice workflow
references/content_frameworks.md	During create (template selection)
references/social_media_optimization.md	When creating social media content
assets/content_calendar_template.md	During calendar workflow
scripts/brand_voice_analyzer.py	During voice workflow (optional — requires Python)