implement-plugin
Skill19 starsChanged 22 days agoApache-2.0View on GitHub
Scaffold, implement, and test Starlark plugins. From protocol/event/phase selection to running sample tests
1 other project uses a version of this.
Adopted by
Most recently taken up by
- ubie-oss/claude-code-plugintheir own version, first seen Feb 12, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- ubie-oss/claude-code-plugin★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- autopilotSkill
- buildSkill
- code-reviewSkill
- implementSkill
- license-checkSkill
- orchestrateSkill
- pentest-proxySkill
- projectSkill
- prSkill
- review-gateSkill
- security-reviewSkill
- testSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
If no description argument is given, interactively confirm:
- Distinctive: line 27
If a description argument is given, auto-determine from its content.
- Distinctive: line 31
Read the following to understand the plugin API:
- Very specific: line 42
Create a plugin file in examples/plugins/:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/implement-plugin
A workflow skill for creating Starlark plugins on the RFC-001 §9.3 plugin engine (internal/pluginv2/). Interactively select protocol/event/phase to generate a working scaffold.
Arguments
/implement-plugin— Create a plugin in interactive mode/implement-plugin <description>— Auto-generate a plugin from a description (e.g.,/implement-plugin Add X-Request-ID header to HTTP requests)
Steps
Phase 1: Requirements Clarification
If no description argument is given, interactively confirm:
- Purpose: What should the plugin do?
- Protocol: Target plugin protocol — one of
http,ws,grpc,grpc-web,sse,raw,tls,connection,socks5(the plugin protocol vocabulary; seeinternal/pluginv2/surface.go). - Event: Hook event under that protocol (e.g.
on_request,on_message,on_chunk). - Phase:
pre_pipeline(default — before Intercept/Transform) orpost_pipeline(after; right place for signing/last-mile mutation). Lifecycle / observation events (on_close,on_handshake,on_disconnect,socks5.on_connect, etc.) take nophase=argument — passing one is a load-time error. - Action: CONTINUE (mutate in place) / DROP (transaction-start only) / RESPOND (transaction-start request; on the response side
http.on_response/ws.on_upgradeon a 101 replace the upstream response,grpc.on_start/grpc-web.on_startend the RPC).
If a description argument is given, auto-determine from its content.
Phase 2: Context Collection
Read the following to understand the plugin API:
docs/rfc/plugin-migration.md— Direct migration table from legacy hook names to(protocol, event, phase)and the rationale.internal/pluginv2/surface.go— The 17-entry hook surface table. Authoritative for which (protocol, event) pairs exist and which actions each accepts.internal/pluginv2/convert.go— The Starlarkmsgdict shape per protocol (snake_case field names,*HeadersValueordered list,msg["raw"]first-class byte injection).internal/pluginv2/lifecycle.go— Dict shapes for lifecycle events (connection.on_connect,socks5.on_connect,tls.on_handshake,ws.on_close).internal/pluginv2/respond_action.go— Typedaction.RESPOND(...)/action.RESPOND_GRPC(...)builtin signatures.examples/plugins/— Existing sample plugins for each major protocol.
Phase 3: Plugin Generation
Create a plugin file in examples/plugins/:
- Filename:
<snake_case_name>.star - Include a comment block at the top describing purpose, the
register_hookcall(s), and a config snippet - Hook registration is script-driven via
register_hook(protocol, event, fn[, phase=...])— there is noprotocol/hooksconfig key - Hook signature is
def fn(msg, ctx):— two positional arguments - Returning
Nonemeans CONTINUE;action.DROPdrops;action.RESPOND(...)short-circuits with a synthetic response (on a response-side hook it replaces the upstream response instead) - Mutate
msgin place —msg["headers"].append(name, value),msg["body"] = b"...",msg["raw"] = b"...". Mutations to the dict and to*HeadersValueare committed regardless of the return value.
Template Structure
# <Plugin Name>
#
# Purpose: <description of purpose>
#
# Hook identity (RFC-001 §9.3):
# register_hook("<protocol>", "<event>", fn[, phase="post_pipeline"])
#
# Config:
# { "path": "examples/plugins/<name>.star", "on_error": "skip" }
def <hook_name>(msg, ctx):
# Read fields: msg["method"], msg["headers"].get_first("X"), ...
# Mutate fields: msg["headers"].append("X-Foo", "bar"), msg["body"] = b"..."
return None # CONTINUE
register_hook("<protocol>", "<event>", <hook_name>)Protocol → msg dict shape (RFC-001 §9.3 + USK-669 snake_case)
| Plugin protocol | Events | Key fields on msg |
http | on_request, on_response | method, scheme, authority, path, raw_query, status, status_reason, headers, trailers, body, anomalies (RO), raw |
ws | on_upgrade, on_message, on_close | opcode, fin, masked, mask, payload, close_code, close_reason, compressed, anomalies (RO), raw |
grpc / grpc-web | on_start, on_data, on_end | start: service, method, metadata, timeout, content_type, encoding, accept_encoding; data: service (RO), method (RO), compressed, wire_length, payload, end_stream; end: status, message, status_details, trailers |
sse | on_event | event, data, id, retry, anomalies (RO), raw |
raw | on_chunk | bytes, raw |
tls | on_handshake (lifecycle, no phase) | side, sni, alpn, version_name, cipher_name, peer_cert_subject, client_fingerprint (frozen) |
connection | on_connect, on_disconnect (lifecycle, no phase) | connect: conn_id, client_addr, listener_name; disconnect: conn_id, client_addr, duration_ms (frozen) |
| socks5 | on_connect (lifecycle, no phase) | conn_id, client_addr, target_addr (frozen) |
msg["path"] on http is the wire form on both HTTP/1.x and HTTP/2 — the request path exactly as the client sent it, percent-encoding not decoded, query excluded (USK-1139). Decode it in the plugin if a decoded view is needed.
Writing method / path / raw_query (request) or status / status_reason (response) changes the line on the wire. On HTTP/1.x only the changed parts are rebuilt — an untouched request-target is sent byte-for-byte, an absolute-form scheme://authority prefix is kept — and the values are not validated: CR / LF / SP go out verbatim, so a plugin can craft request splitting the same way it can with msg["raw"] (USK-1148). authority / scheme are not written to the HTTP/1.x wire; change the Host header instead.
headers / trailers / metadata are *HeadersValue instances, not dicts. Methods: append(name, value), delete_first(name) -> bool, replace_at(index, name, value), get_first(name) -> str|None. Iteration yields (name, value) 2-tuples; name in headers is case-insensitive. Wire order, casing, and duplicates are preserved.
ctx (second positional argument)
ctx.client_addr— client IP string (port stripped) orNonectx.tls— frozen dict of{sni, alpn, version_name, cipher_name, peer_cert_subject, client_fingerprint}orNonectx.transaction_state/ctx.stream_state— mutable scoped dicts:.get(k),.set(k, v),.delete(k),.keys(),.clear(). Lifetime is owned by the Layer (transaction = (ConnID, FlowID) for HTTP / (ConnID, StreamID) for streaming protocols; stream = (ConnID, StreamID) always).
Action constraints (RFC-001 §9.3, surface.go)
| Action | Allowed events |
| CONTINUE | All events (always implicit) |
| DROP | Transaction-start only: http.on_request, ws.on_upgrade, grpc.on_start, grpc-web.on_start, connection.on_connect, socks5.on_connect |
| RESPOND | Transaction-start request events (as above, minus connection/socks5), plus the response side: http.on_response and ws.on_upgrade on the upstream's 101 (replace the upstream response), and grpc.on_start / grpc-web.on_start on the upstream's response headers (end the RPC with the plugin's status). gRPC / gRPC-Web hooks must use action.RESPOND_GRPC(status, message, trailers) and HTTP / WS hooks action.RESPOND(...); the other shape is refused as CONTINUE (Warn). |
Mid-stream events (on_data, on_message, on_event, on_chunk) and lifecycle/observation events (on_close, on_end, on_handshake, on_disconnect) accept CONTINUE only — terminating a stateful stream uses native termination (gRPC RST_STREAM, WS close frame), not an action enum.
Phase 4: Verification
- Visually verify Starlark syntax (compliance with
go.starlark.netsyntax rules) - Build and run the engine load tests:
make build
make testThe engine's LoadPlugins validates register_hook calls at load time — unknown protocol/event, invalid phase, or non-callable fn are reported as LoadError with Kind = LoadErrUnknownProtocol / LoadErrUnknownEvent / LoadErrInvalidPhase / LoadErrPhaseNotSupported / LoadErrNotCallable.
Phase 5: Present Configuration Example
Present the PluginConfig for the generated plugin (RFC-001 shape — no protocol/hooks keys at the config level):
{
"path": "examples/plugins/<name>.star",
"vars": { "<key>": "<value>" },
"on_error": "skip",
"max_steps": 1000000,
"redact_keys": []
}vars is exposed as a frozen Starlark config dict; redact_keys hides values from plugin_introspect. Plugins are loaded once at proxy boot; to change the loaded set, edit the config and restart the proxy (RFC §9.3 D2).
For runtime introspection, use the plugin_introspect MCP tool — read-only listing of loaded plugins and their (protocol, event, phase) registrations:
// MCP tool: plugin_introspect
{}After sending test traffic through the proxy, check each plugin's fail_open_count in the same result. It counts hook outcomes the engine refused or could not evaluate and treated as CONTINUE — the message was forwarded as if the hook had not acted. last_fail_open.kind names the cause: respond_shape_mismatch (RESPOND vs RESPOND_GRPC does not match the hook's protocol), action_not_allowed (an action the event does not accept, e.g. DROP on http.on_response or ws.on_close, RESPOND on connection.on_connect), respond_on_informational, hook_error (fail() / exception / step budget), hook_timeout (still running at its deadline: the 5 s lifecycle budget, shared by all hooks of one lifecycle event so a slow earlier hook can push a later one over it, or a resend / fuzz job's timeout_ms, after which the request is aborted rather than forwarded), invalid_return (e.g. a bare "RESPOND" string), invalid_mutation, body_too_large (hook skipped for a body over 1 MiB), chunk_too_large, unsupported_message, dispatch_error. Check fail_open_by_kind rather than the total: body_too_large / unsupported_message rise on ordinary traffic even for observe-only hooks, whereas action_not_allowed, respond_*, hook_error, hook_timeout or invalid_return on a plugin that is meant to block means some of its blocking decisions were not applied. Full field reference: docs(topic="plugin_introspect").
The legacy plugin MCP tool (list/reload/enable/disable) was removed in USK-695; there is no replacement for reload/enable/disable by design.
Notes
- gRPC mid-stream events accept CONTINUE only. DROP/RESPOND on
grpc.on_data/grpc.on_endis a load-time/dispatch-time error.grpc.on_startaccepts DROP andaction.RESPOND_GRPC(...). grpc.on_start/grpc-web.on_startDROP ends the RPC with no gRPC status — RST_STREAM(CANCEL) on h2, connection close on HTTP/1.x; the upstream is not dialed. Useaction.RESPOND_GRPC(...)to answer with a status.- Response-side RESPOND replaces the upstream response.
http.on_responseRESPOND (andws.on_upgradeRESPOND on the 101) delivers the plugin's response to the client instead of the upstream's, over HTTP/1.x and HTTP/2; the exchange ends normally (keep-alive kept) and the flow records the upstream response as theoriginalvariant, the plugin's asmodified. Later hooks of the same phase are skipped, but Intercept / Transform /post_pipelinehooks still see the replacement — register withphase="post_pipeline"when the replacement must survive Transform rules. RESPOND on an informational 1xx response (e.g.103) is refused (Warn + CONTINUE); the hook fires again on the final response.ws.on_upgradeDROP on the 101 closes the client connection (HTTP/1.x) / resets the stream (HTTP/2) with no response. grpc.on_start/grpc-web.on_startalso fire on the response headers. The response-side Start has an emptymsg["service"](guard withif not msg["service"]).action.RESPOND_GRPC(...)there replaces the upstream's response with the plugin's status (Trailers-Only / gRPC-Web trailer frame) and cancels the upstream stream; DROP ends the RPC with no status, like a request-side DROP.- RESPOND must match the hook's protocol.
grpc.on_start/grpc-web.on_starttake onlyaction.RESPOND_GRPC(...);http.on_request/http.on_response/ws.on_upgradetake onlyaction.RESPOND(...). A mismatched shape is refused at dispatch time (ErrDisallowedAction): Warn log, the hook counts as CONTINUE with itsmsgedits discarded, and the request is forwarded upstream. - DROP / RESPOND are recorded (USK-1393). The stopped message is stored like any other (
queryfinds it); the Stream carries tagsplugin(your plugin's name),plugin_hook(<protocol>.<event>) andplugin_phase. DROP marks the Streamstate="error",blocked_by="plugin"(queryfilter.blocked_by: "plugin"). RESPOND / RESPOND_GRPC has noblocked_by; the plugin's response is recorded as a receive message withmetadata.synthetic = "true".http.on_responseRESPOND-replace is recorded as theoriginal/modifiedvariant pair instead. - WebSocket mid-stream events accept CONTINUE only. To redact a
ws.on_messagepayload, mutatemsg["payload"]in place rather than dropping. To refuse a connection, hookws.on_upgradeand return DROP. (socks5, on_connect)accepts DROP for connection-level allowlists, but nophase=argument — it is a lifecycle event.- WebSocket Ping/Pong frames are still delivered as
(ws, on_message)events; filter bymsg["opcode"](0x9 = ping, 0xA = pong, 0x1 = text, 0x2 = binary) when only certain frame types matter. msg["raw"] = b"..."writes verbatim wire bytes (RFC §9.3 D4 "raw wins") — when both raw and message-side fields are mutated, raw is shipped and message-side mutations are recorded only in the variant snapshot. Exception — HTTP/2 header blocks are read-only: on an HTTP/2httpmessage, agrpcon_start, and agrpc-webon_start,msg["raw"]is unframed HPACK / a header snapshot that cannot be written, so a write is ignored with a Warn (raw only → unchanged; raw + fields → the field edits apply). Editmsg["headers"]/msg["body"]/msg["metadata"]there instead.grpc/grpc-webon_datastill honourmsg["raw"](USK-1237).- Body cap:
msg["body"]is capped at 1 MiB; oversize bodies are surfaced asErrBodyTooLargeand the plugin is skipped (the body is never truncated for the plugin). - Starlark is a subset of Python:
import,class, file I/O, and network access are not available.print()writes to the proxy log. - Module-level variables are frozen after load — mutable objects (lists, dicts) at module level cannot be modified inside hooks. Use immutables (strings, ints, tuples) at module level; mutate via
msg/ctx.transaction_state/ctx.stream_state/state.*instead. configis a frozen dict ofvarsfrom the plugin config. Useconfig["key"](or membership-test first with"key" in config) — there is no schema enforcement beyond the engine's primitive type whitelist.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

