6 added, 6 removed. Audit A to A.
# Agent Skills Specification
This document defines the conventions and requirements for skills in this repository.
## Repository Structure
```
social-media-skills/
├── .claude-plugin/
│ └── marketplace.json # Plugin manifest
├── skills/
- │ ├── social-media-context/
+ │ ├── social-media-context-sms/
│ │ └── SKILL.md
- │ ├── content-strategy/
+ │ ├── content-strategy-sms/
│ │ └── SKILL.md
│ └── <skill-name>/
│ └── SKILL.md
├── tools/
│ └── REGISTRY.md # Tool integrations registry
├── AGENTS.md # This file
├── CLAUDE.md # Agent guidelines
├── LICENSE
├── README.md
└── validate-skills.sh # Validation script
```
Skills are grouped by layer in `skills/` but have no required subdirectory structure beyond `<skill-name>/SKILL.md`.
## Skill Requirements
### YAML Frontmatter
Every `SKILL.md` must begin with a YAML frontmatter block:
```yaml
---
name: skill-name
description: One to three sentence description of what this skill does and when to use it.
metadata:
version: "1.0.0"
---
```
Field constraints:
| Field | Type | Constraints |
|---|---|---|
| `name` | string | 1–64 characters, kebab-case |
| `description` | string | 1–1024 characters |
| `metadata.version` | string | semver format (e.g. `"1.0.0"`) |
### Naming Conventions
- **Lowercase only** — no uppercase letters anywhere in skill names or directory names
- **Alphanumeric and hyphens only** — no spaces, underscores, dots, or special characters
- - **Kebab-case** — words separated by single hyphens (e.g. `hook-writer`, not `hookwriter` or `hook_writer`)
+ - **Kebab-case** — words separated by single hyphens (e.g. `hook-writer-sms`, not `hookwriter` or `hook_writer`)
- The `name` field in frontmatter must match the directory name exactly
### File Size
- Each `SKILL.md` must be **under 500 lines**
- If a skill grows beyond this limit, split guidance into focused sub-sections or extract repeated patterns into shared references
### Content Structure
A well-formed `SKILL.md` should include:
1. YAML frontmatter (required)
2. A brief purpose statement
3. Inputs — what context or parameters the skill expects
4. Steps — numbered or structured instructions the agent follows
5. Outputs — what the skill produces
6. Examples (optional but encouraged)
7. See also — links to related skills
## Git Workflow
Use **conventional commits** for all changes to this repository:
| Prefix | When to use |
|---|---|
| `feat:` | Adding a new skill or significant new capability |
| `fix:` | Correcting errors in skill instructions or metadata |
| `update:` | Improving or expanding an existing skill |
| `docs:` | Changes to README, AGENTS.md, CLAUDE.md, or other docs |
| `chore:` | Tooling, config, or maintenance changes |
Example commit messages:
- - `feat: add hook-writer skill`
- - `update: expand platform-strategy with Bluesky guidance`
- - `fix: correct frontmatter version field in post-writer`
+ - `feat: add hook-writer-sms skill`
+ - `update: expand platform-strategy-sms with Bluesky guidance`
+ - `fix: correct frontmatter version field in post-writer-sms`
- `chore: update validate-skills.sh to check metadata.version`
## Validation
Run the validation script before committing:
```bash
./validate-skills.sh
```
The script checks:
- YAML frontmatter exists with `name` and `description`
- `name` is kebab-case and within 1–64 characters
- `description` is within 1–1024 characters
- File is under 500 lines
All checks must pass before merging to `main`.