AGENT SKILL

agent-compiler

Compile deterministic, content-hashed agents from small behavior modules instead of hand-writing persona prompts. Use when the user asks to build, compose, or reproduce an agent/persona/reviewer from reusable behavior ("compile an agent", "make me a security reviewer from the registry", "why does this agent behave this way", "add a rule to the registry"), or when agent behavior needs provenance, an effect ceiling, or byte-for-byte reproducibility.

License 许可
MIT
最近更新
2026-11-12
Stars
★ 1
Forks
0

01 前言 Front Matter

name
agent-compiler
description
Compile deterministic, content-hashed agents from small behavior modules instead of hand-writing persona prompts. Use when the user asks to build, compose, or reproduce an agent/persona/reviewer from reusable behavior ("compile an agent", "make me a security reviewer from the registry", "why does this agent behave this way", "add a rule to the registry"), or when agent behavior needs provenance, an effect ceiling, or byte-for-byte reproducibility.

02 资源文件 1

03 SKILL.md 正文

agent-compiler

Invariant

Given the same registry revision, query, and compiler version, compilation produces a byte-identical canonical AgentImage and identical hash; every emitted unit carries provenance to a source module; unresolved conflicts, missing dependencies, dependency cycles, and effects above the query's ceiling fail compilation.

The deterministic kernel (scripts/compile.py) enforces all of that. This skill governs the one step the kernel cannot: turning fuzzy intent into a typed AgentQuery — and refusing to smuggle behavior past that boundary.

The boundary rule

Natural language may select behavior; it may not silently define it.

  • You may interview, infer, and search fuzzily while building the query.
  • Once the query exists, only the kernel decides what the agent is.
  • If the user's intent needs behavior no registry module provides, the move is author a module, then recompile — never paste prose into the rendered agent, and never edit a rendered artifact by hand (each one says so in its header).
  • "Just write me the persona file" is an agent-building request, not a writing task. Decline the freehand shortcut and normalize it in the same reply: the deliverable is a compiled, rendered artifact — never hand-authored persona prose, with or without a disclaimer.

Two ways in: MCP tools or the CLI

Installed as a Claude Code plugin, the bundled MCP server (kernel, from scripts/mcp_server.py) starts automatically and exposes the same four pure operations as tools: inspect, compile, explain, render. Prefer them when available — same kernel, same guarantees, no shell round-trip. The CLI below is the identical fallback on any harness without MCP; the server is a convenience, not a dependency, and it never performs an effectful action (render returns markdown text; writing the file stays with you).

Two hooks reinforce this mechanically on Claude Code (a convenience, not a dependency — on any other harness these rules bind through this prose alone): agent-building prompts get a context pointer to the MCP tools, and any hand-edit of a file carrying the renderer's imageHash header is denied with the recompile instruction.

