# Development Workflow for marketingskills: A Complete Guide to Contributing AI Agent Skills

> Master the marketingskills development workflow. Explore our guide on contributing AI agent skills using a proven branch-by-feature strategy and conventional commits.

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

---

**The development workflow for marketingskills follows a branch-by-feature strategy using conventional commits, requiring strict front-matter validation in [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md) files and mandatory version tracking via [`VERSIONS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/VERSIONS.md) before merging through pull requests.**

The **marketingskills** repository by coreyhaines31 provides markdown-based AI agent skills alongside zero-dependency CLI tools. Understanding the development workflow for marketingskills ensures your contributions meet the repository's automated validation checks and content standards documented in [`AGENTS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md) and [`CONTRIBUTING.md`](https://github.com/coreyhaines31/marketingskills/blob/main/CONTRIBUTING.md).

## Step-by-Step Development Workflow

### Fork and Branch Strategy

Start by forking the repository on GitHub and cloning your local copy. Create feature branches using the strict naming convention `feature/skill-your-skill-name` as specified in [`AGENTS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md).

```bash
git clone https://github.com/<your-username>/marketingskills.git
cd marketingskills
git checkout -b feature/skill-your-skill-name

```

Branch names must follow the `feature/…` pattern to pass automated PR checks.

### Scaffold the Skill Structure

Create a new directory under `skills/` using lowercase, hyphen-separated naming. This directory will house your [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md) file and optional subdirectories for references, scripts, or assets.

```bash
mkdir -p skills/your-skill-name

```

All skills live under the `skills/` root directory according to the file structure defined in [`CONTRIBUTING.md`](https://github.com/coreyhaines31/marketingskills/blob/main/CONTRIBUTING.md).

### Create SKILL.md with Valid Frontmatter

Write your [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md) file containing required YAML frontmatter validated against the Agent Skills specification in [`AGENTS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md). Include the `name` and `description` fields exactly as shown.

```markdown
---
name: your-skill-name
description: When to use this skill. Include trigger phrases.
---

## Your Skill Title

Keep content under 500 lines using H2/H3 headings and bullet points.

```

The frontmatter is strictly validated; missing fields will fail the PR checklist.

### Update Version Tracking

Append your skill to [`VERSIONS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/VERSIONS.md) to enable runtime update detection by agents. Use the pipe-delimited table format including the skill name, semantic version, and current date.

```bash
printf "| your-skill-name | 1.0.0 | $(date +%Y-%m-%d) |\n" >> VERSIONS.md

```

Add a corresponding changelog entry under *Recent Changes* in the same file.

### Commit and Submit Changes

Stage your changes and commit using **conventional commit messages** enforced by the PR template. Valid prefixes include `feat:`, `fix:`, and `docs:`.

```bash
git add .
git commit -m "feat: add your-skill-name skill"
git push origin feature/skill-your-skill-name

```

Open a pull request on GitHub and complete the skill quality checklist from [`CONTRIBUTING.md`](https://github.com/coreyhaines31/marketingskills/blob/main/CONTRIBUTING.md) before requesting review.

## Required File Structure and Conventions

The **frontmatter validation** in [`AGENTS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md) requires exactly two YAML fields at the top of every [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md): `name` (matching the directory name) and `description` (containing trigger phrases for agent invocation).

Content constraints include:
- **Maximum 500 lines** per skill file
- **H2 and H3 headings** for organization
- **Optional directories**: `references/`, `scripts/`, `assets/` within the skill folder

The repository requires **zero build steps** for content-only skills, though JavaScript tools in the `tools/` directory should pass `node --check` validation.

## Complete Quick-Start Example

Follow this bash script to execute the full development workflow for marketingskills from initial clone through PR preparation.

```bash

# Clone your fork

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

# Create feature branch following naming conventions

git checkout -b feature/skill-example-skill

# Scaffold directory structure

mkdir -p skills/example-skill

# Create SKILL.md with required frontmatter

cat > skills/example-skill/SKILL.md <<'EOF'
---
name: example-skill
description: When a user needs a quick example. Trigger phrase "example skill".
---

## Example Skill

Demonstrates minimal viable structure.

### Usage

- Ask the agent: "Help me with an example skill."

### Steps

1. Do X
2. Do Y
EOF

# Record version in VERSIONS.md

printf "| example-skill | 1.0.0 | $(date +%Y-%m-%d) |\n" >> VERSIONS.md

# Commit with conventional format and push

git add .
git commit -m "feat: add example-skill skill"
git push origin feature/skill-example-skill

# Now open PR on GitHub using the template checklist

```

## Summary

- **Branch naming**: Use `feature/skill-descriptive-name` format as required by [`AGENTS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md).
- **Directory structure**: Create lowercase, hyphen-separated folders under `skills/` containing [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md).
- **Frontmatter rules**: Include mandatory `name` and `description` YAML fields in every skill file.
- **Version tracking**: Update [`VERSIONS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/VERSIONS.md) with semantic versions and dates for agent update detection.
- **Commit standards**: Use conventional commit prefixes (`feat:`, `fix:`, `docs:`) enforced at PR time.

## Frequently Asked Questions

### What happens if my SKILL.md frontmatter is invalid?

The pull request checks will fail. According to [`AGENTS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/AGENTS.md), every [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md) must contain exactly the `name` and `description` fields in valid YAML format at the top of the file. The PR template includes a specific checkbox for frontmatter validation that reviewers verify before merging.

### Can I include JavaScript tools in my skill contribution?

Yes. While skills themselves are markdown-only, the repository maintains zero-dependency CLI tools in the `tools/` directory. If you add JavaScript utilities, run `node --check` to validate syntax before committing. Reference [`tools/REGISTRY.md`](https://github.com/coreyhaines31/marketingskills/blob/main/tools/REGISTRY.md) for existing integration patterns when connecting to external APIs like GA4 or Stripe.

### Why must I update VERSIONS.md for every new skill?

[`VERSIONS.md`](https://github.com/coreyhaines31/marketingskills/blob/main/VERSIONS.md) serves as the central registry that agents query at runtime to detect available skills and version changes. Without an entry in this file, agents cannot discover or invoke your skill. The table format uses pipes: `| skill-name | version | YYYY-MM-DD |`.

### How long should my skill description be?

Keep the `description` field in [`SKILL.md`](https://github.com/coreyhaines31/marketingskills/blob/main/SKILL.md) frontmatter concise but descriptive, including trigger phrases that help agents recognize when to invoke the skill. The skill body itself must remain under 500 lines total, including headings, lists, and examples, to maintain fast parsing performance.