agentsclimarketplace

Primitive catalog

Skill Aznatkoiny/plugin-forge/skills/primitive-catalog

Decision cards for selecting Claude Code primitives while designing a plugin - skill vs hook vs subagent vs agent team vs MCP server vs bundled script vs LSP vs workflow vs loop. Load during any plugin architecture or composition discussion, when writing a Primitive Decision Record (design/CONTRACT.md), filling six-step consequence chains (trigger, context economics, enforcement, failure modes, testability, distribution), choosing who holds the plan, picking a loop primitive (/goal vs Stop hook vs /loop vs schedule), or deciding MCP-versus-bundled-script. Cards carry exact syntax, version floors, context costs, failure modes, and the grader type that can observe each primitive.From its SKILL.md

Install
npx -y skills add Aznatkoiny/plugin-forge --skill primitive-catalog

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

8.6 KB, as published. Nobody here has run it

Primitive catalog — the decision layer for plugin composition

Use this catalog while drafting a Primitive Decision Record (PDR) in design/CONTRACT.md. Each card in references/cards/ is a decision-oriented distillation: exact syntax, version floors, context costs, and failure modes. For exhaustive syntax the cards point to the official Claude Code docs (https://code.claude.com/docs — fetch llms.txt for the page index) — never duplicate that encyclopedia here.

Rules of use:

  • Answer every loaded card's Consequence prompts in the PDR chain columns C1–C6 before committing to that primitive.
  • When a card's Reject when criteria match, record the rejection as that capability's rejected alternative, naming the chain step that killed it.
  • When a card's Eval hooks section cannot name a grader that observes the primitive in the target design, the choice is unverifiable → unbuildable (the C5 hard gate).

Master rubric 1 — who holds the plan

Escalate only as far as the capability demands; every step up costs tokens, latency, or interactivity.

LevelWho holds the planIntermediates live inRepeatable unitScalePick when
Main conversationClaude, turn by turnMain contextNothing1 threadFrequent back-and-forth; phases share context
Skill (inline)The SKILL.md promptMain contextThe instructions1 threadRepeatable process knowledge; standing rules
SubagentDelegation prompt + agent bodySubagent context; summary returnsThe agent definitionA few parallelVerbose-output isolation; tool restriction; clean expert lens
Forked skill (context: fork / /subtask)SKILL.md as the fork's promptFork context (inherits conversation; shares prompt cache)The skillA few parallelSide task needs the accumulated conversation state
Agent teamLead + shared task listTask list + mailboxes (~/.claude/tasks/)Subagent definitions as roles3–5 peers, 5–6 tasks eachWorkers must discuss/challenge each other; file-partitioned parallel builds
WorkflowThe JS scriptScript variablesThe orchestration script itselfDozens–hundreds (16 concurrent, 1000/run)Homogeneous fan-out; intermediates would overflow context

Master rubric 2 — loop primitives

PrimitiveNext turn firesStops whenPersistsCan a plugin ship it?
/goal <condition>When the previous turn finishesTool-less small-model evaluator judges the condition true from the transcript aloneSession only (survives --resume, counters reset)No — session command (v2.1.139+; needs trust + hooks enabled)
/loopOn a time intervalUser or model decidesSession onlyNo
Stop hook (prompt/agent type)When the previous turn finishesPer the hook's script/prompt verdictIts settings scope — survives sessionsYes — via hooks/hooks.json; the productized /goal
Schedule (cloud routine / scheduled task)On cron, independent of open sessionsPer scheduleAccount/repo levelPlugin ships the skill it invokes, not the schedule

A plugin cannot ship /goal itself. The distributable equivalent is a prompt- or agent-type Stop hook in hooks/hooks.json (honoring stop_hook_active and the 8-block cap, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP), plus documented "goal recipes" — pre-written ≤4,000-char conditions users paste into /goal. Note: scheduled tasks cannot invoke disable-model-invocation: true skills (v2.1.196+). Full loop mechanics: references/cards/loops-card.md.

Master rubric 3 — MCP server vs bundled script

Does the capability need persistent connection state, OAuth to a remote API,
server push (channels), elicitation dialogs, MCP resources/prompts, or a large
tool surface (tool search scales)?
├─ YES → bundle an MCP server (.mcp.json at plugin root)      → mcp-card.md
└─ NO
   ├─ One-shot computation or CLI call, no connection state
   │    → bundled stdlib script + skill with
   │      allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/x.sh *)
   │      (zero prompts, no server lifecycle, no approval dialog,
   │       no timeout design, headless-safe)                   → skills-card.md
   ├─ Long-running local watch (tail a log, poll a queue)      → monitors-bin-card.md
   └─ CLI users should call directly by name                   → bin/ on PATH, monitors-bin-card.md