Workflow

  1. Normalize intent into an AgentQuery. Ask or infer until these are explicit: role, task, domains, views, stance, and the effect ceiling (effectCeiling in the query, or a view's max_effects). Show the user the query JSON before compiling. A compile with no ceiling from either source is refused (NO_EFFECT_CEILING) — an unconstrained agent must be asked for by listing its effects, never implied by omission. Ceiling first, in plain words: before you inspect the registry or call compile, either ask the user to fix the agent's allowed effects (e.g. read-only ["network", "scm:read"] vs. commenting ["network", "scm:read", "scm:write"] — every bundled SCM capability also declares network, so a ceiling of ["scm:read"] alone is rejected with EFFECT_CEILING) or state the ceiling you will compile under — a passing mention that "the compiler enforces a ceiling" is not a ceiling. Then show the draft query (role, task, domains, views, stance, effectCeiling) as JSON, with placeholders marked wherever you still need an answer. Registry inspect calls refine the draft; they never replace showing it — a reply that ends at inspection has not normalized anything.
  2. Discover module IDs with python3 scripts/compile.py inspect --registry <dir> [--kind|--tag|--id]. Fuzzy discovery may suggest IDs; the compile step consumes exact IDs only.
  3. Compile: python3 scripts/compile.py compile --registry <dir> --query <query.json> --out <image.json> The output is a canonical AgentImage whose hash identifies the agent.
  4. On diagnostics, fix the source, not the check. Relay the structured diagnostics and resolve them in the registry (add a supersedes edge, split a module, drop a capability) — never by suppressing or downgrading the failure.
  5. Render the image into a harness-native agent definition: python3 scripts/render_claude_agent.py --image <image.json> --out .claude/agents/<name>.md PORTABILITY: .claude/agents/ is Claude Code's location; the AgentImage, not the rendered file, is the contract, and the same image renders for any other harness (the discipline ports even where the path does not).
  6. Explain on demand: every line of a rendered agent carries its unit ID; python3 scripts/compile.py explain --image <image.json> --unit <id> traces it to module, version, source file, and lines.

Authoring modules

The module format (Markdown + restricted frontmatter + semantic blocks) is specified in references/language.md. Keep modules small and addressable: one concern per module, stable IDs, explicit requires/conflicts_with/ supersedes edges, semantic versions. A module's filesystem location never carries meaning — only its id does.

Where the registry lives

This plugin ships a starter registry/. --registry accepts any directory, so a repository can carry its own registry (e.g. registry/ at its root) and compile agents from it; the kernel treats both identically.

04 同仓库更多 Skills

JRichlen
JRichlen/agent-plugins

wayfinder

Chart a multi-session effort as a labeled map of typed decision tickets (grilling / prototype / research / task) with explicit dependencies and an open frontier agents self-assign into. Plans; never executes. Use this skill whenever the user is working with wayfinder, and on phrases like "chart this effort", "break this into tickets", "what's the frontier", "plan across sessions", or "map out the dependencies for this work".

★ 1
JRichlen
JRichlen/agent-plugins

wave-research

Staged, adversarial research that tries to break a thesis before believing it: waves, checkpoints, falsifiable sub-claims, rival hypotheses, an ACH matrix, source-incentive tags and a verified final thesis. Also carries Workflow templates for a one-pass research-and-verify fan-out. Use to stress-test or vet a contested claim; not for quick lookups.

★ 1
JRichlen
JRichlen/agent-plugins

second-opinion

Offer-only validation pipeline for a verdict or recommendation. Use when the user asks to validate, verify, fact-check, or get a second opinion on a claim or recommendation — "are you sure", "double-check this", "second opinion". Batches fact-checking against sources, adds scoped advisor personas for the angles that need judgment, then re-emits the response grouped into verified, flagged, and conflict, with a mandatory validation delta. Requires a subagent-spawning tool; without one it must decline rather than simulate.

★ 1
JRichlen
JRichlen/agent-plugins

machine-voice

Compression rules for standalone machine-read artifacts the reader scans — agent traces, tool-call logs, status lines, progress updates, handoff notes, state dumps, config, schemas, reference cards, and structured data another agent parses. Applies three layers: lexical compression, markdown structure as navigation, and emojis as typed status markers. Reach for it when emitting one of those artifacts on its own. Companion to human-voice, which governs prose a human reads and also owns any table or block that serves surrounding explanation. Neither skill applies to code or file contents the user will save, commit messages, creative writing, or turns that are only a clarifying question — those ship unstyled and uncompressed.

★ 1
JRichlen
JRichlen/agent-plugins

human-voice

Style for prose a human reads — answers, recommendations, explanations, research summaries, comparisons. Use on every conversational reply that contains prose for a person to read: triage intent, lead with the verdict, keep it scannable, tag claim confidence. Reach for it whenever answering a technical question, comparing options, or making a recommendation, even when the user says nothing about style. Companion to machine-voice, which instead governs standalone machine-read artifacts — agent traces, tool-call logs, status lines, progress updates, handoff notes, state dumps, config, schemas, reference cards, and structured data another agent parses. Neither skill applies to code or file contents, commit messages, creative writing, or turns that are only a clarifying question — those ship unstyled.

★ 1
JRichlen
JRichlen/agent-plugins

ai-writing-mistakes

Catch and repair the tells that mark prose as machine-written — the negation-flip ("it's not X, it's Y"), rule-of-three padding, hedge stacking, unearned intensifiers, filler verbs like delve and leverage, participle trailers ("...ensuring seamless integration"), sycophantic openers, empty closing summaries, and uniform em-dash/sentence rhythm. Use when drafting or revising any prose a human will read, including documents you were asked to author — READMEs, docs, PR bodies, release notes, emails — and when the user asks whether something "sounds like AI" or wants writing tightened. This is a wording pass, not a voice: human-voice still decides layout and confidence tags, machine-voice still owns traces and logs, and neither this skill nor those two touch code, commit messages, or quoted text.

★ 1