Marketing Skills

A production-ready toolkit for AI agents working on marketing tasks. Ships 51+ Agent Skills (markdown workflows) and a TypeScript CLI platform with optional Redis-backed response caching.

Built for engineers and technical marketers who want reproducible, testable tooling around conversion optimization, copywriting, SEO, analytics, and growth workflows.

Feature Highlights

Architecture

flowchart TB
  subgraph Content["Content Layer"]
    SK[skills/*/SKILL.md]
    INT[tools/integrations/*.md]
  end

  subgraph Runtime["TypeScript Runtime"]
    CLI[marketing-skills CLI]
    SYNC[ms-sync]
    VAL[ms-validate]
    REG[CLI Registry]
  end

  subgraph Core["Core Libraries"]
    CFG[config]
    LOG[logger]
    HTTP[http-client]
    ARGS[parse-args]
  end

  subgraph Persistence["Persistence"]
    REDIS[(Redis)]
    CACHE[cache layer]
  end

  SK --> VAL
  SK --> SYNC
  CLI --> REG
  REG --> Core
  CLI --> CACHE
  CACHE --> REDIS
  SYNC --> SK

Skill dependency model

flowchart LR
  PM[product-marketing] --> SEO[SEO & Content]
  PM --> CRO[CRO]
  PM --> COPY[Copy]
  PM --> PAID[Paid & Analytics]
  PM --> GROWTH[Growth & Retention]
  PM --> GTM[Sales & GTM]
  PM --> STRAT[Strategy]

Every skill reads product-marketing context first for positioning, audience, and messaging consistency.

Project Structure

marketingskills/
├── src/                    # TypeScript application code
│   ├── cli.ts              # Unified CLI entry
│   ├── config/             # Environment configuration (Zod)
│   ├── lib/
│   │   ├── cli/            # Argument parsing, HTTP helpers
│   │   ├── logger/         # Structured logging
│   │   └── redis/          # Connection manager + cache
│   ├── skills/             # Sync + validate modules
│   └── clis/               # Per-tool CLI handlers (64 tools)
├── skills/                 # Agent Skills content (unchanged spec)
├── tools/
│   ├── clis/               # CLI documentation
│   └── integrations/       # API integration guides
├── tests/                  # Vitest unit tests
├── docs/                   # Engineering documentation
├── dist/                   # Build output (gitignored)
└── .claude-plugin/         # Claude Code marketplace manifest

Design decisions

• Content vs runtime separation — Skills remain portable markdown; runtime code lives under src/.
• Thin CLI modules — Each tool exports a run(args) handler; shared logic lives in src/lib/.
• Optional Redis — Disabled via REDIS_ENABLED=false for local development without infrastructure.

Installation

Prerequisites

• Node.js 18+
• npm 9+
• Redis 6+ (optional, for caching)

Setup

git clone https://github.com/coreyhaines31/marketingskills.git
cd marketingskills
npm install
cp .env.example .env
npm run build

Install skills into your project

npx skills add coreyhaines31/marketingskills

Or install individual skills from the skills/ directory into .agents/skills/.

Configuration

Copy .env.example to .env and adjust:

Tool-specific API keys (e.g. GA4_ACCESS_TOKEN, APOLLO_API_KEY) are read at runtime by each CLI module.

Development

# Watch mode
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Test
npm run test

# Full pipeline
npm run validate

CLI usage

npx marketing-skills list
npx marketing-skills ga4 reports run --property 123456789 --dry-run
npx marketing-skills apollo people search --titles "CEO,CTO"

Skill maintenance

npm run sync-skills      # Update README table + marketplace.json
npm run validate-skills  # Audit all SKILL.md files

Testing

npm test              # Run all unit tests
npm run test:watch    # Watch mode

Tests cover argument parsing, configuration loading, skill discovery/validation, Redis connection management, and cache key generation.

Workflow

sequenceDiagram
  participant Dev as Developer
  participant CLI as marketing-skills
  participant Cache as Redis Cache
  participant API as External API

  Dev->>CLI: marketing-skills ga4 reports run
  CLI->>Cache: getCached(key)
  alt cache hit
    Cache-->>CLI: cached JSON
    CLI-->>Dev: response (_cached: true)
  else cache miss
    CLI->>API: HTTP request
    API-->>CLI: JSON response
    CLI->>Cache: setCached(key, ttl)
    CLI-->>Dev: response
  end

Troubleshooting

Redis connection failed

• Confirm Redis is running: redis-cli ping
• Set REDIS_ENABLED=false for local dev without Redis
• Check REDIS_URL format

Unknown tool: xyz

Run npx marketing-skills list for available tools. Tool names match the legacy tools/clis/ filenames (e.g. ga4, apollo).

GA4_ACCESS_TOKEN environment variable required

Each tool requires its own API credentials. See tools/integrations/ for setup guides.

Skill validation failures

Run npm run validate-skills for detailed per-skill errors. Common issues:

• name must match directory name (lowercase, hyphens only)
• description must include trigger phrases
• SKILL.md should stay under 500 lines

Build errors after pulling

rm -rf dist node_modules
npm install
npm run build

Contributing

1. Fork the repository
2. Create a feature branch
3. Run npm run validate before committing
4. Follow the Agent Skills specification
5. Open a pull request with a clear description

See CONTRIBUTING.md for skill authoring guidelines.

FAQ

Is this a fork of the original Marketing Skills repo?
Yes — this version adds a TypeScript runtime, Redis caching, tests, and CI while preserving the original skill content and workflows.

Do I need Redis?
No. Set REDIS_ENABLED=false and the CLI works without caching.

Can I still use individual tool scripts?
Use npx marketing-skills <tool> instead of standalone node tools/clis/*.js scripts.

Are skills still markdown-only?
Yes. Skills under skills/ remain content files with no build step.

How do skills relate to CLIs?
Skills provide agent workflows; CLIs provide JSON API access to external marketing tools referenced in those workflows.

Skills Index