Immutable. This exact content is served forever at /api/v1/blob/f22af34e4a55e091.
# Social Media Skills — Agent Guidelines
## Repository Overview
Social media skills for AI agents — 14 skills across strategy, creation, and analysis for text-first platforms (LinkedIn, Twitter/X, Threads, Bluesky).
Each skill lives in `skills/<name>/SKILL.md` and provides structured guidance for AI agents performing social media tasks.
## Skill Organization
Skills are organized into four layers, each building on the previous.
### Foundation
- **social-media-context-sms** — establishes shared context, platform knowledge, and user preferences used by all other skills
### Strategy
- **content-strategy-sms** — defines content pillars, audience targeting, and positioning
- **content-calendar-sms** — plans publishing cadence, themes, and scheduling across platforms
- **platform-strategy-sms** — tailors approach per platform based on audience and format strengths
### Creation
- **post-writer-sms** — writes single standalone posts optimized per platform
- **thread-writer-sms** — writes multi-post threads with narrative arc and strong hooks
- **carousel-writer-sms** — writes slide-by-slide carousel scripts for LinkedIn and similar formats
- **content-repurposer-sms** — transforms existing content into new formats and platforms
- **hook-writer-sms** — crafts high-performing opening lines to maximize engagement
### Analysis
- **performance-analyzer-sms** — interprets post and account metrics to surface insights
- **audience-growth-tracker-sms** — tracks follower trends and identifies growth drivers
- **content-pattern-analyzer-sms** — identifies what content types and topics perform best
- **optimization-advisor-sms** — recommends specific improvements based on data patterns
## Key Conventions
### YAML Frontmatter
Every `SKILL.md` must open with YAML frontmatter containing:
- `name`: kebab-case skill identifier (1–64 chars)
- `description`: plain-English summary of what the skill does (1–1024 chars)
- `metadata.version`: semver string (e.g. `"1.0.0"`)
### Naming
- **kebab-case** for all skill directory and file names
- Lowercase, alphanumeric characters and hyphens only
- No spaces, underscores, or special characters
### File Size
- Each `SKILL.md` must be **under 500 lines**
- Keep instructions focused; link to related skills rather than duplicating guidance
### Writing Style
- **Active voice** throughout — tell the agent what to do, not what might happen
- **Clarity over cleverness** — straightforward language is more reliable than clever phrasing
- **Bold key terms** when first introduced or when emphasis aids scanning
- Short paragraphs and bullet lists over dense prose
## Foundation Dependency
All skills (except `social-media-context-sms` itself) **check for `.agents/social-media-context-sms.md` first** before proceeding. This file contains user-specific context: platforms used, audience description, content pillars, tone preferences, and account handles.
If `.agents/social-media-context-sms.md` is not present, the skill should prompt the agent to run `social-media-context-sms` first, or proceed with reasonable defaults while noting the limitation.
## BlackTwist MCP Integration
**BlackTwist** is the primary tool integration for this skill set. It provides an MCP server with tools for posting, scheduling, and analytics across supported platforms.
- **When BlackTwist MCP is available**: use its tools directly for all posting, scheduling, and analytics operations
- **When BlackTwist MCP is not available**: fall back to advisory mode — output the content and instructions for the user to post manually; note what metrics to check and where to find them
Skills should detect MCP availability by attempting a lightweight call (e.g. `get_user_settings`) and adapting behavior accordingly.
See `tools/REGISTRY.md` for the full list of available BlackTwist tools.
## Cross-References
Skills should reference related skills where relevant. Use the format:
```
See also: **thread-writer-sms**, **hook-writer-sms**
```
Common cross-reference patterns:
- Creation skills reference **hook-writer-sms** for opening lines
- Creation skills reference **content-strategy-sms** for pillar alignment
- Analysis skills reference **optimization-advisor-sms** for next steps
- **content-repurposer-sms** references all creation skills as output targets
## Validation
Run `./validate-skills.sh` to check all skills against conventions before committing.
## Releasing
Follow these steps when creating a new release:
1. **Bump the version** in `metadata.version` inside each changed skill's `SKILL.md` frontmatter. Use semver: patch for fixes, minor for new features or improvements, major for breaking changes.
2. **Commit and push** the version bump to `main`.
3. **Build zip files** — one per skill, each containing only that skill's `SKILL.md`:
```bash
mkdir -p releases
for dir in skills/*/; do
name=$(basename "$dir")
zip -j "releases/$name.zip" "$dir"SKILL.md
done
```
4. **Create the GitHub release** with `gh`:
```bash
gh release create vX.Y.Z --title "Social Media Skills vX.Y.Z" --notes "Release notes here"
```
5. **Upload all zip files** to the release:
```bash
gh release upload vX.Y.Z releases/audience-growth-tracker-sms.zip releases/carousel-writer-sms.zip releases/content-calendar-sms.zip releases/content-pattern-analyzer-sms.zip releases/content-repurposer-sms.zip releases/content-strategy-sms.zip releases/hook-writer-sms.zip releases/optimization-advisor-sms.zip releases/performance-analyzer-sms.zip releases/platform-strategy-sms.zip releases/post-writer-sms.zip releases/social-media-context-sms.zip releases/thread-writer-sms.zip
```
The `releases/` directory is gitignored — zip files are only attached to GitHub releases, not committed to the repo.