AGENTS.md · git:20260303.500b44b · 2026-03-03 · sha256 07dfed42118c74f1
AGENTS.md git:20260303.500b44bA
Immutable. This exact content is served forever at /api/v1/blob/07dfed42118c74f1.
# AGENTS.md
Guidelines for AI agents working in this repository.
## Repository Overview
This repository contains **Agent Skills** for AI agents following the [Agent Skills specification](https://agentskills.io/specification.md). Skills install to `.agents/skills/` (the cross-agent standard). These skills are specifically designed for **marketing to developers** — DevRel, developer tools, APIs, SDKs, and technical products.
- **Name**: Developer Marketing Skills
- **Focus**: Marketing to developers (DevRel, dev tools, APIs, technical products)
- **License**: MIT
## Repository Structure
```
devmarketing-skills/
├── skills/ # Agent Skills
│ └── skill-name/
│ ├── SKILL.md # Required skill file
│ ├── README.md # Quick overview
│ └── references/ # Optional supporting docs
├── AGENTS.md # This file
├── CONTRIBUTING.md
├── LICENSE
└── README.md
```
## Build / Lint / Test Commands
**Skills** are content-only (no build step). Verify manually:
- YAML frontmatter is valid
- `name` field matches directory name exactly
- `name` is 1-64 chars, lowercase alphanumeric and hyphens only
- `description` is 1-1024 characters
## Agent Skills Specification
Skills follow the [Agent Skills spec](https://agentskills.io/specification.md).
### Required Frontmatter
```yaml
---
name: skill-name
description: What this skill does and when to use it. Include trigger phrases.
metadata:
version: 1.0.0
---
```
### Frontmatter Field Constraints
| Field | Required | Constraints |
|---------------|----------|------------------------------------------------------------------|
| `name` | Yes | 1-64 chars, lowercase `a-z`, numbers, hyphens. Must match dir. |
| `description` | Yes | 1-1024 chars. Describe what it does and when to use it. |
| `license` | No | License name (default: MIT) |
| `metadata` | No | Key-value pairs (author, version, etc.) |
### Name Field Rules
- Lowercase letters, numbers, and hyphens only
- Cannot start or end with hyphen
- No consecutive hyphens (`--`)
- Must match parent directory name exactly
**Valid**: `developer-onboarding`, `hacker-news-strategy`, `x-devs`
**Invalid**: `Developer-Onboarding`, `-onboarding`, `developer--onboarding`
### Skill Directory Structure
```
skills/skill-name/
├── SKILL.md # Required - main instructions (<500 lines)
├── README.md # Recommended - quick overview and usage
├── references/ # Optional - detailed docs, templates, examples
├── scripts/ # Optional - executable code
└── assets/ # Optional - templates, data files
```
## Foundation Skill
The `developer-audience-context` skill is the foundation. All other skills reference it first to understand:
- Developer persona (role, seniority, tech stack)
- Where they hang out (Reddit, HN, Discord, Twitter)
- Pain points and problems
- Current alternatives
- Voice and tone
When creating new skills, include a "Before You Start" section that checks for `.agents/developer-audience-context.md`.
## Writing Style Guidelines
### Structure
- Keep `SKILL.md` under 500 lines (move details to `references/`)
- Use H2 (`##`) for main sections, H3 (`###`) for subsections
- Use bullet points and numbered lists liberally
- Short paragraphs (2-4 sentences max)
- Include tables for reference data and comparisons
### Tone
- Direct and instructional
- Second person ("Check if the developer-audience-context exists")
- Technical but accessible — assume readers understand developer concepts
- No marketing fluff — developers see through it
### Developer Marketing Principles
When writing skills, remember that developers:
- Skip landing pages → Go straight to docs, GitHub, API reference
- Distrust marketing speak → Want technical accuracy and honest tradeoffs
- Value transparency → Open source, public roadmaps, honest pricing
- Research thoroughly → Read HN comments, Reddit threads, GitHub issues
- Influence purchasing → Even when not the buyer, they're the decision-maker
### Formatting
- Bold (`**text**`) for key terms
- Code blocks for examples, commands, and templates
- Tables for reference data
- No excessive emojis
### Clarity Principles
- Clarity over cleverness
- Specific over vague
- Active voice over passive
- One idea per section
### Description Field Best Practices
The `description` is critical for skill discovery. Include:
1. What the skill does
2. When to use it (trigger phrases)
3. Related skills for scope boundaries
```yaml
description: When the user wants to write technical tutorials or quickstart guides. Use when the user mentions "tutorial," "quickstart," "getting started guide," or "code walkthrough." For general DevRel content, see devrel-content.
```
## Tool Integrations
Skills reference various tools relevant to developer marketing:
| Category | Tools |
|----------|-------|
| **Listening & Monitoring** | Octolens |
| **Documentation** | Mintlify, ReadMe, GitBook |
| **Analytics** | Plausible, PostHog, Amplitude |
| **Community** | Discord, Slack |
| **Email** | Resend, Loops, Customer.io |
## Git Workflow
### Branch Naming
- New skills: `feature/skill-name`
- Improvements: `fix/skill-name-description`
- Documentation: `docs/description`
### Commit Messages
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
- `feat: add hacker-news-strategy skill`
- `fix: improve clarity in developer-onboarding`
- `docs: update README with new skill`
### Pull Request Checklist
- [ ] `name` matches directory name exactly
- [ ] `name` follows naming rules (lowercase, hyphens, no `--`)
- [ ] `description` is 1-1024 chars with trigger phrases
- [ ] `SKILL.md` is under 500 lines
- [ ] README.md included with quick overview
- [ ] References `developer-audience-context` where appropriate
- [ ] No sensitive data or credentials
## Skill Categories
Skills are organized into these categories:
| Category | Focus |
|----------|-------|
| **Foundation** | Developer audience context (referenced by all others) |
| **Content & Community** | DevRel content, tutorials, newsletters, community, advocacy |
| **Distribution & Discovery** | HN, Reddit, GitHub, Twitter/X, LinkedIn, YouTube |
| **Developer Experience** | Docs, SDKs, API onboarding, sandboxes, changelogs |
| **Growth & Acquisition** | SEO, directories, lead gen, hackathons, ads |
| **Competitive Intelligence** | Listening, competitor tracking, alternatives pages |
| **Conversion & Activation** | Signup, onboarding, free tier, pricing |
| **Lifecycle & Retention** | Email sequences, churn, power users |
When adding new skills, follow the naming patterns of existing skills in that category.
## Cross-References
Skills should reference related skills in their "Related Skills" section. Common patterns:
- `devrel-content` ↔ `technical-tutorials` ↔ `developer-seo`
- `developer-listening` ↔ `competitor-tracking` ↔ `alternatives-pages`
- `developer-onboarding` ↔ `docs-as-marketing` ↔ `api-onboarding`
- `developer-signup-flow` ↔ `developer-onboarding` ↔ `free-tier-strategy`
## Adding New Skills
1. Create directory: `skills/skill-name/`
2. Create `SKILL.md` with valid YAML frontmatter
3. Create `README.md` with quick overview
4. Add to appropriate category in main `README.md`
5. Update ASCII diagram if skill changes category structure
6. Submit PR following the checklist above