skills

# Skills — personal Agent Skills library

> A library of reusable Agent Skills for Claude Code, opencode, and other AI coding tools. Each skill is a self-contained folder under `skills/` with a `SKILL.md` (frontmatter: name, description, category, effort, domain + instructions). The agentic skills compose: primitives (Verify, Reflect) are called by drivers (Iterate, Orchestrate, Research); meta skills (CreateSkill, SkillForge) build and audit the library.

## How to consume this repo (for AI agents)

- **One-shot machine-readable index:** [skills.json](skills.json) — every skill's name, path, category, effort, domain, tier, tuned_for (model generation it was last tuned against), workflows, and description as JSON. Parse this instead of opening every file.
- **Per skill:** read `<SkillName>/SKILL.md` — the `description` field states WHAT it does + WHEN to use it; the `## Workflow Routing` table maps intents to `Workflows/*.md`; `## Gotchas` holds the highest-density failure knowledge; `## Examples` shows trigger->action.
- **System model:** [rules/system.md](rules/system.md) — tier model (A/B/C/D), frontmatter contract, composition graph, state + telemetry conventions.
- **Composed workflows:** [workflows/index.md](workflows/index.md) — an OKF bundle of multi-skill chains for full jobs (build & ship, maintain the library); each chain is one markdown concept with YAML frontmatter (`type: Workflow`, `chain`, `tags`). `skills.json` also carries a `workflows` array with each chain's `title`, `chain`, `tags`, and `summary`.

## Skills by category

### workflow
- [AdaptiveExplainers](skills/AdaptiveExplainers/SKILL.md) — Choose and verify text, diagrams, interactive HTML, or video when explaining a topic, system, investigation, or decision.
- [Build](skills/Build/SKILL.md) — Implements plan tasks one at a time with compile and commit gates. USE WHEN building from a plan.
- [CodebaseOnboarding](skills/CodebaseOnboarding/SKILL.md) — Analyze an unfamiliar codebase and produce an onboarding guide — architecture map, entry points, conventions, starter CLAUDE.md. USE WHEN joining a new project or onboarding a repo.
- [DataReportBuilder](skills/DataReportBuilder/SKILL.md) — Turn a raw Excel/CSV dataset into a two-layer report — plain-language summary plus untouched raw data. USE WHEN someone shares a spreadsheet wanting a report, analysis, summary, or breakdown.
- [Email](skills/Email/SKILL.md) — Use when drafting, replying to, reviewing, or localizing email. Apply owner language policy, native templates, tone rules, and lint. Drafts only; never sends. NOT FOR social posts (use SocialPost).
- [GitHubOps](skills/GitHubOps/SKILL.md) — Manage a GitHub repo via the gh CLI — hygiene, changelog, commit/push, PRs, releases, branch cleanup. USE WHEN clean up the repo, update the changelog, commit/push, open a PR, or cut a release. NOT FOR git branching/merge theory (use GitWorkflow).
- [Iterate](skills/Iterate/SKILL.md) — Bounded multi-pass loop: improve mode (one change per pass, Verify + Reflect, inline or wake-driven) or analysis mode (--lenses, read-only). USE WHEN iterate, refine, keep improving, or explore deeper.
- [MacPluginPlaybook](skills/MacPluginPlaybook/SKILL.md) — Phased playbook to build or port a native SwiftUI macOS menu bar app. USE WHEN starting or porting a macOS menu bar plugin. NOT FOR one view's styling (use MacUX).
- [Orchestrate](skills/Orchestrate/SKILL.md) — Decompose a spec into a dependency DAG, build units in parallel via delegation, review each in a separate context. USE WHEN orchestrating multi-unit or parallel work, or landing a spec.
- [Research](skills/Research/SKILL.md) — Research a question at three depths (quick / standard / deep multi-agent fan-out), then synthesize cited findings. USE WHEN researching a topic, gathering sources, comparing options, or getting a cross-provider second opinion.
- [Robinhood](skills/Robinhood/SKILL.md) — Reverse-engineer local app feature gates and build scoped test copies. USE WHEN investigating Pro locks or local-model restrictions. NOT FOR cloud authorization or supported Superwhisper rebuilds (use SuperwhisperLocalModels).
- [SocialPost](skills/SocialPost/SKILL.md) — Write, rewrite, repurpose, localize, and review social posts in English and Hebrew. USE WHEN drafting or checking a post, tweet, thread, caption, or comment (פוסט). NOT FOR email (use Email).
- [Spec](skills/Spec/SKILL.md) — Explores code and project memory, then writes acceptance criteria. USE WHEN defining what to build before planning.
- [SuperwhisperLocalModels](skills/SuperwhisperLocalModels/SKILL.md) — Inspect and rebuild Superwhisper local-model test copies. USE WHEN restoring Cohere, Parakeet, or S1-mini after updates. NOT FOR general reverse engineering (use Robinhood), cloud access, or license activation.
- [Test](skills/Test/SKILL.md) — Runs test-first development for features and bug fixes. USE WHEN writing tests first, testing a new feature, or fixing a bug with a failing test.
- [Workflows](skills/Workflows/SKILL.md) — Index of composed skill chains: which skills to run in what order for a full job. USE WHEN combining skills or asked 'what's the workflow for X'.

