diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..27e3242 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Agent Skills Specification + url: https://agentskills.io/specification.md + about: Learn the skill format before creating or requesting a skill + - name: Contributing Guide + url: https://github.com/coreyhaines31/marketingskills/blob/main/CONTRIBUTING.md + about: How to contribute a new skill to this repository diff --git a/.github/ISSUE_TEMPLATE/skill-request.yml b/.github/ISSUE_TEMPLATE/skill-request.yml new file mode 100644 index 0000000..b9093fa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/skill-request.yml @@ -0,0 +1,74 @@ +name: Skill Request +description: Request a new marketing skill +title: "Skill Request: [skill-name]" +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new skill! Please fill out the details below. + + - type: input + id: skill-name + attributes: + label: Suggested skill name + description: Lowercase, hyphens only (e.g., "landing-page-audit") + placeholder: "my-skill-name" + validations: + required: true + + - type: textarea + id: description + attributes: + label: What should this skill do? + description: Describe the skill's purpose and capabilities + placeholder: "This skill should help with..." + validations: + required: true + + - type: textarea + id: triggers + attributes: + label: When should it be used? + description: What trigger phrases or scenarios should activate this skill? + placeholder: | + - When the user says "..." + - When working on... + validations: + required: true + + - type: textarea + id: examples + attributes: + label: Example use cases + description: Provide 1-3 specific examples of how you'd use this skill + placeholder: | + 1. I want to... + 2. Help me... + validations: + required: false + + - type: dropdown + id: category + attributes: + label: Category + description: Which category does this skill fit into? + options: + - CRO (Conversion Rate Optimization) + - Copywriting + - SEO + - Paid Ads + - Growth / Strategy + - Analytics + - Other + validations: + required: true + + - type: textarea + id: related-skills + attributes: + label: Related existing skills + description: Are there existing skills this relates to or differs from? + placeholder: "Similar to page-cro but focused on..." + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.md new file mode 100644 index 0000000..9298953 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md @@ -0,0 +1,15 @@ +## Documentation + +## Summary + + + +## Files changed + + + +## Checklist + +- [ ] Links are valid +- [ ] Formatting is consistent with existing docs +- [ ] No sensitive data or credentials diff --git a/.github/PULL_REQUEST_TEMPLATE/new-skill.md b/.github/PULL_REQUEST_TEMPLATE/new-skill.md new file mode 100644 index 0000000..b77ae6a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/new-skill.md @@ -0,0 +1,16 @@ +## New Skill + +**Skill name:** `skills/SKILL-NAME` + +## Summary + + + +## 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 +- [ ] Tested locally with AI agent diff --git a/.github/PULL_REQUEST_TEMPLATE/skill-update.md b/.github/PULL_REQUEST_TEMPLATE/skill-update.md new file mode 100644 index 0000000..6e3e1d9 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/skill-update.md @@ -0,0 +1,21 @@ +## Skill Update + +**Skill:** `skills/SKILL-NAME` + +## Summary + + + +## Type of update + +- [ ] Bug fix +- [ ] Improved instructions +- [ ] Added references/scripts +- [ ] Other + +## Checklist + +- [ ] Changes are focused and minimal +- [ ] `SKILL.md` is still under 500 lines +- [ ] No sensitive data or credentials +- [ ] Tested locally with AI agent diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5a4c1ce --- /dev/null +++ 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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6bc51a8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ +# Contributing + +Thanks for your interest in contributing to Marketing Skills! This guide will help you add new skills or improve existing ones. + +## Requesting a Skill + +You can also suggest new skills by [opening a skill request](https://github.com/coreyhaines31/marketingskills/issues/new?template=skill-request.yml). + +## Adding a New Skill + +### 1. Create the skill directory + +```bash +mkdir -p skills/your-skill-name +``` + +### 2. Create the SKILL.md file + +Every skill needs a `SKILL.md` file with YAML frontmatter: + +```yaml +--- +name: your-skill-name +description: When to use this skill. Include trigger phrases and keywords that help agents identify relevant tasks. +license: MIT +metadata: + author: "[Your Name](https://your-website.com)" + version: "1.0.0" +--- + +# Your Skill Name + +Instructions for the agent go here... +``` + +### 3. Follow the naming conventions + +- **Directory name**: lowercase, hyphens only (e.g., `email-sequence`) +- **Name field**: must match directory name exactly +- **Description**: 1-1024 characters, include trigger phrases + +### 4. Structure your skill + +``` +skills/your-skill-name/ +├── SKILL.md # Required - main instructions +├── references/ # Optional - additional documentation +│ └── guide.md +├── scripts/ # Optional - executable code +│ └── helper.py +└── assets/ # Optional - templates, images, data + └── template.json +``` + +### 5. Write effective instructions + +- Keep `SKILL.md` under 500 lines +- Move detailed reference material to `references/` +- Include step-by-step instructions +- Add examples of inputs and outputs +- Cover common edge cases + +## Improving Existing Skills + +1. Read the existing skill thoroughly +2. Test your changes locally +3. Keep changes focused and minimal +4. Update the version in metadata if making significant changes + +## Submitting Your Contribution + +1. Fork the repository +2. Create a feature branch (`git checkout -b feat/new-skill-name`) +3. Make your changes +4. Test locally with an AI agent +5. Submit a pull request using the appropriate template: + - [New Skill](?template=new-skill.md) + - [Skill Update](?template=skill-update.md) + - [Documentation](?template=documentation.md) + +## Skill Quality Checklist + +- [ ] `name` matches directory name +- [ ] `description` clearly explains when to use the skill +- [ ] Instructions are clear and actionable +- [ ] No sensitive data or credentials +- [ ] Follows existing skill patterns in the repo + +## Questions? + +Open an issue if you have questions or need help with your contribution. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7c48dd6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Corey Haines + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index d12375f..fb8589d 100644 --- a/README.md +++ b/README.md @@ -166,41 +166,8 @@ You can also invoke skills directly: Found a way to improve a skill? Have a new skill to suggest? PRs and issues welcome! -**Ideas for contributions:** -- Improve existing skill instructions or frameworks -- Add new experiment ideas or best practices -- Fix typos or clarify confusing sections -- Suggest new skills (open an issue first to discuss) -- Add examples or case studies - -**How to contribute:** -1. Fork the repo -2. Edit the skill file(s) -3. Submit a PR with a clear description of what you improved - -### Skill File Structure - -Each skill is a directory containing a `SKILL.md` file: - -``` -skills/ - skill-name/ - SKILL.md -``` - -The `SKILL.md` file follows this format: - -```markdown ---- -name: skill-name -description: One-line description for skill selection ---- - -# Skill Name - -[Full instructions for the AI agent] -``` +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding or improving skills. ## License -MIT - Use these however you want. +[MIT](LICENSE) - Use these however you want.