AGENTS.md · diff

git:20260928.7a6efbf to git:20260928.1155602

6 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# 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).
- **Name**: PMM-Skills
- **GitHub**: [mia-ppp/PMM-Skills](https://github.com/mia-ppp/PMM-Skills)
- **License**: MIT
## Repository Structure
```
PMM-Skills/
├── skills/ # Agent Skills
│ ├── _shared/ # Shared references skills load (evidence gaps, segment selection, messaging examples)
│ └── skill-name/
│ └── SKILL.md # Required skill file
├── tools/
│ ├── clis/ # Zero-dependency Node.js CLI tools (61 tools)
│ ├── composio/ # Composio integration layer (quick start + toolkit mapping)
│ ├── integrations/ # API integration guides per tool
│ └── REGISTRY.md # Tool index with capabilities
├── 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
**CLI tools** (`tools/clis/*.js`) are zero-dependency Node.js scripts (Node 18+). Verify with:
```bash
node --check tools/clis/<name>.js # Syntax check
node tools/clis/<name>.js # Show usage (no args = help)
node tools/clis/<name>.js <cmd> --dry-run # Preview request without sending
```
## 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.
---
```
### 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**: `page-cro`, `email-sequence`, `ab-test-setup`
**Invalid**: `Page-CRO`, `-page`, `page--cro`
### Optional Skill Directories
```
skills/skill-name/
├── SKILL.md # Required - main instructions (<500 lines)
├── references/ # Optional - detailed docs loaded on demand
├── scripts/ # Optional - executable code
└── assets/ # Optional - templates, data files
```
## 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)
### Tone
- Direct and instructional
- Second person ("You are a conversion rate optimization expert")
- Professional but approachable
### Formatting
- Bold (`**text**`) for key terms
- Code blocks for examples 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
### House Style
These rules apply to skill files and to every deliverable a skill produces.
- **No em dashes.** Use a period, comma, colon, or parentheses instead.
- **Sentences span two lines at most.** Split any longer sentence into two.
- **Bullets lead with the outcome.** State the result first, then how to get it.
### 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 optimize conversions on any marketing page. Use when the user says "CRO," "conversion rate optimization," "this page isn't converting." For signup flows, see signup-flow-cro.
```
## Evidence gaps
Evidence decides how an item is labeled, never whether it is included. The full rule lives in one place: `skills/_shared/evidence-gaps.md`. It covers the Sourced / Assumed / Gap labels, the "Inputs and assumptions" note every deliverable opens with, relevance cuts, customer-facing copy, and the ranked Evidence gaps lists.
- **Edit the rule only in that file.** It ships with installed skills and the eval harness loads it; this file does neither.
- **Load it from every skill that produces a deliverable.** Reference it as `../_shared/evidence-gaps.md`.
- **Load `../_shared/segment-selection.md` too** from any skill that chooses an audience, ICP, beachhead, or wedge.
## Production runs
A production run is a skill producing a real deliverable, such as a GTM plan for an assignment.
- **Never edit skill files during a production run.** Finish the run with the skills as they are.
- **Report skill problems separately, after the run.** Name the skill, what the run exposed, and the proposed fix.
- - **Test skill fixes with the eval harness.** Production runs do not grade themselves with a pass or fail step.
+ - **Test skill fixes with a smoke test, not in the run.** Production runs do not grade themselves with a pass or fail step.
+
+ ## Testing skill changes
+
+ - **Check every skill change with an in-session smoke test.** Run the changed skill once on one of its eval prompts from `evals/evals.json`, save the output to `scratch/`, and hand it to the user to review.
+ - **Run the API eval harness only when the user asks.** It is optional. No commit, merge, push, or rollout waits on it.
## 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 skill-name skill`
- `fix: improve clarity in page-cro`
- `docs: update README`
### 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
- [ ] No instruction drops content for lacking proof (see Evidence gaps)
- [ ] Output format ends with an Evidence gaps section
- [ ] No sensitive data or credentials
## Tool Integrations
This repository includes a tools registry for agent-compatible marketing tools.
- **Tool discovery**: Read `tools/REGISTRY.md` to see available tools and their capabilities
- **Integration details**: See `tools/integrations/{tool}.md` for API endpoints, auth, and common operations
- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier, zoominfo, clay, supermetrics, coupler, outreach, crossbeam, introw, composio
- **Composio** (integration layer): Adds MCP access to OAuth-heavy tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, etc.). See `tools/integrations/composio.md`
### Registry Structure
```
tools/
├── REGISTRY.md # Index of all tools with capabilities
└── integrations/ # Detailed integration guides
├── ga4.md
├── stripe.md
├── rewardful.md
└── ...
```
### When to Use Tools
Skills reference relevant tools for implementation. For example:
- `referral-program` skill → rewardful, tolt, dub-co, mention-me guides
- `analytics-tracking` skill → ga4, mixpanel, segment guides
- `email-sequence` skill → customer-io, mailchimp, resend guides
- `paid-ads` skill → google-ads, meta-ads, linkedin-ads guides
For tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion), Composio provides MCP access via a single server. See `tools/integrations/composio.md` for setup and `tools/composio/marketing-tools.md` for the full toolkit mapping.
## Skill Categories
See `README.md` for the current list of skills organized by category. When adding new skills, follow the naming patterns of existing skills in that category.
## Claude Code-Specific Enhancements
These patterns are **Claude Code only** and must not be added to `SKILL.md` files directly, as skills are designed to be cross-agent compatible (Codex, Cursor, Windsurf, etc.). Apply them locally in your own project's `.claude/skills/` overrides instead.
### Dynamic content injection with `!`command``
Claude Code supports embedding shell commands in SKILL.md using `` !`command` `` syntax. When the skill is invoked, Claude Code runs the command and injects the output inline: the model sees the result, not the instruction.
**Most useful application: auto-inject the product marketing context file**
Instead of every skill telling the agent "go check if `.agents/product-marketing-context.md` exists and read it," you can inject it automatically:
```markdown
Product context: !`cat .agents/product-marketing-context.md 2>/dev/null || echo "No product context file found. Ask the user about their product before proceeding."`
```
Place this at the top of a skill's body (after frontmatter) to make context available immediately without any file-reading step.
**Other useful injections:**
```markdown
# Inject today's date for recency-sensitive skills
Today's date: !`date +%Y-%m-%d`
# Inject current git branch (useful for workflow skills)
Current branch: !`git branch --show-current 2>/dev/null`
# Inject recent commits for context
Recent commits: !`git log --oneline -5 2>/dev/null`
```
**Why this is Claude Code-only**: Other agents that load skills will see the literal `` !`command` `` string rather than executing it, which would appear as garbled instructions. Keep cross-agent skill files free of this syntax.