Self-Improving Marketing Skill#

Log marketing-specific learnings, campaign issues, and feature requests to markdown files for continuous improvement. Captures messaging misses, channel underperformance, audience drift, brand inconsistency, attribution gaps, and content decay. Important learnings get promoted to brand guidelines, content calendars, channel playbooks, audience personas, or attribution models.

First-Use Initialisation#

Before logging anything, ensure the .learnings/ directory and files exist in the project or workspace root. If any are missing, create them:

bash

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Marketing Learnings\n\nMessaging misses, audience drift, brand inconsistency, content decay, and channel insights captured during marketing operations.\n\n**Categories**: messaging_miss | channel_underperformance | audience_drift | brand_inconsistency | attribution_gap | content_decay\n**Areas**: content | campaigns | seo | social | email | paid_media | analytics\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/CAMPAIGN_ISSUES.md ] || printf "# Campaign Issues Log\n\nCampaign failures, channel problems, messaging errors, and performance issues.\n\n---\n" > .learnings/CAMPAIGN_ISSUES.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nMarketing tools, automation capabilities, and analytics improvements.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

Never overwrite existing files. This is a no-op if .learnings/ is already initialised.

Do not log customer PII, API keys, ad account credentials, or internal revenue figures. Prefer aggregated metrics and redacted campaign identifiers over raw customer data.

If you want automatic reminders, use the opt-in hook workflow described in Hook Integration.

Quick Reference#

SituationActionCTR drops >20% from baselineLog to .learnings/CAMPAIGN_ISSUES.md with performance detailsConversion rate declines >15%Log to .learnings/CAMPAIGN_ISSUES.md with funnel analysisBrand guideline violation foundLog to .learnings/LEARNINGS.md with category brand_inconsistencyOrganic traffic falls >25%Log to .learnings/LEARNINGS.md with category content_decayEmail bounce rate spikes >5%Log to .learnings/CAMPAIGN_ISSUES.md with deliverability detailsUTM attribution breaksLog to .learnings/LEARNINGS.md with category attribution_gapMessaging misses target segmentLog to .learnings/LEARNINGS.md with category messaging_missChannel underperforms benchmarkLog to .learnings/LEARNINGS.md with category channel_underperformanceAudience persona no longer fitsLog to .learnings/LEARNINGS.md with category audience_driftSocial engagement declinesLog to .learnings/CAMPAIGN_ISSUES.md with engagement metricsRecurring campaign patternLink with **See Also**, consider priority bumpBroadly applicable insightPromote to brand guidelines, playbook, or persona doc

OpenClaw Setup (Recommended)#

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

Installation#

Via ClawdHub (recommended):

bash

clawdhub install self-improving-marketing

Manual:

bash

git clone https://github.com/jose-compu/self-improving-marketing.git ~/.openclaw/skills/self-improving-marketing

Manual clone is optional. Check out a reviewed tag or commit before use. Do not install an unpinned default branch into a shared environment.

Workspace Structure#

OpenClaw injects these files into every session:

text

~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── CAMPAIGN_ISSUES.md
    └── FEATURE_REQUESTS.md

Create Learning Files#

bash

mkdir -p ~/.openclaw/workspace/.learnings

Then create the log files (or copy from assets/):

• LEARNINGS.md — messaging misses, audience drift, brand inconsistency, content decay, attribution gaps
• CAMPAIGN_ISSUES.md — campaign failures, channel problems, deliverability issues, performance drops
• FEATURE_REQUESTS.md — marketing tools, automation, analytics capabilities

Promotion Targets#

When marketing learnings prove broadly applicable, promote them:

Learning TypePromote ToExampleMessaging patternsBrand guidelines"Enterprise segment requires ROI-first messaging, not feature lists"Channel insightsChannel playbooks"LinkedIn carousel ads outperform single-image by 3x for B2B"Audience shiftsAudience personas"ICP shifted from SMB founders to mid-market VPs of Engineering"Content patternsContent calendar"Publish comparison posts after competitor launches"Attribution fixesAttribution model"Always use server-side UTM capture for redirect chains"Email patternsTOOLS.md"Warm new sending domains for 14 days minimum"

Optional: Enable Hook#

Opt-in and workspace-local. Do not copy this hook to ~/.openclaw/hooks/ (that path is user-global). Skip it unless you want reminders in this workspace:

bash

mkdir -p .openclaw/hooks
cp -r hooks/openclaw .openclaw/hooks/self-improving-marketing