### quality
- [Hygiene](skills/Hygiene/SKILL.md) — Audit ~/.claude for git, skill, code, and rules hygiene issues. USE WHEN auditing the Claude config, checking harness health, or cleaning up skills/hooks/rules.
- [Reflect](skills/Reflect/SKILL.md) — Self-rate the just-finished output on five axes with evidence, then fix any gap scored ≤3. USE WHEN a non-trivial task finishes — 3+ files, a multi-step workflow, or 3+ debug attempts.
- [SecurityReview](skills/SecurityReview/SKILL.md) — Audits code for vulnerabilities and secrets. USE WHEN reviewing code for security issues.
- [Verify](skills/Verify/SKILL.md) — Run a build/type/lint/test/secret/diff gate ending in a READY / NOT READY verdict. USE WHEN verifying changes, before commit or PR, or as a quality gate.

### reference
- [BackendDesign](skills/BackendDesign/SKILL.md) — Reference for API design, database schema, and server architecture. USE WHEN designing an API, modeling a schema, or structuring a backend service.
- [CodingStandards](skills/CodingStandards/SKILL.md) — Language coding standards (TS, Python, Bash, PowerShell, Swift, Rust). USE WHEN writing, reviewing, or scaffolding code.
- [CreateCLI](skills/CreateCLI/SKILL.md) — Generate a production-ready TypeScript CLI; shared base that routes to CreateCLI-Agent or CreateCLI-Human. USE WHEN create a CLI, command-line tool, or wrap an API. NOT FOR agent skills (use CreateSkill) or Python.
- [CreateCLI-Agent](skills/CreateCLI-Agent/SKILL.md) — Generate a production-ready TypeScript CLI for autonomous agents (JSON contract, non-interactive, semantic exits). USE WHEN create an agent CLI, tool for LLM/automation, or wrap an API for agents. NOT FOR human-first interactive CLIs (use CreateCLI-Human), agent skills (use CreateSkill), or Python.
- [CreateCLI-Human](skills/CreateCLI-Human/SKILL.md) — Generate a production-ready TypeScript CLI for human operators (TTY UX, prose help, optional JSON). USE WHEN create a CLI for people, interactive command-line tool, or wrap an API for humans. NOT FOR agent-first CLIs (use CreateCLI-Agent), agent skills (use CreateSkill), or Python.
- [CreateMcp](skills/CreateMcp/SKILL.md) — Build a Model Context Protocol (MCP) server with the official SDK — tools, resources, prompts, transport, and security. USE WHEN creating, scaffolding, connecting, or debugging an MCP server.
- [DockerPatterns](skills/DockerPatterns/SKILL.md) — Reference for Docker and Docker Compose local dev patterns. USE WHEN writing a Dockerfile or compose file, or containerizing local dev.
- [FrontendAesthetics](skills/FrontendAesthetics/SKILL.md) — Visual direction and anti-slop gate — typography, color, motion. USE WHEN building any page/dashboard/UI, redesigning, design direction, or looks templated/AI-made. NOT FOR component logic or performance (use FrontendDesign).
- [FrontendDesign](skills/FrontendDesign/SKILL.md) — Reference for building React/Next.js components, hooks, state, and performance. USE WHEN building components, hooks, state, or optimizing renders. NOT FOR visual styling, typography, or color (use FrontendAesthetics).
- [GitWorkflow](skills/GitWorkflow/SKILL.md) — Reference for git branching strategies, commit conventions, merge vs rebase, and conflict resolution. USE WHEN choosing a branching model, resolving conflicts, or setting commit conventions. NOT FOR running gh repo operations like push/PR/release (use GitHubOps).

