skills: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This repository packages AI-agent skills for Postey — markdown skill definitions plus a zero-dependency Node.js CLI that agents invoke to draft, schedule, and manage social media posts. Multiple skills are planned; postey is the first.

Note: AGENTS.md is a symlink to this file; edits propagate.

Repository Layout

skills/  (repo: posteyai/skills)
├── .claude-plugin/
│   └── marketplace.json       — Marketplace catalog; a pack's entry IS its manifest (strict: false); the hub has its own plugin.json
├── .grok-plugin/
│   └── plugin.json            — Grok Build manifest; the whole repo is the plugin (xai-org/plugin-marketplace pins a commit of it)
├── .mcp.json                  — The hosted Postey MCP server for the Grok Build plugin; must match skills/postey/.mcp.json
├── .claude/
│   └── settings.json          — extraKnownMarketplaces for team auto-install
├── .github/workflows/
│   └── test.yml               — CI: node --test + check-versions + check-leaks (2 scopes) + check-setup-links + check-capability-overlap + check-doc-commands + refresh-capability-snapshot + check-mcp-tool-sync
├── scripts/
│   ├── lib/
│   │   ├── skills.js          — discoverSkills(): the single definition of "what counts as a skill". Every multi-skill check consumes this
│   │   └── cross-skill-links.js — reference scanner (markdown links + backtick refs) behind check-cross-skill-links.js
│   ├── check-versions.js      — CI: verify SKILL.md version == marketplace == pack.json == REGISTRY.md == README badge (per skill) == .codex-plugin == .cursor-plugin
│   ├── set-version.mjs        — write every version place from one argument (release step; --check to dry-run)
│   ├── check-release-tag.mjs  — CI on main: the released version's tag exists on the remote (rawBase pins it)
│   ├── check-cross-skill-links.js — CI: no skill may reference a file it does not ship
│   ├── check-doc-commands.js  — CI: verify every documented command exists in the CLI COMMANDS table
│   ├── check-mcp-tool-sync.js — CI: verify SKILL.md mcp-tools.tools: == MCP server registry
│   ├── check-leaks.js         — CI leak gate: hashed-denylist + secret-pattern scanner (`--hash` mode generates denylist entries)
│   └── leak-denylist.json     — Committed sha256 hashes (high-entropy terms only) + secret-shape patterns
├── tests/
│   ├── postey-cli.test.js     — node:test suite for postey CLI
│   ├── check-leaks.test.js    — leak-gate suite (synthetic secret-shaped fixtures; root tests/ is skip-listed in the scanner)
│   ├── skills-discovery.test.js — discoverSkills() against a 2-skill fixture
│   ├── cross-skill-links.test.js — reference gate: leak/dangling/history cases
│   ├── fixtures/              — synthetic skill trees for the two suites above
│   └── pack-manifest.test.js  — pack.json completeness + version + tag-pinned rawBase, per skill
├── templates/
│   └── skill/                 — Starter template for new skills (copy and fill in). Kept out of skills/ so whole-repo installers (Grok, Codex) don't ship it
└── skills/
    ├── REGISTRY.md            — Index of all skills in this repo
    └── postey/                — The postey skill (the hub)
        ├── .claude-plugin/plugin.json + .mcp.json — Claude directory plugin root (hub only)
        ├── .muse-plugin/plugin.json — Muse Code manifest: the skill plus the MCP server (hub only)
        ├── SKILL.md           — Authoritative skill spec (< 500 lines)
        ├── CHANGELOG.md       — User-facing changelog
        ├── command-reference.md — Full command table (loaded on demand)
        ├── routing-guide.md   — Extended CLI vs MCP routing reference
        ├── video-workflow.md  — Video transcription + cross-post workflow
        ├── prompts.md         — Platform caption generation templates
        ├── pack.json          — Fetch-install manifest (rawBase pinned to the release tag)
        ├── bootstrap-prompt.md — One-paste agent setup prompt
        ├── references/        — Content flows + playbooks (10 files, loaded on demand)
        └── scripts/
            ├── postey.js      — Main CLI (zero runtime deps, Node 18+)
            ├── videoUtils.js  — Video transcription + cross-post helpers
            └── mediaValidator.js — MIME validation