See references/openclaw-integration.md for complete details.

---

Generic Setup (Other Agents)#

For Claude Code, Codex, Copilot, or other agents, create .learnings/ in the project or workspace root:

bash

mkdir -p .learnings

Create the files inline using the headers shown above.

Add reference to agent files#

Add to AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md:

Self-Improving Marketing Workflow

When marketing issues or insights are discovered:

1. Log to .learnings/CAMPAIGN_ISSUES.md, LEARNINGS.md, or FEATURE_REQUESTS.md
2. Review and promote broadly applicable learnings to:
   • Brand guidelines — messaging tone, positioning, and identity rules
   • Channel playbooks — per-channel strategy and benchmarks
   • Audience personas — updated ICP definitions and segment profiles
   • Content calendars — content type cadence and topic frameworks
   • Attribution models — tagging standards and measurement methodology

Logging Format#

Learning Entry [LRN-YYYYMMDD-XXX]#

Append to .learnings/LEARNINGS.md:

markdown

## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: content | campaigns | seo | social | email | paid_media | analytics

### Summary
One-line description of the marketing insight

### Details
Full context: what happened in the campaign or channel, why the expected outcome
differed from actual, what the correct approach or messaging strategy should be.
Include relevant metrics (CTR, CVR, CPL, ROAS) with before/after comparison.

### Evidence

**Metrics before:**
- CTR: X.X%
- Conversion rate: X.X%
- CPL: $XX.XX

**Metrics after (or expected):**
- CTR: X.X%
- Conversion rate: X.X%
- CPL: $XX.XX

### Suggested Action
Specific campaign adjustment, messaging change, targeting update, or process improvement

### Metadata
- Source: analytics_dashboard | a_b_test | campaign_report | brand_audit | customer_feedback | attribution_tool
- Channel: google_ads | meta_ads | linkedin | email | organic_search | social | direct
- Segment: enterprise | mid_market | smb | consumer | all
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: messaging_miss.wrong_value_prop | audience_drift.icp_shift (optional)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---

Categories for learnings:

CategoryUse Whenmessaging_missValue proposition, copy, or positioning failed to resonate with target segmentchannel_underperformanceChannel metrics (CTR, CPL, ROAS) fall significantly below benchmarksaudience_driftTarget audience behavior, demographics, or needs have shiftedbrand_inconsistencyMessaging, visual identity, or tone deviates from brand guidelinesattribution_gapTracking breaks, UTM parameters lost, conversion path unclearcontent_decayPreviously high-performing content loses traffic or engagement over time

Campaign Issue Entry [CMP-YYYYMMDD-XXX]#

Append to .learnings/CAMPAIGN_ISSUES.md:

markdown

## [CMP-YYYYMMDD-XXX] issue_description

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: content | campaigns | seo | social | email | paid_media | analytics

### Summary
Brief description of the campaign problem

### Performance Data
- Campaign: campaign name or ID (redacted if needed)
- Channel: google_ads | meta_ads | linkedin | email | organic_search
- Date Range: YYYY-MM-DD to YYYY-MM-DD
- Budget Spent: $X,XXX
- Key Metrics:
  - Impressions: XX,XXX
  - Clicks: X,XXX
  - CTR: X.X% (benchmark: X.X%)
  - Conversions: XXX
  - CVR: X.X% (benchmark: X.X%)
  - CPL: $XX.XX (benchmark: $XX.XX)
  - ROAS: X.Xx (benchmark: X.Xx)

### Root Cause
What in the campaign setup, targeting, creative, or messaging caused the issue.

### Fix Applied
What changes were made to address the problem.

### Prevention
How to avoid this issue in future campaigns (checklist item, review step, automation)

### Context
- Trigger: performance_alert | manual_review | a_b_test | customer_complaint | deliverability_report
- Campaign Type: lead_gen | brand_awareness | retargeting | nurture | product_launch | event_promotion
- Audience: target segment description

### Metadata
- Reproducible: yes | no | unknown
- Related Campaigns: campaign-name-or-id
- See Also: CMP-20250110-001 (if recurring)

---

Feature Request Entry [FEAT-YYYYMMDD-XXX]#

Append to .learnings/FEATURE_REQUESTS.md:

markdown

## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: content | campaigns | seo | social | email | paid_media | analytics

### Requested Capability
What marketing tool, automation, or analytics capability is needed

