feat: add repo scaffolding — root files, plugin manifest, validation script, tools registry

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-09-19 05:44:19 +08:00 · 2026-03-20 23:51:10 +01:00
commit e37149082c
8 changed files with 545 additions and 0 deletions
@@ -0,0 +1,22 @@
+{
+  "name": "social-media-skills",
+  "owner": "threads-power-tool",
+  "version": "1.0.0",
+  "description": "Social media skills for AI agents — content strategy, creation, and analysis for LinkedIn, Twitter/X, Threads, and Bluesky",
+  "skills": [
+    "social-media-context",
+    "content-strategy",
+    "content-calendar",
+    "platform-strategy",
+    "post-writer",
+    "thread-writer",
+    "carousel-writer",
+    "content-repurposer",
+    "hook-writer",
+    "performance-analyzer",
+    "audience-growth-tracker",
+    "content-pattern-analyzer",
+    "optimization-advisor"
+  ],
+  "strict": false
+}
@@ -0,0 +1,8 @@
+node_modules/
+.env
+.env.*
+!.env.example
+.DS_Store
+*.swp
+.idea/
+.vscode/
@@ -0,0 +1,108 @@
+# 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/
+│   │   └── SKILL.md
+│   ├── content-strategy/
+│   │   └── 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`)
+- 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`
+- `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`.
@@ -0,0 +1,90 @@
+# 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** — establishes shared context, platform knowledge, and user preferences used by all other skills
+
+### Strategy
+- **content-strategy** — defines content pillars, audience targeting, and positioning
+- **content-calendar** — plans publishing cadence, themes, and scheduling across platforms
+- **platform-strategy** — tailors approach per platform based on audience and format strengths
+
+### Creation
+- **post-writer** — writes single standalone posts optimized per platform
+- **thread-writer** — writes multi-post threads with narrative arc and strong hooks
+- **carousel-writer** — writes slide-by-slide carousel scripts for LinkedIn and similar formats
+- **content-repurposer** — transforms existing content into new formats and platforms
+- **hook-writer** — crafts high-performing opening lines to maximize engagement
+
+### Analysis
+- **performance-analyzer** — interprets post and account metrics to surface insights
+- **audience-growth-tracker** — tracks follower trends and identifies growth drivers
+- **content-pattern-analyzer** — identifies what content types and topics perform best
+- **optimization-advisor** — 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` itself) **check for `.agents/social-media-context.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.md` is not present, the skill should prompt the agent to run `social-media-context` 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**, **hook-writer**
+```
+
+Common cross-reference patterns:
+- Creation skills reference **hook-writer** for opening lines
+- Creation skills reference **content-strategy** for pillar alignment
+- Analysis skills reference **optimization-advisor** for next steps
+- **content-repurposer** references all creation skills as output targets
+
+## Validation
+
+Run `./validate-skills.sh` to check all skills against conventions before committing.
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Social Media Skills Contributors
+
+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.
@@ -0,0 +1,80 @@
+# Social Media Skills
+
+AI agent skills for social media content strategy, creation, and analysis across text-first platforms.
+
+## Skill Catalog
+
+### Foundation
+| Skill | Description |
+|---|---|
+| [social-media-context](skills/social-media-context/) | Captures platform context, audience details, content pillars, and tone preferences used by all other skills |
+
+### Strategy
+| Skill | Description |
+|---|---|
+| [content-strategy](skills/content-strategy/) | Defines content pillars, audience targeting, and positioning for consistent brand voice |
+| [content-calendar](skills/content-calendar/) | Plans publishing cadence, themes, and scheduling across platforms |
+| [platform-strategy](skills/platform-strategy/) | Tailors content approach per platform based on audience and format strengths |
+
+### Creation
+| Skill | Description |
+|---|---|
+| [post-writer](skills/post-writer/) | Writes single standalone posts optimized for each platform's format and audience |
+| [thread-writer](skills/thread-writer/) | Writes multi-post threads with a clear narrative arc and strong opening hook |
+| [carousel-writer](skills/carousel-writer/) | Writes slide-by-slide carousel scripts for LinkedIn and similar visual formats |
+| [content-repurposer](skills/content-repurposer/) | Transforms existing content into new formats and adapts it across platforms |
+| [hook-writer](skills/hook-writer/) | Crafts high-performing opening lines to maximize engagement and stop-the-scroll |
+
+### Analysis
+| Skill | Description |
+|---|---|
+| [performance-analyzer](skills/performance-analyzer/) | Interprets post and account metrics to surface actionable insights |
+| [audience-growth-tracker](skills/audience-growth-tracker/) | Tracks follower trends and identifies the content driving growth |
+| [content-pattern-analyzer](skills/content-pattern-analyzer/) | Identifies which content types, topics, and formats perform best |
+| [optimization-advisor](skills/optimization-advisor/) | Recommends specific improvements based on performance data and patterns |
+
+## Installation
+
+### Claude Code plugin (recommended)
+
+```bash
+claude plugin add threads-power-tool/social-media-skills
+```
+
+### Git submodule
+
+```bash
+git submodule add https://github.com/threads-power-tool/social-media-skills .claude/skills/social-media-skills
+```
+
+### Git clone
+
+```bash
+git clone https://github.com/threads-power-tool/social-media-skills .claude/skills/social-media-skills
+```
+
+## Supported Platforms
+
+- **LinkedIn** — long-form posts, carousels, newsletters
+- **Twitter/X** — posts, threads, spaces
+- **Threads** — posts, threads (Meta)
+- **Bluesky** — posts, threads, starter packs
+
+## Tool Integrations
+
+### BlackTwist (primary)
+
+[BlackTwist](https://blacktwist.app) is the recommended MCP integration for this skill set. When the BlackTwist MCP server is connected to your Claude environment, skills use it directly for:
+
+- Publishing and scheduling posts
+- Fetching analytics and engagement data
+- Managing drafts and queued content
+- Tracking follower growth
+
+When BlackTwist is not available, skills fall back to advisory mode — generating content and instructions for manual posting.
+
+See [tools/REGISTRY.md](tools/REGISTRY.md) for the full tool reference.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
@@ -0,0 +1,98 @@
+# Tool Integrations Registry
+
+This document lists all tool integrations available to skills in this repository.
+
+## BlackTwist (Primary)
+
+**BlackTwist** is the primary MCP integration for posting, scheduling, and analytics. When the BlackTwist MCP server is connected, skills use it directly rather than falling back to advisory mode.
+
+MCP server identifier: `mcp__blacktwist`
+
+### Content Management
+
+Tools for creating, editing, retrieving, and deleting content.
+
+| Tool | Description |
+|---|---|
+| `create_post` | Create and publish a new post or thread |
+| `edit_post` | Edit a single post (standalone or within a thread) |
+| `edit_thread` | Edit an entire thread, including post order and content |
+| `get_thread` | Retrieve a thread by ID, including all posts and metadata |
+| `delete_thread` | Delete a thread and all its posts |
+| `list_posts` | List published posts with optional filters |
+| `list_drafts` | List saved drafts pending review or scheduling |
+
+### Analytics
+
+Tools for fetching performance data, metrics, and growth insights.
+
+| Tool | Description |
+|---|---|
+| `get_post_analytics` | Fetch engagement metrics for a specific post (views, likes, replies, reposts) |
+| `get_live_metrics` | Fetch real-time metrics for recently published content |
+| `get_metric_timeseries` | Retrieve metric data over a time range for trend analysis |
+| `get_follower_growth` | Fetch follower count history and net growth over time |
+| `get_consistency` | Check posting consistency score and streak data |
+| `get_daily_recap` | Get a daily summary of account activity and performance |
+| `get_recommendations` | Fetch AI-generated recommendations based on recent performance |
+
+### Scheduling
+
+Tools for managing publish times and scheduled content.
+
+| Tool | Description |
+|---|---|
+| `list_time_slots` | List optimal or available publishing time slots |
+| `reschedule_thread` | Move a scheduled thread to a new publish time |
+| `get_thread_follow_up` | Retrieve the follow-up action configured for a thread |
+| `set_thread_follow_up` | Set a follow-up action (e.g. reply, repost) to trigger after publishing |
+
+### Account
+
+Tools for account configuration, team, and subscription management.
+
+| Tool | Description |
+|---|---|
+| `get_user_settings` | Retrieve user preferences and account configuration |
+| `list_teams` | List teams and members associated with the account |
+| `get_subscription` | Retrieve current subscription plan and limits |
+| `list_providers` | List connected platform accounts (LinkedIn, Twitter/X, Threads, Bluesky) |
+
+---
+
+## Third-Party Scheduling Tools (Reference Only)
+
+These tools are not directly integrated but may be relevant when BlackTwist is unavailable.
+
+### Buffer
+
+- **Website**: https://buffer.com
+- **Capabilities**: Multi-platform scheduling, analytics, team collaboration
+- **API**: REST API available for programmatic access
+
+### Hootsuite
+
+- **Website**: https://hootsuite.com
+- **Capabilities**: Enterprise scheduling, monitoring, analytics dashboards
+- **API**: REST API available; MCP integration not available
+
+### Later
+
+- **Website**: https://later.com
+- **Capabilities**: Visual content calendar, link-in-bio, Instagram-focused
+- **API**: REST API available for scheduling and media management
+
+---
+
+## Platform Native Analytics (Manual Fallback)
+
+When no analytics tool is available, direct users to platform-native analytics:
+
+| Platform | Analytics Location |
+|---|---|
+| **LinkedIn** | Profile > Analytics (for personal) or Page Admin > Analytics (for pages) |
+| **Twitter/X** | Analytics.twitter.com or per-post analytics via the ellipsis menu |
+| **Threads** | Profile > Insights (requires Creator account or 100+ followers) |
+| **Bluesky** | Limited native analytics; use third-party tools like Clearsky or Bluesky Stats |
+
+Key metrics to collect manually: impressions/views, likes, replies, reposts/shares, profile visits, follower count change.
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# validate-skills.sh — validates all skills in skills/ against conventions
+
+set -euo pipefail
+
+SKILLS_DIR="$(dirname "$0")/skills"
+PASS=0
+WARN=0
+FAIL=0
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+RESET='\033[0m'
+
+pass() { echo -e "${GREEN}  ✓ $1${RESET}"; ((PASS++)); }
+warn() { echo -e "${YELLOW}  ⚠️  $1${RESET}"; ((WARN++)); }
+fail() { echo -e "${RED}  ❌ $1${RESET}"; ((FAIL++)); }
+
+if [[ ! -d "$SKILLS_DIR" ]]; then
+  echo -e "${YELLOW}No skills/ directory found — nothing to validate.${RESET}"
+  exit 0
+fi
+
+skill_dirs=("$SKILLS_DIR"/*/SKILL.md)
+
+if [[ ${#skill_dirs[@]} -eq 0 ]] || [[ ! -f "${skill_dirs[0]}" ]]; then
+  echo -e "${YELLOW}No SKILL.md files found in skills/ — nothing to validate.${RESET}"
+  exit 0
+fi
+
+for skill_file in "$SKILLS_DIR"/*/SKILL.md; do
+  [[ -f "$skill_file" ]] || continue
+
+  skill_name="$(basename "$(dirname "$skill_file")")"
+  echo
+  echo "Validating: $skill_name"
+
+  # --- Frontmatter exists ---
+  if ! head -1 "$skill_file" | grep -q '^---'; then
+    fail "Missing YAML frontmatter (file must start with ---)"
+    continue
+  fi
+
+  # Extract frontmatter block (between first and second ---)
+  frontmatter="$(awk '/^---/{count++; if(count==2) exit; next} count==1' "$skill_file")"
+
+  # --- name field ---
+  name_value="$(echo "$frontmatter" | grep '^name:' | sed 's/^name:[[:space:]]*//' | tr -d '"'"'" | head -1)"
+
+  if [[ -z "$name_value" ]]; then
+    fail "Missing 'name' field in frontmatter"
+  else
+    name_len=${#name_value}
+    if [[ $name_len -lt 1 || $name_len -gt 64 ]]; then
+      fail "name '$name_value' is $name_len chars — must be 1–64"
+    elif ! echo "$name_value" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$'; then
+      fail "name '$name_value' is not valid kebab-case (lowercase alphanumeric and hyphens only)"
+    else
+      pass "name '$name_value' is valid kebab-case ($name_len chars)"
+    fi
+
+    if [[ "$name_value" != "$skill_name" ]]; then
+      warn "name '$name_value' does not match directory name '$skill_name'"
+    fi
+  fi
+
+  # --- description field ---
+  desc_value="$(echo "$frontmatter" | grep '^description:' | sed 's/^description:[[:space:]]*//' | tr -d '"'"'" | head -1)"
+
+  if [[ -z "$desc_value" ]]; then
+    fail "Missing 'description' field in frontmatter"
+  else
+    desc_len=${#desc_value}
+    if [[ $desc_len -lt 1 ]]; then
+      fail "description is empty"
+    elif [[ $desc_len -gt 1024 ]]; then
+      fail "description is $desc_len chars — must be 1–1024"
+    else
+      pass "description is $desc_len chars (within 1–1024)"
+    fi
+  fi
+
+  # --- metadata.version field ---
+  version_value="$(echo "$frontmatter" | grep -A5 '^metadata:' | grep 'version:' | sed 's/.*version:[[:space:]]*//' | tr -d '"'"'" | head -1)"
+
+  if [[ -z "$version_value" ]]; then
+    warn "Missing metadata.version in frontmatter"
+  elif ! echo "$version_value" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+    warn "metadata.version '$version_value' does not look like semver (e.g. 1.0.0)"
+  else
+    pass "metadata.version '$version_value' looks like semver"
+  fi
+
+  # --- File size ---
+  line_count="$(wc -l < "$skill_file" | tr -d ' ')"
+  if [[ $line_count -gt 500 ]]; then
+    fail "File is $line_count lines — must be under 500"
+  elif [[ $line_count -gt 450 ]]; then
+    warn "File is $line_count lines — approaching 500-line limit"
+  else
+    pass "File is $line_count lines (under 500)"
+  fi
+
+done
+
+echo
+echo "----------------------------------------"
+echo -e "Results: ${GREEN}${PASS} passed${RESET}  ${YELLOW}${WARN} warnings${RESET}  ${RED}${FAIL} failed${RESET}"
+echo
+
+if [[ $FAIL -gt 0 ]]; then
+  echo -e "${RED}Validation failed — fix errors before committing.${RESET}"
+  exit 1
+else
+  echo -e "${GREEN}All checks passed.${RESET}"
+  exit 0
+fi