Default to the script. MCP must earn its lifecycle cost: approval prompts, trust dialogs, timeout/idle design, headless auth preflight, and stdio's never-reconnects failure mode.

Card index

Load only the cards relevant to the candidate compositions under discussion.

  • references/cards/skills-card.md — load when any capability could be a skill or command: invocation-control matrix (disable-model-invocation vs user-invocable), 1,536-char description cap and 1% listing budget, arguments, the !-backtick dynamic injection and its policy fallback, context: fork narrowing, 5k/25k compaction budgets, paths scoping, model/effort routing, stacking stop rule.
  • references/cards/hooks-card.md — load when behavior must be enforced rather than suggested, or automated at a lifecycle point: 30-event catalog with per-event matcher vocabulary, five executor types and their selection rule, exit-code discipline, per-event output schemas, Stop-loop mechanics, headless gaps.
  • references/cards/agents-teams-card.md — load when delegating to subagents or coordinating an agent team: plugin frontmatter stripping and its two workarounds, background 19-tool filter, memory: project, isolation: worktree base-branch gotcha, dual-mode bodies, resume-via-SendMessage, team task DAGs, plan approval, TaskCompleted gates.
  • references/cards/mcp-card.md — load when integrating external systems: transport selection, plugin-scoped tool naming, tool search and 2KB instruction discovery, timeouts and backgrounding, tools vs resources vs prompts vs elicitation vs channels, headless auth preflight, and the honest MCP-apps status note.
  • references/cards/lsp-card.md — load when the target plugin serves a programming language and post-edit diagnostics or code navigation would help: configure-never-bundle rule, official-plugin dependency route, first-server-wins, diagnostics toggle.
  • references/cards/workflows-card.md — load when a capability fans out over many homogeneous items: agent()/pipeline() with schema and label, 16/1000 caps, resume replay order, the ultracode-never-fires-headless trap, always-pair-with-a-script rule.
  • references/cards/loops-card.md — load when a capability is "keep working until done": /goal condition authoring, evaluator mechanics, shipped Stop-hook productization, /loop, ralph/karpathy outer-loop patterns.
  • references/cards/headless-card.md — load when anything must run under claude -p (CI, evals, routines): --bare hermeticity, output formats, --json-schema, system/init gating, permission rule syntax, session chaining.
  • references/cards/worktrees-card.md — load when work needs filesystem isolation: --worktree lifecycle, -p never cleans up, worktree.baseRef, .worktreeinclude, sharing semantics.
  • references/cards/monitors-bin-card.md — load for long-running background watchers (monitors/monitors.json, when: on-skill-invoke) and bin/ executables added to the Bash PATH.
  • references/cards/output-styles-settings-card.md — load when the plugin needs a persona shift or fleet display: output styles vs CLAUDE.md vs agents, force-for-plugin, plugin settings.json (agent, subagentStatusLine only).
  • references/cards/distribution-card.md — load when deciding install level and lifecycle: marketplaces, version strategy (SHA vs pinned semver), dependencies, renames, seed dirs for CI, cloud-session declaration.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.