### User Context
Why it's needed, what workflow it improves, what manual process it replaces

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built: dashboard widget, automation rule, integration, report template, alert system

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_tool_or_feature

---

ID Generation#

Format: TYPE-YYYYMMDD-XXX

• TYPE: LRN (learning), CMP (campaign issue), FEAT (feature request)
• YYYYMMDD: Current date
• XXX: Sequential number or random 3 chars (e.g., 001, A7B)

Examples: LRN-20250415-001, CMP-20250415-A3F, FEAT-20250415-002

Resolving Entries#

When an issue is fixed, update the entry:

1. Change **Status**: pending → **Status**: resolved
2. Add resolution block after Metadata:

markdown

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Campaign/Initiative**: Q1 Product Launch v2
- **Notes**: Updated messaging to lead with ROI data instead of feature list

Other status values:

• in_progress — Actively being optimized or fixed
• wont_fix — Decided not to address (add reason in Resolution notes)
• promoted — Elevated to brand guidelines, playbook, or persona doc
• promoted_to_skill — Extracted as a reusable skill

Detection Triggers#

Automatically log when you encounter:

CTR / Click Performance (→ campaign issue or learning):

• CTR drops >20% from previous period or campaign benchmark
• Email open rate decline >15% week-over-week
• Landing page bounce rate exceeds 70%

Conversion Performance (→ campaign issue with performance data):

• Conversion rate declines >15% from baseline
• CPL exceeds benchmark by >50%
• ROAS drops below break-even threshold
• Funnel drop-off spikes at a specific stage

Email Deliverability (→ campaign issue with deliverability trigger):

• Bounce rate exceeds 5% (hard bounces)
• Spam complaint rate exceeds 0.1%
• Domain reputation score drops
• Unsubscribe rate spikes >2x normal

Organic / SEO (→ learning with content_decay or campaign issue):

• Organic traffic drops >25% month-over-month
• Top-ranking page loses position by 5+ spots
• Core Web Vitals fail threshold
• Featured snippet lost to competitor

Social / Engagement (→ learning with channel_underperformance):

• Engagement rate drops >30% from average
• Follower growth stalls or turns negative
• Comment sentiment shifts negative

Brand / Messaging (→ learning with brand_inconsistency or messaging_miss):

• Brand sentiment shifts negative in monitoring tools
• Customer feedback mentions confusion about positioning
• Internal teams use inconsistent value propositions

Attribution / Tracking (→ learning with attribution_gap):

• UTM parameters missing or malformed on campaign URLs
• Redirect chains strip tracking parameters
• Cross-domain tracking breaks between properties
• Multi-touch attribution model shows >30% unattributed conversions

Priority Guidelines#

PriorityWhen to UseMarketing ExamplescriticalBrand crisis, major campaign failure with significant budget waste, data breach affecting customersPR crisis from messaging mistake, $50K+ budget spent on broken tracking, sending PII in email blasthighSignificant CTR/conversion drops, deliverability issues affecting large audience, attribution fully brokenCPL 3x above benchmark for >1 week, bounce rate >10%, all UTMs stripped by new redirectmediumChannel underperformance, content decay, gradual audience drift, minor brand inconsistencyBlog post lost 40% traffic after update, LinkedIn ads below median CTR, persona needs refreshlowMinor copy improvements, process optimization, small tracking gaps, cosmetic brand issuesSubject line A/B test insight, minor UTM naming inconsistency, social post timing optimization

Area Tags#

Use to filter learnings by marketing domain:

AreaScopecontentBlog posts, landing pages, whitepapers, case studies, video content, webinarscampaignsCampaign strategy, multi-channel orchestration, launch planning, promotionsseoOrganic search, keyword strategy, technical SEO, content optimization, link buildingsocialSocial media strategy, community management, organic social, influencer partnershipsemailEmail campaigns, nurture sequences, deliverability, list hygiene, segmentationpaid_mediaPPC, display ads, social ads, programmatic, retargeting, budget allocationanalyticsAttribution, reporting, dashboards, A/B testing, conversion tracking, data quality

Promoting to Permanent Marketing Standards#

When a learning is broadly applicable (not a one-off campaign fix), promote it to permanent marketing standards.

When to Promote#

• Messaging pattern proves effective across 3+ campaigns or segments
• Channel insight applies to all campaigns on that platform
• Audience shift is confirmed by multiple data sources over 2+ quarters
• Attribution fix prevents a class of tracking errors, not just one campaign
• Brand rule violation occurs in 3+ assets from different teams

