# Acryl Build Extension

> Use when the user asks you to add a feature, tool, panel, command or integration to ACRYL itself (build a plugin or extension). The end-to-end workflow, from reading the docs to a live plugin.

- Skill: `acryldev/acryl-build-extension` (Agent Skill)
- Install (CLI): `npx skillmds@latest add acryldev/acryl-build-extension`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acryldev/acryl-build-extension/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: acryldev (https://skillmd.com/u/acryldev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/acryldev/acryl-build-extension

---

# Build an ACRYL extension

1. Read {{pack}}/docs/start-here/this-runtime.md completely (contracts, delivery).
2. Decide WHERE it mounts and on which surfaces: read {{pack}}/docs/maps/mount-points.md (CLI has terminal overlays; Web and Desktop have
   client slots; tools, commands, prompts and skills work everywhere). Ask or check which surface the user is on
   if it matters (the router and acryl_workspace_status help). For an unfamiliar kind of plugin see {{pack}}/docs/maps/taxonomy.md.
3. Pick the plugin type(s) the feature needs and open the matching doc from {{pack}}/docs/README.md
   (tool, service, event hook, config, prompt, client UI, host route, tui command). Read it completely and
   follow its cross-references.
4. Open the closest working example in {{pack}}/example-plugins/README.md and read every file of it. Copy it into a
   NEW directory <workspace>/.acryl-extensions/<plugin-name>/ (outside the pack) and change it. Never guess a plugin's shape from memory.
5. Write the package (package.json, cordis.patch.yml, index.js, and client.js for UI). Declare honestly in package.json: `"acryl": { "apiVersion": 1, "permissions": [...] }` (fs.read, fs.write, net, shell, secrets, ui); the human sees the permissions before a new extension is installed. Write it under `<workspace>/.acryl-extensions/<name>/` (this project) or `<ACRYL home>/extensions/<name>/` (all projects and surfaces on this home).
6. Call the acryl_install_plugin tool with the ABSOLUTE path of that directory. Read its result. Fix the named cause and call it
   again if it fails; it undoes failed installs.
7. Tell the user what you built, whether it is live, and (for UI) that they should reload the page or window.
   Do not claim it works before the tool result says so. You cannot publish to the marketplace; say what
   remains if the user wants that.