### delegation
- [Agy](skills/Agy/SKILL.md) — Delegate a coding, refactor, PR-review, or image task to the Antigravity CLI (agy) as an autonomous worker. USE WHEN delegating such a task to agy/Antigravity, or running the agy CLI.
- [OpenCode](skills/OpenCode/SKILL.md) — Delegate a coding, refactor, or PR-review task to the OpenCode CLI as an autonomous worker. USE WHEN delegating such a task to OpenCode, or running the opencode CLI.
- [Pi](skills/Pi/SKILL.md) — Delegate a coding, refactor, or PR-review task to the Pi (pi.dev) CLI as an autonomous worker. USE WHEN delegating such a task to Pi, or running the pi CLI.

### meta
- [ContextBudget](skills/ContextBudget/SKILL.md) — Audit Claude Code context-window consumption across agents, skills, MCP servers, and rules, and produce prioritized token-savings recommendations. USE WHEN context feels bloated or you want to cut token usage.
- [CreateHook](skills/CreateHook/SKILL.md) — Generate lifecycle hooks for AI agent runtimes (Claude Code, OpenCode, OpenClaw, Hermes Agent). USE WHEN writing, wiring, or debugging an event hook, plugin hook, or agent automation trigger.
- [CreatePlugin](skills/CreatePlugin/SKILL.md) — Package a project as an AI-agent plugin with Hermes, Claude, OpenClaw, Pi, OpenCode, and MCP adapters. USE WHEN porting workflows across agent hosts. NOT FOR standalone CLIs (use CreateCLI).
- [CreateSkill](skills/CreateSkill/SKILL.md) — Create, validate, and improve individual skills. USE WHEN create/validate/improve a skill or a skill isn't triggering. NOT FOR TypeScript CLI generation (use CreateCLI) or whole-library audits (use SkillForge).
- [ModelUpgrade](skills/ModelUpgrade/SKILL.md) — Re-tune skills for any model, current or named: judge relevance and fit, then reprompt, replan, or retire. USE WHEN switching models, a model ships, or skills feel dated.
- [SkillForge](skills/SkillForge/SKILL.md) — Audit the whole skill library for agentic readiness and instrument it with telemetry in bulk. USE WHEN auditing skills for autonomy, finding agentic gaps, or adding execution logging across skills. NOT FOR creating a single skill (use CreateSkill) or re-tuning for a new model (use ModelUpgrade).

### visual
- [Art](skills/Art/SKILL.md) — Generates images, diagrams, and visual output. USE WHEN producing any visual artifact — illustration, diagram, chart, thumbnail, card. NOT FOR in-app chart components (use the dataviz skill).

### prompting
- [Prompting](skills/Prompting/SKILL.md) — Vendor-agnostic prompt-engineering standard library. USE WHEN authoring or refining a prompt, system message, skill, agent instruction, or rule file.

## Workflows (composed skill chains)

> Multi-skill chains for full jobs, as an OKF bundle — one markdown concept per workflow with YAML frontmatter. Two families: build & ship (use the skills on a project) and maintain the library (meta). Index: [workflows/index.md](workflows/index.md).

