desktop-shipped-skills
Skill42 starsChanged 10 days agoMITView on GitHub
Change the agent skills Hive Desktop ships into an agent workspace — the hive-flows, hive-actions, hive-settings, hive-webhook-sources, hive-mcp, hive-agent-workspaces SKILL.md files. Use when editing what one of those says or adding a new one.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- cli-autocalibrateSkill
- cli-smokeSkill
- cli-tuiSkill
- desktop-apiSkill
- desktop-commands-auditSkill
- desktop-devserverSkill
- desktop-ui-auditSkill
- desktop-ui-perfSkill
- docs-auditSkill
- docs-pageSkill
- go-enumSkill
- release-notesSkill
- release-prepSkill
- releaseSkill
- sqlcSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 80
Do not write install code paths for a new skill: If a change needs a branch outside the prompt registry, the skill is being modelled wrong …
- Distinctive: line 89
Keep them accurate about the current schema — the agent-workspaces prompt in particular, since it teaches the manifest shape.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Change a shipped skill
A shipped skill is a rendered prompt, not a file. cmd/desktop/internal/app/prompts
owns the text (ADR go-owned-llm-prompts) and cmd/desktop/internal/app/skills wraps it in
the Agent Skills SKILL.md format. app.SkillsService composes the two: slug
is hive-<prompt id> and the frontmatter description is the prompt's
description plus Use when configuring this in Hive Desktop (<target>).
Nothing installs a skill globally. A workspace enables a package, the
package's glob patterns select names out of the shipped set plus
.shared/skills/, and agentws.Generate renders the selection into that
workspace's .claude/skills/ and .agents/skills/
(ADR skills-are-declared-by-a-workspace, ADR skill-packages-are-the-unit-a-workspace-enables).
The .agents/skills/ files in this repo are the project's own dev skills and
have nothing to do with these — do not confuse the two.
Edit what a skill says
Prompt text lives in cmd/desktop/internal/app/prompts/templates/*.tmpl, never in a Go
string literal or a frontend component. Three rules decide which file to open:
- Wording shared by more than one prompt goes in
fragments.tmpland is composed with{{template}}— write a change once. - What a prompt says about a type comes from that type's own documentation
—
flow.NodeDocfor node types,actions.Docfor action types,mcpcatalog.Docfor MCP entries — spliced in by thesectionfunction. Fix the type's doc; do not restate it in the template. - Install-specific paths and URLs come from
.Env(FlowsDir,ActionsPath,SettingsPath,WebhookBaseURL,MCPEndpoint,AgentWorkspacesDir, and the*Enabledflags), so a rendered skill names the real file on that machine instead of a placeholder.
Add a skill
A template in templates/ plus one entry in definitions
(cmd/desktop/internal/app/prompts/prompts.go) with listed: true. Nothing else changes:
SkillsService.ShippedSkills reports whatever the catalog holds, so the
seeded hive package's hive-* pattern picks the new slug up and every
workspace that enabled that package carries it on its next open — no manifest
edited anywhere.
listed: false marks a context-scoped prompt that needs instance data only its
own editor has (webhook-transform) — it is rendered on demand and never
offered as a skill.
ValidateSkill enforces the Agent Skills naming rules: the slug is 1–64 chars
of lowercase letters, digits, and single hyphens, must not contain a reserved
word, and the description caps at 1024 characters — which the hive- prefix
and the appended target sentence must fit inside.
Validate
go test ./cmd/desktop/internal/app/... # prompts, the SKILL.md renderer, and SkillsService
mise run check # the pre-push gate: generate, tidy, lint, testcmd/desktop/internal/app/prompts/prompts_test.go is the real specification and asserts
against the registries, not fixed lists: every definition renders with no
unresolved template field, the flows and actions prompts cover every registered
node/action type, each prompt carries this install's paths, and rendering is
deterministic. Adding a node or action type without extending its doc fails
there. TestEveryShippedSkillRenders (cmd/desktop/internal/app/skills_service_test.go)
is the other half: a slug the catalogue advertises but RenderSkill refuses
would fail the open of every workspace whose package selects it.
Guardrails
- A rendered
SKILL.mdis generated output. Editing one under a workspace's.claude/skills/is silently replaced on the next open (ADR workspace-directories-are-generated-and-disposable). Change the template. - Do not write install code paths for a new skill. If a change needs a branch outside the prompt registry, the skill is being modelled wrong — it should be a template plus a registry entry.
- A prompt that cannot render headlessly cannot ship.
ShippedSkillscallsCatalog(Input{}), which silently omits a definition whosedataerrors, so such a prompt is simply absent from every workspace. That is what retiredhive-keybindings, whose body needed the frontend's command catalog. - A change to what these prompts say reaches a workspace on its next open. Keep them accurate about the current schema — the agent-workspaces prompt in particular, since it teaches the manifest shape.
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.

