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:

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

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):

clawdhub install self-improving-marketing

Manual:

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:

~/.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

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:

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:

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:

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:

## [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:

Campaign Issue Entry [CMP-YYYYMMDD-XXX]

Append to .learnings/CAMPAIGN_ISSUES.md:

## [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:

## [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:

### 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

Area Tags

Use to filter learnings by marketing domain:

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

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):

## 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):

## 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

# 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:

{
  "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)

{
  "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

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

Extraction Workflow

1. Identify candidate: Learning meets extraction criteria
2. Run helper (or create manually):

   ./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

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):

.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:

**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.