agentleFS
hay-kothay-kot/hive-desktop/.agents/skills/shipped-skills/SKILL.md

shipped-skills

Skill4 starsChanged 2 months 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.

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

    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 …

    line 80
  2. Distinctive:

    Keep them accurate about the current schema — the agent-workspaces prompt in particular, since it teaches the manifest shape.

    line 89

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

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

Change a shipped skill

A shipped skill is a rendered prompt, not a file. internal/app/prompts owns the text (ADR go-owned-llm-prompts) and 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 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.tmpl and is composed with {{template}} — write a change once.
  • What a prompt says about a type comes from that type's own documentation — flow.NodeDoc for node types, actions.Doc for action types, mcpcatalog.Doc for MCP entries — spliced in by the section function. 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 *Enabled flags), 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 (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 ./internal/app/...       # prompts, the SKILL.md renderer, and SkillsService
mise run check                   # the pre-push gate: generate, tidy, lint, test

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 (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.md is 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. ShippedSkills calls Catalog(Input{}), which silently omits a definition whose data errors, so such a prompt is simply absent from every workspace. That is what retired hive-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.

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.