Promotion Targets#

TargetWhat Belongs ThereBrand guidelinesMessaging tone, positioning statements, visual identity rules, do/don't examplesChannel playbooksPer-channel best practices, benchmarks, creative specs, targeting strategiesAudience personasICP definitions, segment profiles, buying triggers, objection handlingContent calendarContent type cadence, topic frameworks, seasonal planning, repurposing rulesAttribution modelUTM taxonomy, tagging standards, measurement methodology, reporting templatesTOOLS.mdMarketing tool configurations, integration gotchas, API limitsAGENTS.mdAutomated marketing workflows, review checkpoints

How to Promote#

1. Distill the learning into a concise guideline, checklist item, or rule

2. Add to appropriate target (brand doc, playbook, persona profile)

3. Show a reviewed diff and apply only after explicit user approval

4. Update original entry:

   • Change **Status**: pending → **Status**: promoted
   • Add **Promoted**: brand guidelines (or channel playbook, persona doc, content calendar, attribution model)

Promotion Examples#

Learning (verbose):

Product launch email sent to enterprise segment with SMB-focused messaging. Used "easy setup" and "affordable pricing" — enterprise buyers want ROI data, security compliance, and integration capabilities. Open rate 8% vs. 22% benchmark.

As brand guideline (concise):

markdown

## Enterprise Messaging Rules
- Lead with ROI metrics and business impact, not ease-of-use
- Reference security certifications (SOC2, ISO 27001) in first fold
- Include integration ecosystem and API capabilities
- Avoid "affordable" or "cheap" — use "cost-effective" with TCO comparison

Learning (verbose):

LinkedIn carousel ads outperform single-image for B2B. 12 campaigns, 3 months: 2.8x higher CTR, 1.9x lower CPL. Best with 5-7 slides, data-driven, strong hook.

As channel playbook (actionable):

markdown

## LinkedIn Ad Creative Guidelines
- Default to carousel format for B2B educational content (5-7 slides)
- First slide: strong hook (question or bold stat)
- Benchmark CTR: 0.8-1.2% (carousel) vs. 0.3-0.5% (single image)

Recurring Pattern Detection#

If logging something similar to an existing entry:

1. Search first: grep -r "keyword" .learnings/

2. Link entries: Add **See Also**: CMP-20250110-001 in Metadata

3. Bump priority if issue keeps recurring

4. Consider systemic fix: Recurring marketing issues often indicate:

   • Missing brand guideline (→ add to brand standards)
   • Outdated persona (→ refresh audience research)
   • Broken process (→ add to campaign checklist)
   • Attribution gap (→ fix tracking infrastructure)

Periodic Review#

Review .learnings/ at natural breakpoints:

When to Review#

• Before launching a new campaign in the same channel
• After completing a campaign or content initiative
• When the same performance pattern appears again
• Monthly during active campaign periods
• Quarterly for audience persona and brand guideline updates

Quick Status Check#

bash

# Count pending marketing issues
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority campaign issues
grep -B5 "Priority\*\*: high" .learnings/CAMPAIGN_ISSUES.md | grep "^## \["

# Find all messaging misses
grep -B2 "messaging_miss" .learnings/LEARNINGS.md | grep "^## \["

Review Actions#

• Resolve fixed campaign issues
• Promote recurring patterns to brand guidelines or playbooks
• Link related entries across files
• Update attribution model with tracking fixes

Hook Integration#

Enable automatic reminders through agent hooks. This is opt-in.

Hooks persist across sessions once installed. Keep them project-scoped. Do not install user-level or global hooks. Never use an empty matcher. PostToolUse inspects command output in-process; do not log raw output, secrets, or transcripts.

Quick Setup (Claude Code / Codex)#

Create .claude/settings.json in your project:

json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "campaign|CTR|conversion|email|attribution|brand|content|ROAS",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-marketing/scripts/activator.sh"
      }]
    }]
  }
}

This injects a marketing-focused learning evaluation reminder after matching prompts (~50-100 tokens overhead).

Advanced Setup (With Error Detection)#

json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "campaign|CTR|conversion|email|attribution|brand|content|ROAS",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-marketing/scripts/activator.sh"
      }]
    }]
  }
}

Leave PostToolUse disabled. Do not attach error-detector.sh to every Bash call.

Available Hook Scripts#

