chore: add repo essentials and GitHub templates

- Add MIT LICENSE file - Add CONTRIBUTING.md with skill creation guide - Add AGENTS.md and CLAUDE.md for AI agent guidelines - Add issue template for skill requests - Add PR templates for new skills, updates, and docs - Update README with links to contributing guide and license
2026-01-26 09:37:57 +11:00
parent 21f0ce7f6e
commit 6406f9e89b
10 changed files with 406 additions and 35 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,157 @@
+# 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). It also serves as a **Claude Code plugin marketplace** via `.claude-plugin/marketplace.json`.
+
+- **Name**: Marketing Skills
+- **GitHub**: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
+- **Creator**: Corey Haines
+- **License**: MIT
+
+## Repository Structure
+
+```
+marketingskills/
+├── .claude-plugin/
+│   └── marketplace.json   # Claude Code plugin marketplace manifest
+├── skills/                # Agent Skills
+│   └── skill-name/
+│       └── SKILL.md       # Required skill file
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
+
+## Build / Lint / Test Commands
+
+**Not applicable** - This is a content-only repository with no executable code.
+
+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.
+---
+```
+
+### 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
+
+### 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.
+```
+
+## Claude Code Plugin
+
+This repo also serves as a plugin marketplace. The manifest at `.claude-plugin/marketplace.json` lists all skills for installation via:
+
+```bash
+/plugin marketplace add coreyhaines31/marketingskills
+/plugin install marketing-skills
+```
+
+See [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins.md) for details.
+
+## Git Workflow
+
+### Branch Naming
+
+- New skills: `feat/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 sensitive data or credentials
+
+## 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.