Creating New Skills & Contributing
Relevant source files
The following files were used as context for generating this wiki page:
This page outlines the standards and procedures for developing new agent skills and contributing to the Developer Marketing Skills repository. The project provides a collection of specialized knowledge and workflows for AI agents (such as Claude Code, Cursor, or Windsurf) focused on marketing to technical audiences.
Sources: README.md:1-12
Skill Architecture and Specification
All skills must adhere to the Agent Skills specification. In this repository, skills are content-only markdown files located in the skills/ directory. Each skill is contained within its own sub-directory named after the skill.
Sources: AGENTS.md:5-15, AGENTS.md:51-57
Required Directory Structure
A standard skill implementation consists of several mandatory and optional components:
skills/skill-name/
├── SKILL.md # Required: Main instructions and YAML frontmatter (<500 lines)
├── README.md # Recommended: Overview and usage examples
├── references/ # Optional: Detailed documentation or templates
├── scripts/ # Optional: Executable code for the agent
└── assets/ # Optional: Templates or data files
Sources: AGENTS.md:51-57
The following diagram illustrates the relationship between a skill's core components and the AI agent:
Sources: AGENTS.md:20-30, AGENTS.md:51-57
Frontmatter Requirements
Every SKILL.md must start with a YAML frontmatter block. This metadata is critical for skill discovery and categorization by AI agents.
| Field | Required | Constraints |
|---|---|---|
name | Yes | 1-64 characters, lowercase a-z, numbers, hyphens. Must match directory name exactly. |
description | Yes | 1-1024 characters. Must include trigger phrases for the agent. |
license | No | Default is MIT. |
metadata | No | Key-value pairs like version or author. |
Sources: AGENTS.md:37-45
Naming Conventions
The name field is subject to strict validation rules:
- Must use lowercase letters, numbers, and hyphens only.
- Cannot start or end with a hyphen.
- No consecutive hyphens (
--). - Valid examples:
developer-onboarding,x-devs. - Invalid examples:
Developer-Onboarding,developer--onboarding.
Sources: AGENTS.md:46-50
Content Guidelines for SKILL.md
The SKILL.md file serves as the system prompt for the AI agent. It must prioritize clarity and technical accuracy over "marketing fluff."
Technical Constraints
- Length: Keep the file under 500 lines. Excessive detail should be moved to the
references/directory. - Formatting: Use H2 (
##) for main sections and H3 (###) for subsections. - Style: Use direct, instructional language in the second person (e.g., "Check if the context exists").
Sources: AGENTS.md:65-75
Foundation Dependency
New skills should almost always reference the developer-audience-context skill. This foundation provides the persona, pain points, and tech stack details necessary for the agent to generate relevant content.
Git Workflow and PR Checklist
Contributors must follow a structured workflow to ensure skill quality and consistency.
Branching and Commits
- Branching: Use prefixes like
feature/skill-name,fix/skill-name, ordocs/description. - Commits: Follow Conventional Commits.
feat: add hacker-news-strategy skillfix: improve clarity in developer-onboarding
Sources: AGENTS.md:105-115
Pull Request Checklist
Before submitting a PR, verify the following:
- Directory name matches the
namefield in YAML frontmatter exactly. - YAML frontmatter is valid and contains trigger phrases in the
description. SKILL.mdis under 500 lines.- A
README.mdwith a quick overview is included in the skill folder. - The skill is added to the appropriate category in the main
README.md. - The ASCII diagram in
README.mdis updated if category structures change.
Sources: AGENTS.md:117-125, AGENTS.md:144-149
Summary of Skill Categories
When contributing, skills should be placed into one of the following established categories to maintain repository organization:
| Category | Focus Area |
|---|---|
| Foundation | Developer audience context and personas. |
| Content & Community | Tutorials, blog posts, newsletters, and advocacy. |
| Distribution | HN, Reddit, GitHub, and social media strategies. |
| Developer Experience | Docs, SDKs, and API onboarding. |
| Growth & Acquisition | SEO, lead gen, and hackathons. |
| Intelligence | Listening, competitor tracking, and alternatives. |
Sources: AGENTS.md:127-140, README.md:27-110
Contributing to this project involves creating highly structured, instruction-heavy markdown files that allow AI agents to navigate the unique challenges of developer marketing, such as bypassing "marketing speak" in favor of technical depth and transparency.
Sources: README.md:14-25