- [API feature](workflows/api-feature.md) — A backend or API change, security-gated from design to PR. · chain: BackendDesign(ref) → Spec → Build → Test → SecurityReview → GitHubOps:PullRequest
- [Autonomous loop](workflows/autonomous-loop.md) — Hands-off improvement of a target via Iterate, with a mandatory exit condition. · chain: Iterate(target, goal, max) → [Verify + Reflect each pass] → GitHubOps:CommitPush
- [Multi-skill batch build](workflows/batch-build.md) — Build or refactor many skills at once, in parallel, each reviewed in isolation. · chain: Spec → Orchestrate(Decompose → RunLayer → MergeQueue) → Verify [final integration gate — Orchestrate already verifies each unit] → GitHubOps:PullRequest
- [Build a CLI](workflows/build-cli.md) — Ship a TypeScript command-line tool, tier-picked and Verify-gated. · chain: [Research(API, if wrapping)] → CreateCLI → Test → Verify → GitHubOps:PullRequest
- [Build an MCP server](workflows/build-mcp.md) — Scaffold, secure, test, and connect a Model Context Protocol server. · chain: CreateMcp:BuildServer → SecurityReview → CreateMcp:TestServer → CreateMcp:ConnectServer → Verify → GitHubOps:PullRequest
- [Canonicalize a skill](workflows/canonicalize-skill.md) — Fix a skill's structure to conform to canon — naming, frontmatter, routing. · chain: CreateSkill:ValidateSkill → CreateSkill:CanonicalizeSkill → GitHubOps:CommitPush
- [Context diet](workflows/context-diet.md) — Cut context-window bloat across agents, skills, MCP, and rules — no feature change. · chain: ContextBudget → trim agents / skills / MCP / rules → Verify
- [Fix a skill's trigger](workflows/fix-trigger.md) — A skill won't activate or mis-fires — repair its description and routing. · chain: CreateSkill:OptimizeDescription → CreateSkill:TestSkill → GitHubOps:CommitPush
- [Frontend build](workflows/frontend-build.md) — Full frontend feature from spec through visual direction, components, assets, tests, to ship. · chain: Spec → FrontendAesthetics:DesignBrief → FrontendDesign → Art → Spec → Build → Test → FrontendAesthetics:SlopAudit → Reflect → Verify → GitHubOps:CommitPush → GitHubOps:PullRequest
- [Library-wide audit](workflows/library-audit.md) — Whole-library health sweep — agentic readiness, telemetry, canon, repo hygiene. · chain: SkillForge → CreateSkill:CanonicalizeSkill ×offenders → GitHubOps:RepoHygiene → GitHubOps:CommitPush
- [Model upgrade](workflows/model-upgrade.md) — Re-tune the library when a new model generation ships — relevance and fit per skill, then reprompt, replan, or retire. · chain: ModelUpgrade:Watch → ModelUpgrade:Assess → ModelUpgrade:Apply → CreateSkill:ValidateSkill → GitHubOps:PullRequest
- [New skill — heavy](workflows/new-skill-heavy.md) — Author a complex, multi-workflow skill whose shape isn't obvious yet. · chain: Iterate:RunLenses → Spec → CreateSkill → CreateSkill:TestSkill → Verify → GitHubOps:PullRequest
- [New skill — quick](workflows/new-skill-quick.md) — Author a new skill with clear scope and a single capability. Daily path. · chain: Prompting → CreateSkill(scaffold) → CreateSkill:TestSkill → CreateSkill:ValidateSkill → GitHubOps:CommitPush
- [Onboard a codebase](workflows/onboard.md) — Get productive in an unfamiliar repo fast, then make the first change. · chain: CodebaseOnboarding → Research(fill gaps) → Spec (first change) → spec-to-ship
- [Release](workflows/release.md) — Cut a tagged version of the library — hygiene, changelog, GitHub release. · chain: GitHubOps:RepoHygiene → GitHubOps:Changelog → GitHubOps:Release
- [Repo hygiene](workflows/repo-hygiene.md) — Periodic cleanup of config and project repo — git, skills, rules, manifest drift. · chain: Hygiene → fix → GitHubOps:RepoHygiene
- [Research to build](workflows/research-to-build.md) — Ground an unknown domain, library, or API before building against it. · chain: Research(standard|deep) → Spec → Build → Verify → GitHubOps:PullRequest
- [Research to buy](workflows/research-to-buy.md) — Compare options before a purchase or adoption decision, then score a pick. · chain: Research(deep) → comparison matrix → scored recommendation
- [Research to report](workflows/research-to-report.md) — Deliverable is cited findings plus visuals, not code. · chain: Research(deep) → DataReportBuilder → Art(diagrams)
- [Security pass](workflows/security-pass.md) — Harden existing code before release — no new feature. · chain: SecurityReview → fix CRITICAL/HIGH → Verify → GitHubOps:CommitPush
- [Ship fast](workflows/ship-fast.md) — Clear-enough scope; move fast and discover the details mid-flight. · chain: Spec → Build → Reflect → Verify → GitHubOps:CommitPush → GitHubOps:PullRequest
- [Spec to ship](workflows/spec-to-ship.md) — Know exactly what to build; spec-driven build from criteria to PR. · chain: Spec → Build → Test → Reflect → Verify → GitHubOps:CommitPush → GitHubOps:PullRequest
- [UI feature](workflows/ui-feature.md) — A frontend change that looks intentional, not AI-slop — direction before components. · chain: FrontendAesthetics:DesignBrief → FrontendDesign(build) → FrontendAesthetics:SlopAudit → Verify → GitHubOps:CommitPush

## Key docs

- [README.md](README.md) — human-facing index + install guide
- [workflows/index.md](workflows/index.md) — composed skill chains, OKF bundle (one concept per workflow)
- [rules/system.md](rules/system.md) — canonical skill-system spec
- [CLAUDE.md](CLAUDE.md) — Claude Code loader + composition map
- [AGENTS.md](AGENTS.md) — brief for non-Claude-Code tools
- [INSTALL-AI.md](INSTALL-AI.md) — install guide for all supported tools
- [skills.json](skills.json) — machine-readable manifest (skills + workflows)