agentleFS
everrunseverruns/yolop/.agents/skills/author-extension/SKILL.md

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.

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
  1. Distinctive:

    Use this when the user wants a *new, persistent* capability and no installed extension provides it — something worth keeping across …

    line 20
  2. Very specific:

    If an installed extension already covers it, use that instead (list_extensions).

    line 25
  3. Distinctive:

    Not yet available: providers.

    line 46
  4. Distinctive:

    Keep stdout for protocol JSON only.

    line 65
  5. Very specific:

    Do not hardcode absolute paths in the manifest — the package is copied on install.

    line 105

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

FacetScaffoldGenerated seam
toolstools=[…]handle_tool(name, args) returning the result dict
hookshooks=[…]handle_hook(event, tool_name, args) — pre_tool_use can block, post_tool_use observes
promptprompt=…a static system-prompt contribution
mcpServers—declared in the manifest directly
statusstatus: trueemit_status(text); empty text clears the field. TUI-only, a no-op in --print/ACP
skillsskills: truea starter skills/<name>/SKILL.md, mounted read-only when the extension is enabled
commandscommands: ["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

  1. Scaffold. scaffold_extension name=<name> [description=…] [language=python|typescript|rust] with the facets you need — tools=[…], hooks=[…], and/or prompt=…. This writes a package (manifest + server source) with the handler bodies stubbed. python and typescript (a dependency-free Node.js server) are single-file and need no build step; rust emits a serde_json-only crate. Pick the one whose toolchain the environment has; Python is the default.

    For rust, the scaffold result includes a build command — run it after editing to compile the binary into bin/ before installing. The zero-build templates skip that.

  2. 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 on tool_name/args. Keep stdout for protocol JSON only; log to stderr.
  3. 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.
  4. Verify. doctor_extension name=<name> — spawns the server, runs the handshake, and checks the served tools/prompt against the manifest. Fix any fail/warn before enabling. If the server won't spawn, check the shebang and that the command is executable.
  5. 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.
  6. 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 manifest name.
  • 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-run install_extension to pick up edits into the store.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.