author-extension
Skill18 starsChanged 13 days agoMITView on GitHub
Write a new yolop extension end-to-end — scaffold, implement, install, verify, and enable it — when the user asks yolop to add a capability, integrate with something, or "build an extension" for a need that no installed extension covers.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- maintenanceSkill
- releaseSkill
- shipSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Use this when the user wants a *new, persistent* capability and no installed extension provides it — something worth keeping across …
- Very specific: line 25
If an installed extension already covers it, use that instead (list_extensions).
- Distinctive: line 46
Not yet available: providers.
- Distinctive: line 65
Keep stdout for protocol JSON only.
- Very specific: line 105
Do not hardcode absolute paths in the manifest — the package is copied on install.
≈ “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
Author an extension
Goal: turn a capability request ("integrate with X", "block Y", "add a tool that Z") into a working, installed yolop extension — built by yolop itself.
An extension is a capability package served over YEP (the yolop extension
protocol): a plugin.json manifest plus a capability server that speaks
newline-delimited JSON-RPC over stdio. See knowledge/specs/extensions.md.
When to use
Use this when the user wants a new, persistent capability and no installed extension provides it — something worth keeping across sessions, not a one-off shell command. Signals: "make yourself a tool for…", "add an extension that…", "integrate yolop with…", "from now on, block/allow…".
If an installed extension already covers it, use that instead
(list_extensions). If the need is a single throwaway action, just do it — do
not author an extension for it.
What an extension can contribute
A manifest must contribute at least one facet; declare only what you need.
extensions.md defines each one — this is what to pass the
scaffold and what it generates.
| Facet | Scaffold | Generated seam |
| tools | tools=[…] | handle_tool(name, args) returning the result dict |
| hooks | hooks=[…] | handle_hook(event, tool_name, args) — pre_tool_use can block, post_tool_use observes |
| prompt | prompt=… | a static system-prompt contribution |
| mcpServers | — | declared in the manifest directly |
| status | status: true | emit_status(text); empty text clears the field. TUI-only, a no-op in --print/ACP |
| skills | skills: true | a starter skills/<name>/SKILL.md, mounted read-only when the extension is enabled |
| commands | commands: ["name", …] | handle_command(name, arguments); registered as /<ext>:<cmd> |
| ui_ask | — | declare ui_ask: true and send ui/ask ({prompt, placeholder?}) by hand; refused in --print/ACP |
Not yet available: providers.
The loop
Scaffold.
scaffold_extension name=<name> [description=…] [language=python|typescript|rust]with the facets you need —tools=[…],hooks=[…], and/orprompt=…. This writes a package (manifest + server source) with the handler bodies stubbed.pythonandtypescript(a dependency-free Node.js server) are single-file and need no build step;rustemits aserde_json-only crate. Pick the one whose toolchain the environment has; Python is the default.For
rust, the scaffold result includes abuildcommand — run it after editing to compile the binary intobin/before installing. The zero-build templates skip that.- Implement. Open the generated server (the tool result prints its path)
and fill in the marked
handle_*bodies; leave the protocol plumbing alone. A hook returns{}to allow or{"block": True, "reason": "…"}to deny — and it receives every subscribed tool call, so gate ontool_name/args. Keep stdout for protocol JSON only; log to stderr. - Install.
install_extension source=<package dir>— copies the package into the store and pins it. Installing runs third-party code; since you authored it here, the sharp edge is enabling — see step 5. - Verify.
doctor_extension name=<name>— spawns the server, runs the handshake, and checks the served tools/prompt against the manifest. Fix anyfail/warnbefore enabling. If the server won't spawn, check the shebang and that the command is executable. - Enable (ask first). Show the user the contribution summary and ask
before
enable_extension name=<name>— enabling adds it to the harness and runs its server every session. In the interactive TUI it is applied to the running session immediately (activated on the live agent), so its tools/prompt/hooks are available on the next turn — no restart — and it's persisted for future sessions. In--print/ACP there's no live session to mutate, so it only takes effect next run. - Iterate live (already-enabled extensions). Once an extension is enabled
and its server has run this session,
reload_extension name=<name>restarts that server in place so edits to its implementation take effect immediately — no yolop restart. This is the fast inner loop for fixing a handler you authored: edit the server,reload_extension, call the tool again. The manifest is the session's approval boundary, so a surface change (adding a tool, changing a schema) still needs a restart, and reload can never widen the grant.
Acceptance check
The loop is proven when yolop, unaided, produces an extension that actually
works — e.g. a pre_tool_use hook that blocks any git command, or a tool
that returns a computed value — installed, doctor-green, and effective after a
restart. The end-to-end deny path is covered by
scaffolded_extension_blocks_git_end_to_end in src/extensions/mod.rs.
Notes
- Names: ascii letters, digits,
-,_. The dir name must equal the manifestname. - Do not hardcode absolute paths in the manifest — the package is copied on
install. The scaffold resolves the server via the package's
bin/on PATH. - Iterate by editing the server and re-running
doctor_extension; no reinstall is needed while working from the scaffolded dir, but re-runinstall_extensionto pick up edits into the store.
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.

