AGENTS.md

Task Completion Requirements

• bun run validate and bun run check must pass before considering tasks completed.

What this is

Social media skills for AI Agents. It learn your strategy, voice and platform-native format — posts, threads, carousels, reels-ready scripts, ad copy, calendars.

A general, vendor-neutral social-media content skills for any AI agent. Skills live in skills/<name>/SKILL.md (flat — no category folders; categories live in frontmatter and the README table).

Commands

• bun run validate — frontmatter schema + agentskills.io hard limits (name ≤ 64 chars, description ≤ 1024), description discovery rules, purity lint across every bundled file (SKILL.md + references//scripts//evals/), cross-repo name-collision check, relative-link resolution, and eval-shape lint.
• bun run validate:spec — cross-check every skill with the canonical skills-ref validator. Runs via uvx/skills-ref when available; soft-skips (exit 0) otherwise, since it is a demonstration-grade tool, and tolerates top-level Claude Code frontmatter fields it doesn't know (e.g. disable-model-invocation; see CLAUDE_CODE_EXTRA_FIELDS in the script). validate is the production gate.
• bun run format / bun run format:check — Prettier (write / check). Generated JSON and the README skill table are excluded so the generator stays their sole authority.
• bun run build:index — regenerate skills-index.json, the README skill table, and the Claude Code plugin manifests (.claude-plugin/plugin.json + marketplace.json, sourced from repo.config.json + package.json). Commit all of them.
• bun run check — validate + validate:spec + format:check + drift-check (what CI runs).
• bun run zips — package per-skill zips into dist/zips/.

Rules that gate every change

1. Purity (the community-protection principle): no skill file — SKILL.md, references/, scripts/, or evals/ — may mention Inklate, MCP, scheduling APIs, or any provider integration. The README is the ONLY funnel surface in this repo. CI greps every bundled file; reviewers enforce the spirit.
2. Descriptions are discovery. 3–8 sentences, ≤ 1024 characters (spec limit), ≥ 4 literal trigger phrases in quotes, platform names spelled out, and a mention of social-context.md. The description is the only signal agents use to auto-trigger.
3. Frontmatter contract: name (lowercase-hyphen slug ≤ 64 chars, = folder name), description (≤ 1024), optional license and compatibility (agentskills.io spec fields), and metadata.{version (semver), category (Foundation | Create | Ads | Plan | Check), topics (slug list), examplePrompt}. Write YAML in block style — no flow arrays like topics: [a, b] — so the canonical skills-ref validator accepts it.
4. Body shape: context load → workflow → quality bar → deliverable, ending at the deliverable. A workflow step must check the output against the Quality bar before the deliverable — the bar is a gate, not a passive table. Skills that read social-context.md name the sections they read by exact ## heading (the Foundation schema: Positioning, Audience, Platforms, Pillars, Voice, Cadence, Goals, Never). A skill may bundle references/, scripts/, and evals/; name them from SKILL.md with relative paths, and load heavy reference data on demand (progressive disclosure). social-check is the worked example.
5. Self-contained / portable. Skills install individually (via skills.sh and the per-skill zips), so a skill may reference only files inside its own directory — never another skill's files.
6. Evals. Each skill should ship evals/evals.json (agentskills.io format: skill_name, evals[] with id / prompt / expected_output / assertions). bun run validate lints their shape.
7. Names must not collide with inklate/skills (both repos install into one skills directory). The validator cross-checks the sibling index when reachable.
8. Scope fence: social only (organic + paid). No SEO/email/CRO skills.
9. Naming & shared language. Skill names use a domain-first social-* family, with platform a constraint in references/, not a name (idk, the user-invoked router, is a deliberate exception). Shared domain terms live in CONTEXT.md; use them. The idk router maps the family — whenever you add, rename, or remove a skill, update idk's Skill map so it never routes to a skill that moved or omits one that exists.

After editing any skill, run bun run check before committing; skills-index.json, the README table, and the .claude-plugin/ manifests are build artifacts that must stay in sync (CI fails on drift).