firefrost-gaming/claude-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d740f77ef74494dea032333894e335f6332cb423
claude-skills-reference/marketing-skill/site-architecture/references/url-design-guide.md
Alireza Rezvani 52321c86bc feat: Marketing Division expansion — 7 → 42 skills (#266) 
* feat: Skill Authoring Standard + Marketing Expansion plans

SKILL-AUTHORING-STANDARD.md — the DNA of every skill in this repo:
10 universal patterns codified from C-Suite innovations + Corey Haines' marketingskills patterns:

1. Context-First: check domain context, ask only for gaps
2. Practitioner Voice: expert persona, goal-oriented, not textbook
3. Multi-Mode Workflows: build from scratch / optimize existing / situation-specific
4. Related Skills Navigation: when to use, when NOT to, bidirectional
5. Reference Separation: SKILL.md lean (≤10KB), refs deep
6. Proactive Triggers: surface issues without being asked
7. Output Artifacts: request → specific deliverable mapping
8. Quality Loop: self-verify, confidence tagging
9. Communication Standard: bottom line first, structured output
10. Python Tools: stdlib-only, CLI-first, JSON output, sample data

Marketing expansion plans for 40-skill marketing division build.

* feat: marketing foundation — context + ops router + authoring standard

marketing-context/: Foundation skill every marketing skill reads first
  - SKILL.md: 3 modes (auto-draft, guided interview, update)
  - templates/marketing-context-template.md: 14 sections covering
    product, audience, personas, pain points, competitive landscape,
    differentiation, objections, switching dynamics, customer language
    (verbatim), brand voice, style guide, proof points, SEO context, goals
  - scripts/context_validator.py: Scores completeness 0-100, section-by-section

marketing-ops/: Central router for 40-skill marketing ecosystem
  - Full routing matrix: 7 pods + cross-domain routing to 6 skills in
    business-growth, product-team, engineering-team, c-level-advisor
  - Campaign orchestration sequences (launch, content, CRO sprint)
  - Quality gate matching C-Suite standard
  - scripts/campaign_tracker.py: Campaign status tracking with progress,
    overdue detection, pod coverage, blocker identification

SKILL-AUTHORING-STANDARD.md: Universal DNA for all skills
  - 10 patterns: context-first, practitioner voice, multi-mode workflows,
    related skills navigation, reference separation, proactive triggers,
    output artifacts, quality loop, communication standard, python tools
  - Quality checklist for skill completion verification
  - Domain context file mapping for all 5 domains

* feat: import 20 workspace marketing skills + standard sections

Imported 20 marketing skills from OpenClaw workspace into repo:

Content Pod (5):
  content-strategy, copywriting, copy-editing, social-content, marketing-ideas

SEO Pod (2):
  seo-audit (+ references enriched by subagent), programmatic-seo (+ refs)

CRO Pod (5):
  page-cro, form-cro, signup-flow-cro, onboarding-cro, popup-cro, paywall-upgrade-cro

Channels Pod (2):
  email-sequence, paid-ads

Growth + Intel + GTM (5):
  ab-test-setup, competitor-alternatives, marketing-psychology, launch-strategy, brand-guidelines

All 29 skills now have standard sections per SKILL-AUTHORING-STANDARD.md:
  ✅ Proactive Triggers (4-5 per skill)
  ✅ Output Artifacts table
  ✅ Communication standard reference
  ✅ Related Skills with WHEN/NOT disambiguation

Subagents enriched 8 skills with additional reference docs:
  seo-audit, programmatic-seo, page-cro, form-cro,
  onboarding-cro, popup-cro, paywall-upgrade-cro, email-sequence

43 files, 10,566 lines added.

* feat: build 13 new marketing skills + social-media-manager upgrade

All skills are 100% original work — inspired by industry best practices,
written from scratch in our own voice following SKILL-AUTHORING-STANDARD.md.

NEW Content Pod (2):
  content-production — full research→draft→optimize pipeline, content_scorer.py
  content-humanizer — AI pattern detection + voice injection, humanizer_scorer.py

NEW SEO Pod (3):
  ai-seo — AI search optimization (AEO/GEO/LLMO), entirely new category
  schema-markup — JSON-LD structured data, schema_validator.py
  site-architecture — URL structure + internal linking, sitemap_analyzer.py

NEW Channels Pod (2):
  cold-email — B2B outreach (distinct from email-sequence lifecycle)
  ad-creative — bulk ad generation + platform specs, ad_copy_validator.py

NEW Growth Pod (3):
  churn-prevention — cancel flows + save offers + dunning, churn_impact_calculator.py
  referral-program — referral + affiliate programs
  free-tool-strategy — engineering as marketing

NEW Intelligence Pod (1):
  analytics-tracking — GA4/GTM setup + event taxonomy, tracking_plan_generator.py

NEW Sales Pod (1):
  pricing-strategy — pricing, packaging, monetization

UPGRADED:
  social-media-analyzer → social-media-manager (strategy, calendar, community)

Totals: 42 skills, 27 Python scripts, 60 reference docs, 163 files, 43,265 lines

* feat: update index, marketplace, README for 42 marketing skills

- skills-index.json: 89 → 124 skills (42 marketing entries)
- marketplace.json: marketing-skills v2.0.0 (42 skills, 27 tools)
- README.md: badge 134 → 169, marketing row updated
- prompt-engineer-toolkit: added YAML frontmatter
- Removed build logs from repo
- Parity check: 42/42 passed (YAML + Related + Proactive + Output + Communication)

* fix: merge content-creator into content-production, split marketing-psychology

Quality audit fixes:

1. content-creator → DEPRECATED redirect
   - Scripts (brand_voice_analyzer.py, seo_optimizer.py) moved to content-production
   - SKILL.md replaced with redirect to content-production + content-strategy
   - Eliminates duplicate routing confusion

2. marketing-psychology → 24KB split to 6.8KB + reference
   - 70+ mental models moved to references/mental-models-catalog.md (397 lines)
   - SKILL.md now lean: categories overview, most-used models, quick reference
   - Saves ~4,300 tokens per invocation

* feat: add plugin configs, Codex/OpenClaw compatibility, ClawHub packaging

- marketing-skill/SKILL.md: ClawHub-compatible root with Quick Start for Claude Code, Codex CLI, OpenClaw
- marketing-skill/CLAUDE.md: Agent instructions (routing, context, anti-patterns)
- marketing-skill/.codex/instructions.md: Codex CLI skill routing
- .claude-plugin/marketplace.json: deduplicated, marketing-skills v2.0.0
- .codex/skills-index.json: content-creator marked deprecated, psychology updated
- Total: 42 skills, 27 Python tools, 60 references, 18 plugins

* feat: add 16 Python tools to knowledge-only skills

Enriched 12 previously tool-less skills with practical Python scripts:
- seo-audit/seo_checker.py — HTML on-page SEO analysis (0-100)
- copywriting/headline_scorer.py — headline quality scoring (0-100)
- copy-editing/readability_scorer.py — Flesch + passive + filler detection
- content-strategy/topic_cluster_mapper.py — keyword clustering
- page-cro/conversion_audit.py — HTML CRO signal analysis (0-100)
- paid-ads/roas_calculator.py — ROAS/CPA/CPL calculator
- email-sequence/sequence_analyzer.py — email sequence scoring (0-100)
- form-cro/form_field_analyzer.py — form field CRO audit (0-100)
- onboarding-cro/activation_funnel_analyzer.py — funnel drop-off analysis
- programmatic-seo/url_pattern_generator.py — URL pattern planning
- ab-test-setup/sample_size_calculator.py — statistical sample sizing
- signup-flow-cro/funnel_drop_analyzer.py — signup funnel analysis
- launch-strategy/launch_readiness_scorer.py — launch checklist scoring
- competitor-alternatives/comparison_matrix_builder.py — feature comparison
- social-media-manager/social_calendar_generator.py — content calendar
- readability_scorer.py — fixed demo mode for non-TTY execution

All 43/43 scripts pass execution. All stdlib-only, zero pip installs.
Total: 42 skills, 43 Python tools, 60+ reference docs.

* feat: add 3 more Python tools + improve 6 existing scripts

New tools from build agent:
- email-sequence/scripts/sequence_analyzer.py — email sequence scoring (91/100 demo)
- paid-ads/scripts/roas_calculator.py — ROAS/CPA/CPL/break-even calculator
- competitor-alternatives/scripts/comparison_matrix_builder.py — feature matrix

Improved scripts (better demo modes, fuller analysis):
- seo_checker.py, headline_scorer.py, readability_scorer.py,
  conversion_audit.py, topic_cluster_mapper.py, launch_readiness_scorer.py

Total: 42 skills, 47 Python tools, all passing.

* fix: remove duplicate scripts from deprecated content-creator

Scripts already live in content-production/scripts/. The content-creator
directory is now a pure redirect (SKILL.md only + legacy assets/refs).

* fix: scope VirusTotal scan to executable files only

Skip scanning .md, .py, .json, .yml — they're plain text files
that VirusTotal can't meaningfully analyze. This prevents 429 rate
limit errors on PRs with many text file changes (like 42 marketing skills).

Scan still covers: .js, .ts, .sh, .mjs, .cjs, .exe, .dll, .so, .bin, .wasm

---------

Co-authored-by: Leo <leo@openclaw.ai>
2026-03-06 03:56:16 +01:00

221 lines
8.3 KiB
Markdown
Raw Blame History

# URL Design Guide
URL structure by site type — with examples of what good and bad looks like in practice.
---
## Universal URL Rules
Before the site-specific patterns, these apply everywhere:
1. **Lowercase always** — `/Blog/SEO-Tips` and `/blog/seo-tips` are different URLs. Always lowercase.
2. **Hyphens, not underscores** — Google treats hyphens as word separators. Underscores join words. `/seo-tips` not `/seo_tips`.
3. **No special characters** — No `%`, `&`, `#`, `?` in the path itself.
4. **No trailing slash inconsistency** — Pick a convention (`/page` or `/page/`) and enforce it sitewide with redirects.
5. **No dates in URLs unless required** — `/blog/2024/03/seo-tips` ages poorly. `/blog/seo-tips` is evergreen.
6. **Stop words are usually fine** — `/how-to-write-cold-emails` is readable and fine. Don't obsessively remove "how", "to", "a", "the" unless the URL is very long.
7. **Keep them short** — Under 75 characters is a good target. Shorter is usually better.
---
## SaaS / B2B Software
### Recommended Structure
```
/ (homepage)
/features
/features/[feature-name] e.g. /features/email-automation
/pricing
/solutions/[use-case] e.g. /solutions/sales-teams
/solutions/[industry] e.g. /solutions/healthcare
/integrations
/integrations/[tool-name] e.g. /integrations/salesforce
/blog
/blog/[post-slug] e.g. /blog/cold-email-templates
/customers
/customers/[customer-name] e.g. /customers/acme-corp
/about
/changelog
/docs (or subdomain: docs.example.com)
/docs/[topic]/[subtopic]
```
### What Works and What Doesn't
| ✅ Do | ❌ Don't |
|-------|----------|
| `/pricing` | `/pricing-plans` (redundant) |
| `/features/email-automation` | `/product/features/email-automation/detail` (too deep) |
| `/blog/cold-email-guide` | `/blog/articles/cold-email/complete-guide-to-cold-email` (too long) |
| `/solutions/sales-teams` | `/solutions-for-sales-teams` (ugly) |
| `/integrations/hubspot` | `/connect-with/hubspot-integration` |
### SaaS-Specific Notes
- `/features/` pages should actually be rankable landing pages, not just nav items.
- `/solutions/` by use case captures bottom-funnel searches ("sales team email tool").
- `/integrations/[tool]` pages are high-intent SEO goldmines — build a real page for each.
- Blog posts should live at `/blog/[slug]` — not `/resources/`, not `/learn/`, not `/content/`. Pick one.
- Changelog belongs at `/changelog` — some companies put it at `/releases` or `/updates`. Fine, just pick one.
---
## Blog / Content Site
### Recommended Structure
```
/ (homepage)
/[category] e.g. /seo, /email-marketing, /content
/[category]/[post-slug] e.g. /seo/technical-seo-audit-checklist
/guides (optional hub for long-form guides)
/guides/[guide-slug] e.g. /guides/cold-email-complete-guide
/tools (optional if you have free tools)
/tools/[tool-name]
/author/[author-slug]
/tag/[tag-name] (often better to noindex tags)
```
### What Works and What Doesn't
| ✅ Do | ❌ Don't |
|-------|----------|
| `/seo/keyword-research-guide` | `/seo/keyword-research/a-complete-guide-to-keyword-research-for-beginners-in-2024` |
| `/guides/cold-email` | `/blog/2024/03/15/cold-email-guide` |
| `/author/reza-rezvani` | `/author?id=42` |
| Flat category → post structure | 4-level nesting |
### Blog-Specific Notes
- Date-based URLs (`/2024/03/15/slug`) age poorly and look stale. Avoid.
- Tag pages create duplicate/thin content at scale. Either noindex them or give them real content.
- If you have <500 posts, flat `/post-slug` is fine. If you have >500, category buckets help organization.
- Author pages are worth building as real pages — they help E-E-A-T signals.
---
## E-Commerce
### Recommended Structure
```
/ (homepage)
/collections (or /shop, /catalog)
/collections/[category] e.g. /collections/mens-shoes
/collections/[category]/[subcategory] e.g. /collections/mens-shoes/running
/products/[product-slug] e.g. /products/air-max-270-black
/brands/[brand-name]
/sale
/new-arrivals
/blog
/blog/[post-slug]
```
### What Works and What Doesn't
| ✅ Do | ❌ Don't |
|-------|----------|
| `/products/air-max-270-black` | `/products?id=89472&color=black&size=10` |
| `/collections/mens-shoes` | `/products/shoes/men/athletic/running/all-styles` |
| Canonical on variant pages | Let `?color=red&size=10` create duplicate URLs |
### E-Commerce-Specific Notes
- Product variant pages (size, color) are the biggest duplicate content risk in e-commerce. Use canonical tags pointing to the base product URL, or use URL parameters and configure them in GSC.
- Filter and sort pages (`?sort=price-asc&brand=nike`) should either be canonicalized or blocked.
- Collection/category pages need real content to rank — not just a product grid.
- Discontinued products: don't just delete them. 301 to closest alternative or return 410 with a helpful message.
---
## Local Business / Service Area
### Recommended Structure (Single Location)
```
/ (homepage)
/services
/services/[service-name] e.g. /services/plumbing-repair
/about
/contact
/blog
/blog/[post-slug]
/areas-served (optional hub for service area pages)
/areas-served/[city-name] e.g. /areas-served/brooklyn
```
### Recommended Structure (Multi-Location)
```
/ (homepage)
/locations
/locations/[city] e.g. /locations/new-york
/locations/[city]/[service] e.g. /locations/new-york/plumbing
/services/[service-name] (generic service pages)
```
### Local-Specific Notes
- City/location pages must have unique, locally relevant content — not just "Find our [service] in [city]" copy-pasted 47 times.
- `/areas-served/brooklyn` should have real information about serving Brooklyn, not a thin page.
- Multi-location sites: `/locations/[city]` works better than subdomain per city for smaller operations. Subdomains make sense for truly independent franchises.
---
## URL Redirect Mapping (When Restructuring)
If you're changing URLs, you need a 301 redirect map. Every old URL → new URL. No exceptions.
**Redirect mapping process:**
1. Export all indexed URLs from Google Search Console (Crawl → Coverage → All)
2. Export all inbound links to your site (use Ahrefs, Semrush, or GSC)
3. Map old → new for every URL that has inbound links or search traffic
4. Implement 301 redirects server-side (not JS redirects, not meta refresh)
5. Monitor in GSC for 404 errors after migration
6. Update internal links — don't just redirect, fix the source links
**Priority redirect tiers:**
- **Tier 1:** Pages with significant inbound external links — redirect these first
- **Tier 2:** Pages with significant organic traffic — redirect to preserve equity
- **Tier 3:** Pages with neither — still redirect, but lower urgency
**Never:**
- Chain redirects more than 1 hop (`/old` → `/temp` → `/new` wastes equity)
- 302 redirect something that's a permanent move (use 301)
- Leave old URLs live as duplicates without canonicals
---
## Canonicalization
When the same content is accessible at multiple URLs, tell Google which one is canonical.
```html
<link rel="canonical" href="https://example.com/the-canonical-url" />
```
Common scenarios requiring canonicals:
- `http://` vs `https://` — canonical should always be `https://`
- `www` vs non-www — pick one, canonical + 301 the other
- Trailing slash vs no trailing slash — `/page` and `/page/` are different URLs to Google
- Filtered/sorted product pages — canonical to base product/collection URL
- Paginated pages — canonical the first page (or use `rel=next`/`rel=prev`)
- Printer-friendly versions — canonical to main page
- Syndicated content — canonical to original source
---
## HTTP Status Code Reference
| Code | Meaning | Use |
|------|---------|-----|
| 200 | OK | Normal page |
| 301 | Moved Permanently | URL changed permanently — passes equity |
| 302 | Found (Temporary) | Temporary redirect — does NOT pass equity |
| 404 | Not Found | Page doesn't exist — configure a helpful 404 page |
| 410 | Gone | Page intentionally removed — Google deindexes faster than 404 |
| 503 | Service Unavailable | Maintenance mode — tell Google to come back later |
Use 301, not 302, for all permanent URL changes.
Reference in New Issue View Git Blame Copy Permalink