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

The development workflow for marketingskills follows a branch-by-feature strategy using conventional commits, requiring strict front-matter validation in SKILL.md files and mandatory version tracking via 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 and 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.

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 file and optional subdirectories for references, scripts, or assets.

mkdir -p skills/your-skill-name

All skills live under the skills/ root directory according to the file structure defined in CONTRIBUTING.md.

Create SKILL.md with Valid Frontmatter

Write your SKILL.md file containing required YAML frontmatter validated against the Agent Skills specification in AGENTS.md. Include the name and description fields exactly as shown.

---
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 to enable runtime update detection by agents. Use the pipe-delimited table format including the skill name, semantic version, and current date.

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:.

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 before requesting review.

Required File Structure and Conventions

The frontmatter validation in AGENTS.md requires exactly two YAML fields at the top of every 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.

# 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.
• Directory structure: Create lowercase, hyphen-separated folders under skills/ containing SKILL.md.
• Frontmatter rules: Include mandatory name and description YAML fields in every skill file.
• Version tracking: Update 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, every 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 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 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 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.

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