How to Contribute to the Marketingskills Project: A Step-by-Step Guide

Yes, you can contribute to the marketingskills project by forking the repository, creating a new skill in the skills/ directory, validating it with the provided script, and opening a pull request.

The marketingskills repository is an open-source collection of Markdown-based Agent Skills that enable AI agents to perform marketing tasks like CRO, copywriting, and SEO optimization. According to the project's README, contributions are explicitly welcomed, and the codebase in coreyhaines31/marketingskills provides clear architectural guidelines and automated validation to ensure every submission meets quality standards.

Understanding the Repository Structure

Before you contribute to the marketingskills project, familiarize yourself with the core architecture defined in AGENTS.md and CONTRIBUTING.md.

Core Components

The repository organizes content into specific directories:

• skills/ — Contains individual skill subdirectories (e.g., skill-name/), each requiring a mandatory SKILL.md file following the Agent Skills specification
• tools/REGISTRY.md — Central index of zero-dependency CLI tools and third-party integrations
• tools/integrations/*.md — Documentation for external API integrations (GA4, Stripe, etc.)
• AGENTS.md — Specifications for naming conventions, front-matter validation, and Git workflow
• VERSIONS.md — Tracks version numbers for each skill to notify users of updates
• validate-skills.sh — Local lint script that enforces YAML validity, naming rules, and the 500-line limit

Setting Up Your Contribution

Follow the Git workflow outlined in AGENTS.md to prepare your local environment.

Fork and Clone

Start by forking the repository on GitHub, then clone your copy:

git clone https://github.com/<your-username>/marketingskills.git
cd marketingskills

The upstream repository remains coreyhaines31/marketingskills, while your fork serves as the origin for your feature branches.

Create a Feature Branch

Use the branch naming convention specified in AGENTS.md:

git checkout -b feature/<skill-name>

Replace <skill-name> with a lowercase, hyphenated description of your contribution (e.g., feature/lead-magnet-wizard).

Creating or Improving Skills

Each skill in the marketingskills project follows a strict structural format defined in CONTRIBUTING.md.

Directory Layout

Create a new skill directory under skills/:

mkdir -p skills/your-skill-name

Inside this directory, create a SKILL.md file with mandatory front-matter:

---
name: your-skill-name
description: When the user wants to... (include trigger phrases describing the marketing task)
---

Content Requirements

The SKILL.md file must adhere to constraints defined in AGENTS.md:

• Line limit: Maximum 500 lines per skill
• Front-matter name: Must match the directory name exactly (lowercase, hyphens only)
• Naming rules: No consecutive hyphens (--), maximum 64 characters
• Description: Maximum 1024 characters, must include trigger phrases for AI agent recognition

Example Skill Structure

Here is a minimal example for a fictional "lead-magnet-wizard" skill:

---
name: lead-magnet-wizard
description: Generate high-conversion lead magnets (e-books, checklists) for SaaS products.
---

# Lead Magnet Wizard

1. Ask the user for the target audience and primary value proposition.
2. Draft a short outline of the magnet's sections.
3. Generate a polished draft using the built-in copywriting patterns.

**Usage**

```text
/create lead-magnet-wizard

## Testing and Validation

Before submitting your contribution to the marketingskills project, you must run the validation script to ensure compliance.

### Running Local Checks

Execute the lint script from the repository root:

```bash
./validate-skills.sh

This script validates:

• YAML front-matter syntax
• Directory name alignment with the name field
• Line count limits (≤ 500 lines)
• Description length (≤ 1024 characters)

Resolve all warnings before committing. For example, output might show:

✅ skill lead-magnet-wizard: front-matter OK
⚠️ skill copywriting: description exceeds 1024 characters

Alternative: Using the CLI Generator

The repository includes a zero-dependency Node.js CLI at tools/clis/skill.js that scaffolds skills automatically:

npx skills add coreyhaines31/marketingskills --skill lead-magnet-wizard

This command creates the folder structure, starter SKILL.md with valid front-matter, and updates tools/REGISTRY.md.

Submitting Your Contribution

Once validation passes, prepare your submission following the project's Git standards.

Commit Standards

Use Conventional Commits style as specified in AGENTS.md:

git add skills/your-skill-name
git commit -m "feat: add lead-magnet-wizard skill"
git push origin feature/your-skill-name

Pull Request Process

Open a pull request against the main branch using the template located at .github/PULL_REQUEST_TEMPLATE/new-skill.md. The template enforces the checklist from CONTRIBUTING.md, including:

• Front-matter matches directory name
• Description is clear and contains trigger phrases
• No secrets or credentials exposed

Maintain the registry manually if not using the CLI by adding an entry to tools/REGISTRY.md:

| Skill                | Description |
|----------------------|-------------|
| [lead-magnet-wizard](skills/lead-magnet-wizard/) | Generate high-conversion lead magnets for SaaS products. |

Project maintainers will run CI validation (the same validate-skills.sh script) and merge approved contributions into main.

Summary

• Yes, contributions are welcome to the marketingskills project via GitHub pull requests
• All skills reside in skills/<skill-name>/SKILL.md with strict front-matter requirements (name, description ≤ 1024 chars)
• Files must be ≤ 500 lines and directory names must match the front-matter name field exactly
• Run ./validate-skills.sh locally before submitting to check YAML syntax and naming compliance
• Use the feature/<skill-name> branch convention and Conventional Commits format
• Reference CONTRIBUTING.md, AGENTS.md, and tools/REGISTRY.md for detailed specifications

Frequently Asked Questions

Do I need programming experience to contribute to the marketingskills project?

No advanced programming is required. Skills are written in Markdown with YAML front-matter. You only need to understand the front-matter structure defined in AGENTS.md and follow the 500-line limit. The validate-skills.sh script handles technical validation automatically.

What happens if my skill description is too long?

If your description exceeds 1024 characters or lacks trigger phrases, the ./validate-skills.sh script will flag an error. You must shorten the description and ensure it includes actionable trigger phrases (e.g., "When the user wants to...") so AI agents can recognize when to invoke the skill.

Can I update an existing skill instead of creating a new one?

Yes, improvements to existing skills are welcome. Follow the same branch naming convention (feature/<descriptive-change>), modify the relevant skills/<skill-name>/SKILL.md file, and bump the version in VERSIONS.md if the change constitutes a major update. Run the validation script before submitting your pull request.

Is there a specific format for commit messages?

Yes, the project requires Conventional Commits format as documented in AGENTS.md. Use prefixes like feat: for new skills, fix: for corrections, or docs: for documentation updates. This standardizes the commit history and enables automated changelog generation.

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