ScriptHook TypePurposescripts/activator.shUserPromptSubmitReminds to evaluate marketing learnings after tasksscripts/error-detector.shPostToolUse (Bash)Triggers on campaign issues, deliverability errors, tracking problems

See references/hooks-setup.md for detailed configuration and troubleshooting.

Automatic Skill Extraction#

Extracted skills are untrusted until a human reviews the generated SKILL.md. Do not keep or publish an extracted skill without explicit user approval.

When a marketing learning is valuable enough to become a reusable skill, extract it.

Skill Extraction Criteria#

CriterionDescriptionRecurringSame campaign pattern in 2+ channels or quartersVerifiedStatus is resolved with proven fix and measured improvementNon-obviousRequired actual analysis, testing, or investigationBroadly applicableNot campaign-specific; useful across segments or channelsUser-flaggedUser says "save this as a skill" or similar

Extraction Workflow#

1. Identify candidate: Learning meets extraction criteria

2. Run helper (or create manually): bash

   ./skills/self-improving-marketing/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improving-marketing/scripts/extract-skill.sh skill-name
   
   

3. Customize SKILL.md: Fill in template with marketing-specific content

4. Update learning: Set status to promoted_to_skill, add Skill-Path

5. Verify: Read skill in fresh session to ensure it's self-contained

Extraction Detection Triggers#

Use conversation signals ("This campaign pattern keeps working", "Save this as a playbook") to identify extraction candidates.

Multi-Agent Support#

AgentActivationDetectionClaude CodeHooks (UserPromptSubmit, PostToolUse)Automatic via error-detector.shCodex CLIHooks (same pattern)Automatic via hook scriptsGitHub CopilotManual ( .github/copilot-instructions.md)Manual reviewOpenClawWorkspace injection + inter-agent messagingVia session tools

Best Practices#

1. Log immediately — campaign context and metrics fade fast after the moment passes
2. Include before/after metrics — quantify the impact with CTR, CVR, CPL, ROAS comparisons
3. Specify the channel — patterns differ between Google Ads, LinkedIn, email, organic
4. A/B test before scaling — never scale a campaign change based on gut feel alone
5. Document creative rationale — why a headline, image, or CTA was chosen for the segment
6. Track attribution end-to-end — verify UTMs survive redirects, link shorteners, and cross-domain hops
7. Review personas quarterly — audience needs and behaviors shift; validate with data
8. Audit brand consistency monthly — check all active assets against current brand guidelines
9. Promote after review when recurrence appears — if a messaging pattern works across 3+ campaigns, codify it

Gitignore Options#

Keep learnings local (per-team):

gitignore

.learnings/

Track learnings in repo (org-wide): Don't add to .gitignore — learnings become shared marketing knowledge.

Hybrid (track templates, ignore entries): add .learnings/*.md and !.learnings/.gitkeep to .gitignore.

Stackability Contract (Standalone + Multi-Skill)#

This skill is standalone-compatible and stackable with other self-improving skills.

Namespaced Logging (recommended for 2+ skills)#

• Namespace for this skill: .learnings/marketing/
• Keep current standalone behavior if you prefer flat files.
• Optional shared index for all skills: .learnings/INDEX.md

Required Metadata#

Every new entry must include:

markdown

**Skill**: marketing

Hook Arbitration (when 2+ skills are enabled)#

• Use one dispatcher hook as the single entrypoint.
• Dispatcher responsibilities: route by matcher, dedupe repeated events, and rate-limit reminders.
• Suggested defaults: dedupe key = event + matcher + file + 5m_window; max 1 reminder per skill every 5 minutes.

Narrow Matcher Scope (marketing)#

Only trigger this skill automatically for marketing signals such as:

• campaign|ctr|conversion|attribution|creative test
• persona|positioning|channel mix|cac|roas
• explicit marketing intent in user prompt

Cross-Skill Precedence#

When guidance conflicts, apply:

1. security
2. engineering
3. coding
4. ai
5. user-explicit domain skill
6. meta as tie-breaker

Ownership Rules#

• This skill writes only to .learnings/marketing/ in stackable mode.
• Do not read other skill folders, their SKILL.md files, or their log entries.
• Standalone mode writes to this project's .learnings/*.md log files only.
• Stackable mode writes only to the namespaced folder above and must not rewrite other skills' log entries.
• Promotion into AGENTS.md, SOUL.md, TOOLS.md, MEMORY.md, rules, hooks, or generated skills is not a logging write. Show a reviewed diff and apply only after explicit user approval.