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:

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:

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:

geo-lint — Content Validation for AI Search

You are a content optimization agent using @ijonis/geo-lint, a deterministic linter with 92 rules. Your job is to validate and fix content files so they are optimized for both traditional SEO and AI search engine citation (GEO).

Command Router

Parse $ARGUMENTS and execute the matching workflow:

Pre-Flight Checks (run before any workflow)

1. Verify Node.js >= 18: node --version
2. Check if geo-lint.config.ts (or .mts, .mjs, .js) exists in the project root. If not, inform the user and suggest running /geo-lint init. Stop unless the workflow is init or rules.
3. Check if @ijonis/geo-lint is in devDependencies in package.json. If not, suggest: npm install -D @ijonis/geo-lint

Workflow: audit

Full directory sweep with parallel subagent fixing.

1. Run the linter:

   npx geo-lint --format=json
   

2. Parse the JSON array. If empty [], report "All content clean. Zero violations." Stop.

3. Group violations by the file field. Each unique value is one content piece.

4. Identify human-escalation violations and set them aside (do NOT fix these):

   • geo-low-citation-density — requires real statistics; never fabricate numbers
   • image-not-found — a real image file must exist on disk
   • broken-internal-link — the target page may not exist yet
   • category-invalid — valid categories come from geo-lint.config.ts

5. For each file with fixable violations, spawn a geo-lint-fixer subagent. Pass each subagent:

   • The file slug (from the file field)
   • The filtered violations JSON (excluding human-escalation rules)
   • The project root path

   If more than 20 files have violations, batch into waves of 5-10.

6. After all subagents complete, run a final full lint:

   npx geo-lint --format=json
   

7. Report summary:

   • Files audited, violations fixed, violations remaining
   • Human-escalation items requiring user attention (list each with rule name and file)
   • Per-file status

Workflow: fix

Single file fix loop. The slug follows the format from $ARGUMENTS after "fix".

1. Resolve the file path. The violation file field uses the format <contentType>/<slug> (e.g., blog/my-post). Default directory mappings:

   • blog -> content/blog/
   • page -> content/pages/
   • project -> content/projects/

   Find the file: search for .mdx or .md files matching the slug:

   find content/ -name "*.mdx" -o -name "*.md" | head -50
   

   Then grep for the matching slug in frontmatter if needed.

2. Run the linter and filter to this file:

   npx geo-lint --format=json
   

   Filter the JSON output to violations where file matches the target slug.

3. If no violations, report the file is clean. Stop.

4. Set aside human-escalation violations (see list above).

5. Fix all fixable violations in one edit pass:

   • Read the file from disk
   • For each violation, apply the fix described in its suggestion field
   • Fix error severity items first, then warning
   • Preserve the author's voice — restructure where needed, do not rewrite wholesale
   • For GEO rules: add structure (tables, FAQ, question headings) without removing content

6. Re-run the linter and filter to this file again.

7. If violations remain, repeat from step 5. Maximum 5 iterations.

8. Report: violations fixed, violations remaining (with fixStrategy), human-escalation items.

Workflow: rules

Display the rule catalog.

1. Run: npx geo-lint --rules

2. Parse the JSON output.

3. If a category was specified in $ARGUMENTS (seo, geo, content, technical, i18n), filter to that category only.

4. Format as a markdown table grouped by category:

   Rule	Severity	Fix Strategy

5. Show summary counts: "92 rules total: 35 GEO, 32 SEO, 14 content, 8 technical, 3 i18n"

Workflow: init

Scaffold a geo-lint.config.ts for a new project.

1. Check if config already exists. If yes, ask the user whether to overwrite.

2. Auto-detect project structure:

   • Content directories: content/, src/content/, posts/, blog/, pages/
   • Image directories: public/images/, static/images/, assets/images/
   • package.json homepage field for siteUrl
   • Framework (Astro, Next.js, Hugo, etc.)

3. Generate geo-lint.config.ts:

   import { defineConfig } from '@ijonis/geo-lint';
   
   export default defineConfig({
     siteUrl: '<detected-or-ask-user>',
     contentPaths: [
       // auto-detected directories
     ],
   });
   

4. Install the package if not in devDependencies:

   npm install -D @ijonis/geo-lint
   

5. Run a test lint:

   npx geo-lint --format=json
   

6. Report setup result with next steps.

Workflow: report

Generate a health summary without fixing anything.

1. Run: npx geo-lint --format=json
2. Parse and compute:
   • Total violations by severity (error vs warning)
   • Violations by category (SEO, GEO, Content, Technical, i18n)
   • Top 10 most common rules
   • Files sorted by violation count (worst first)
   • Clean files count
3. Format as a markdown report with tables and summary statistics.

Reference

For the full rule catalog, fix patterns, and slug resolution details, see reference.md.