# How Modules Are Organized in the MarketingSkills Project

> Discover how modules are organized in the marketingskills project with a shallow, content-driven structure. Explore skill workflows, tools, and root-level metadata for agent discovery.

- Repository: [Corey Haines/marketingskills](https://github.com/coreyhaines31/marketingskills)
- Tags: internals
- Published: 2026-04-24

---

**The marketingskills repository uses a deliberately shallow, content-driven module structure where the `skills/` directory contains workflow definitions with mandatory [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md)** – Repository conventions and contributor guidelines
- **[`VERSIONS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md), each [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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:

```bash
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`](https://github.com/coreyhaines31/marketingskills/blob/main/tools/integrations/ga4.md) details the Google Analytics 4 API structure that [`ga4-report.js`](https://github.com/coreyhaines31/marketingskills/blob/main/ga4-report.js) consumes.

### Tool Registry ([`tools/REGISTRY.md`](https://github.com/coreyhaines31/marketingskills/blob/main/tools/REGISTRY.md))

The [`REGISTRY.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md)** – Defines repository-wide conventions, including the 500-line limit enforcement and front-matter requirements for skills
- **[`.claude-plugin/marketplace.json`](https://github.com/coreyhaines31/marketingskills/blob/main/.claude-plugin/marketplace.json)** – Publishes skill definitions to the Claude Code plugin marketplace
- **[`VERSIONS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/VERSIONS.md)** – Acts as a version lock-file enabling agents to detect when upstream skills receive updates
- **[`README.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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:

```javascript
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`](https://github.com/coreyhaines31/marketingskills/blob/main/REGISTRY.md)
- **Metadata** files ([`AGENTS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md), [`VERSIONS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/VERSIONS.md), [`.claude-plugin/marketplace.json`](https://github.com/coreyhaines31/marketingskills/blob/main/.claude-plugin/marketplace.json)) govern conventions, versioning, and marketplace publication
- **Size limits** enforced by CI require all [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md) front-matter. For example, a skill declared with `name: email-sequence` must reside in [`skills/email-sequence/SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md) to enforce a 500-line maximum on all [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/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`](https://github.com/coreyhaines31/marketingskills/blob/main/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.