How Modules Are Organized in the MarketingSkills Project

The marketingskills repository uses a deliberately shallow, content-driven module structure where the skills/ directory contains workflow definitions with mandatory SKILL.md files, the tools/ directory houses executable Node.js CLI utilities and API integration guides, and root-level metadata files govern agent discovery and versioning.

The coreyhaines31/marketingskills repository provides AI agents with marketing-focused capabilities through a curated collection of Agent Skills. Understanding how modules are organized in the marketingskills project is essential for contributors building new skills and developers integrating these workflows into Claude Code, Codex, or Cursor environments.

Top-Level Directory Layout

The repository follows a flat hierarchy designed for quick traversal by automated agents. Rather than deep nesting, modules are categorized into three primary areas: marketing skills (content), executable tools (utilities), and configuration metadata (orchestration).

Key directories at the repository root include:

• skills/ – Marketing workflow definitions (≈70+ skills)
• tools/ – CLI utilities and third-party API integrations
• .claude-plugin/ – Claude Code marketplace manifest
• AGENTS.md – Repository conventions and contributor guidelines
• VERSIONS.md – Version lock-file for upstream change detection

The Skills Module Structure (skills/)

Each marketing capability lives as an isolated module within skills/. This directory contains approximately 70 subdirectories, each representing a discrete agent skill such as page-cro/, email-sequence/, or ad-audit/.

Skill Folder Conventions

Every skill module follows a strict one-folder-per-skill rule. The folder name must exactly match the name field in the skill's front-matter metadata. For example, the conversion rate optimization skill resides at skills/page-cro/ and declares name: page-cro in its metadata.

Each skill folder contains:

• SKILL.md (mandatory) – The skill definition with YAML front-matter and markdown instructions
• references/ (optional) – Supporting documentation and examples
• scripts/ (optional) – Auxiliary automation scripts
• assets/ (optional) – Images, templates, or binary resources

SKILL.md File Requirements

The SKILL.md file follows the Agent Skills specification. The file begins with YAML front-matter containing at minimum the name and description keys, followed by markdown content describing step-by-step workflow instructions.

According to the CI checks defined in AGENTS.md, each SKILL.md must remain under 500 lines to ensure fast parsing by agent systems. The front-matter name field must exactly match the parent folder name, creating a predictable lookup pattern: skills/<skill-name>/SKILL.md.

The Tools Module Structure (tools/)

While skills provide knowledge, the tools/ directory provides actionable capabilities. This module contains executable utilities that agents invoke to interact with external services like Google Analytics 4, Stripe, or Mailchimp.

CLI Utilities (tools/clis/)

The clis/ subdirectory houses zero-dependency Node.js scripts designed for direct execution. These utilities require no build step and can be invoked immediately:

node tools/clis/ga4-report.js run --dry-run

The --dry-run flag allows agents to preview API requests without transmitting data, a safety feature implemented across all CLI tools in this directory.

Integration Guides (tools/integrations/)

Complementing the CLI tools, the integrations/ directory contains markdown documentation explaining API endpoints, OAuth scopes, and sample payloads. For example, tools/integrations/ga4.md details the Google Analytics 4 API structure that ga4-report.js consumes.

Tool Registry (tools/REGISTRY.md)

The REGISTRY.md file serves as the canonical index of all available tools. Agents parse this file to discover capabilities, understand input parameters, and determine which external services each tool can access.

Configuration and Metadata Files

Several root-level files govern repository behavior and agent discovery:

• AGENTS.md – Defines repository-wide conventions, including the 500-line limit enforcement and front-matter requirements for skills
• .claude-plugin/marketplace.json – Publishes skill definitions to the Claude Code plugin marketplace
• VERSIONS.md – Acts as a version lock-file enabling agents to detect when upstream skills receive updates
• README.md – Human-readable skill matrix and installation instructions

Programmatic Access to Module Organization

Agents can programmatically discover and load skills by reading the filesystem directly. The following pattern demonstrates how to parse a skill's metadata and instructions:

const fs = require('fs');
const path = require('path');
const yaml = require('js-yaml');

// Construct path to specific skill
const skillPath = path.join(__dirname, 'skills', 'page-cro', 'SKILL.md');
const skillMd = fs.readFileSync(skillPath, 'utf8');

// Parse YAML front-matter
const [, frontMatter, body] = skillMd.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
const { name, description } = yaml.load(frontMatter);

console.log(`Loaded skill: ${name}`);
console.log(`Description: ${description}`);
// The 'body' variable contains the markdown instructions for the LLM

This approach leverages the shallow directory structure to enable dynamic skill discovery without complex module resolution.

Summary

• Skills live in skills/<name>/SKILL.md with mandatory YAML front-matter where the name matches the folder exactly
• Tools reside in tools/clis/ (executable Node.js) and tools/integrations/ (API documentation), indexed by REGISTRY.md
• Metadata files (AGENTS.md, VERSIONS.md, .claude-plugin/marketplace.json) govern conventions, versioning, and marketplace publication
• Size limits enforced by CI require all SKILL.md files to remain under 500 lines
• Execution of CLI tools follows the pattern node tools/clis/<tool-name>.js run --dry-run

Frequently Asked Questions

What naming convention must skill folders follow?

Skill folder names must exactly match the name field in their SKILL.md front-matter. For example, a skill declared with name: email-sequence must reside in skills/email-sequence/SKILL.md. This one-to-one mapping enables deterministic file resolution by agent runtimes.

How are file size limits enforced for skill modules?

The repository uses CI checks configured in AGENTS.md to enforce a 500-line maximum on all SKILL.md files. This constraint ensures skills remain focused, parse quickly, and load efficiently into language model context windows.

What is the difference between the tools/clis/ and tools/integrations/ directories?

The tools/clis/ directory contains executable Node.js scripts that perform actions (such as querying APIs), while tools/integrations/ contains static markdown documentation describing how to communicate with external services. The CLI scripts reference the integration guides for configuration details like OAuth scopes and endpoint specifications.

How do AI agents detect updates to skills in the repository?

Agents monitor the VERSIONS.md file, which serves as a version lock-file tracking the state of upstream skills. By comparing their cached version against this file, agents can determine when skill definitions have changed and trigger updates accordingly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}