Agent Specification and Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Agent Specification and Guidelines define the standards, structures, and behavioral expectations for AI agents (such as Claude Code, Cursor, or Windsurf) operating within the devmarketing-skills repository. The primary purpose is to provide agents with specialized knowledge and workflows for developer-focused marketing tasks, ensuring that AI-generated content and strategies align with technical accuracy and developer audience expectations.
The project follows the Agent Skills specification, where skills are installed to the cross-agent standard directory .agents/skills/. These skills function as specialized instruction sets that agents reference to perform tasks ranging from creating technical tutorials to optimizing developer onboarding flows.
Sources: AGENTS.md:3-9, README.md:3-8
Core Skill Architecture
The architecture is based on "Skills," which are Markdown files containing specialized knowledge and frontmatter for agent discovery. Each skill is self-contained within a directory in skills/ and must include a SKILL.md file.
Required Skill Structure
Every skill must adhere to a specific directory and file structure to ensure compatibility with agent discovery mechanisms.
The diagram above shows the required and optional components of a single agent skill.
Sources: AGENTS.md:52-60
Skill Metadata Configuration
Skills require valid YAML frontmatter for identification and triggering. The name field is strictly enforced and must match the directory name exactly.
| Field | Required | Constraints |
|---|---|---|
name | Yes | 1-64 chars, lowercase a-z, numbers, hyphens. No consecutive hyphens. |
description | Yes | 1-1024 chars. Must include trigger phrases for discovery. |
metadata | No | Versioning and author information. |
license | No | Default is MIT. |
Sources: AGENTS.md:32-50
Foundation and Dependencies
The developer-audience-context skill serves as the foundational requirement for all other skills in the repository. Agents are instructed to load this context before executing other specialized marketing tasks.
This flow illustrates the dependency of specialized skills on the foundational audience context.
Sources: AGENTS.md:62-69, skills/devrel-content/SKILL.md:14-22, skills/technical-tutorials/SKILL.md:14-22
Context Sections
The foundation skill captures ten specific sections of developer intelligence that guide agent behavior:
- Product Overview: Name, category, and core tech.
- Developer Persona: Role, seniority, and tech stack.
- Hanging Out: Communities (Reddit, Discord, HN).
- Pain Points: Functional and emotional frustrations.
- Alternatives: Competitors and DIY workarounds.
- Differentiators: Technical and DX advantages.
- Verbatim Language: Exact phrases used by developers.
- Trust Signals: GitHub stars, adoption metrics.
- Conversion Actions: Success definitions (e.g., "Hello World" moment).
- Voice & Tone: Formality and technicality spectrum.
Sources: skills/developer-audience-context/SKILL.md:40-112
Agent Behavioral Guidelines
Agents must follow specific writing style and tone principles when generating content for developers. Developers are characterized as having a "finely-tuned BS detector," preferring technical accuracy over marketing fluff.
Tone and Style
- Direct and Instructional: Use second-person perspective (e.g., "Check if the context exists").
- Clarity Over Cleverness: One idea per section with active voice.
- Transparency: Acknowledge tradeoffs; nothing is perfect.
- No Marketing Fluff: Avoid terms like "best-in-class" or "seamless."
Sources: AGENTS.md:73-95, skills/devrel-content/SKILL.md:204-215
Content Constraints
To maintain efficiency and readability for the LLM context window:
SKILL.mdfiles must be kept under 500 lines.- Detailed documentation should be moved to the
references/directory. - Paragraphs should be short (2-4 sentences max).
- Bold text should be used for key terms.
Sources: AGENTS.md:71-83
Technical Implementation Standards
When agents are tasked with generating code-related content, they must adhere to the "Copy-Paste Test" to maintain developer trust.
Code Example Requirements
Agents must verify the following for every code block generated:
- Standalone Execution: Code must run without modification.
- Include Imports: All necessary libraries and dependencies must be present.
- Show Output: Expected results should be provided in a code block.
- Error Handling: Real-world patterns (try/catch) should be included.
- Environment Agnostic: Examples should work across macOS, Linux, and Windows.
Sources: skills/devrel-content/SKILL.md:95-125, skills/technical-tutorials/SKILL.md:120-135
Git and Contribution Workflow
Agents contributing to the repository itself must follow Conventional Commits and specific branching strategies:
- Branching:
feature/skill-name,fix/skill-name-description, ordocs/description. - Commits: Use prefixes like
feat:,fix:, ordocs:. - Validation: YAML frontmatter must be valid and the
namefield must match the directory name exactly.
Sources: AGENTS.md:112-132
Conclusion
The Agent Specification and Guidelines ensure that AI agents provide consistent, high-quality, and technically accurate support for developer marketing. By grounding all actions in the foundational audience context and adhering to strict "No BS" writing standards, the project enables agents to bridge the gap between marketing objectives and developer expectations effectively.
Sources: README.md:11-20, AGENTS.md:7-13