Skills

A skill is a folder of instructions, and sometimes scripts, that teaches an agent a repeatable task: how your team deploys, reviews a migration, or writes a release note. In hob you install a skill once and it works in every backend. hob also decides which skills agents may use. It trusts a skill by its exact content, not by where the file happens to be, so a skill that changes waits for you again.

Open the Skills view from the toolbar or the command palette, or run hob open view skills.

Where skills come from

Each skill has a metadata.uuid in its SKILL.md, and the value must be a UUID. The UUID keeps a skill's identity when it is renamed or copied. A personal or project skill without one is listed as Needs a UUID; select Add UUID to add it. hob adds only that one line to the file.

A skill's name is what people and agents type after /, such as /release-notes: lowercase letters, digits, and single dashes. An optional title in metadata.title, such as "Release notes", is for people. hob shows the title first and the /name after it; a skill without a title shows only its /name. The title never decides which skill runs or what is trusted.

When two skills share a name, the Skills view shows both. A built-in, personal, or organization skill keeps the name over a project skill, so a repository cannot replace your /deploy. Select Use for /name to choose a different one.

Review a skill

New project skills, changed skills, and organization installs appear under Waiting for review. Select Review to open the review over the Skills view. It says why the skill waits, which version it moves from and to, and what approving allows, for example that agents in this project can use /deploy at exactly this version. A new skill shows each file as plain text. A changed skill shows the differences in each changed file since the version you approved. A text file larger than 256 KiB is not shown inline; select View full file to read it. Binary files are listed by name and size only. To approve binary scripts, you confirm that you approve them without reading them.

A skill can need up to two kinds of approval:

• Instructions: the text the agent reads.
• Bundled scripts: files the agent can run inside its own sandbox.

When you approve, hob keeps a read-only copy of that exact version. Agents only ever receive paths into that copy, so a later edit to the files cannot change what you approved. Any change to the skill, even to a supporting file, brings it back for review.

For a repository you already trust, set This project's skills to Trust this project's skills. Changes are then used without a review, and hob still records each version. The setting belongs to this project and its Git remote on your computer; a repository cannot turn it on for itself.

Use a skill

Type / in an agent's composer. Each hob skill appears once in the hob group. A skill that cannot run yet is dimmed and says why; choosing it opens its review instead of adding it to your message. What you type matches the name and the title, so /rel and /Release both find "Release notes". Choose it, add any arguments, and send. hob renders the skill when the message leaves the queue, so a skill you change while the message waits is checked again. If the skill needs review, the message is not sent, your draft stays in the composer, and Review opens it.

Agents can also start a trusted skill on their own when it fits the task, in every backend. They see only its name and description until they run it, and a skill that waits for review is not offered to them at all. An agent that was already running may need a new session before it uses a new skill on its own; /name works at once.

The Skills button shows how many skills and updates wait for your review, so you see them without opening the view. A skill that an organization's policy updated on its own says so on its row.

Commands in a skill

hob runs nothing for a skill. A line such as !`git status` reaches the agent as an instruction to run that command itself, inside its own sandbox and with your usual permission prompts, and to use the output. hob skill check warns about these lines, so you can write the instruction in plain words instead. For commands that must run on this computer, use an automation.

Share skills with an organization

An organization is a Git repository in the hob organization layout. A personal repository works too, for example to share your setup between computers. In Settings → Trust, select Add organization, and give the Git URL and, optionally, a branch or tag. hob uses your own Git credentials and never prompts, so load SSH keys into ssh-agent or configure a Git credential helper.

Adding an organization makes its skills available; it does not install them. Review and install each skill you want. When the organization changes, the installed skill keeps running the version you approved, and the update waits for review.

An organization set to Trust this organization's skills installs without a review, and updates on its own when the update is a higher version (a higher semver metadata.version) or changes only the icon. Any other change waits for your review: the Skills view says whether it has no new version or looks like a downgrade. The update review shows the new entries of the skill's CHANGELOG.md above the differences. Trusting an organization means trusting everyone who can write to its repository. If you set the organization back to review or remove it, the trust that rested on it ends; your own approvals stay.

hob checks each organization once an hour, and when it starts or you open the Skills view after that time. It asks the remote where the branch points and fetches only when it moved. The repository can set another interval, and Check for updates in the organization's settings overrides it on your computer. Check now checks at once, and Check for updates in the Skills view checks every organization and tracked skill. An organization with no successful check for a day, or for 24 intervals when that is longer, is marked as possibly out of date.

Trusted publishers

In Settings → Trust, Publishers and tracked skills lists the publishers you trust: public keys or root certificates of people or teams who sign skills with OpenSSF Model Signing, a skill.oms.sig file in the skill folder. A publisher's signature applies to your tracked skills, and to the organizations that vouch for it, which you select when you edit an organization. A skill version signed by such a publisher is trusted without a review, even in an organization whose other changes you review, and the skill shows who approved it. Removing a publisher, changing its key, or unselecting it removes the trust its signatures gave.

Your keys

Settings → Trust → Your keys lists the keys you sign with. Create device key makes a key that lives only on this computer. Add SSH key from agent adds a key your SSH agent holds, such as a key on a hardware security key; hob never reads its private half and asks the agent to sign. Retire stops a key from signing. A retired device key's private half is deleted.

Shared panes and issues, and the project skills you sign, are signed with one of your keys: the newest, or the one you choose with Use for signing. For shares, when that key counts as your member key in an organization, the share goes to your member folder, and teammates who have the organization see it as Verified. Otherwise it goes to a folder named after the key and shows as Unverified until the key is linked to a member. hob hides a share whose signature does not check out, and lists its file and the reason so you can fix it.

hob finds your SSH agent in this order: the SSH agent socket you set in Your keys, then SSH_AUTH_SOCK, then IdentityAgent in your ssh configuration. hob asks ssh -G to read the configuration, so agents such as 1Password and Secretive work when you set IdentityAgent under Host *. Your keys shows which agent hob uses.

hob stores a device key's private half in a file that only your user account can read. Any program that runs as your user can read it too. For stronger protection, use an SSH key held in an agent or on a hardware key.

Sign a project skill

A signature on a project skill vouches for it to your organization. Open the skill in the Skills view and choose Sign. You can sign only a version you approved: if you have not approved it yet, Approve and sign shows the full review, then records your approval and signs in one step. A device key writes skill.oms.sig; a key in your SSH agent writes skill.ssh.sig. Your approval carries over to the signed version, because only the signature file changed.

When teammates open the project, hob checks the signature against the members of their organizations. If the signer is a member with an active key and the organization's skills are trusted, the skill is trusted without a review. If the organization reviews each change, the review names the signer. A signature by a retired key gives no new trust, and revoking the key removes the trust it gave.

Organization members

An organization lists its members and their keys in members/. Each member has a member.json with a name and one or more public keys: hob device keys and SSH keys, each marked active, retired, or revoked.

A member counts in two steps.

1. The entry is valid. An admin signed it, or the organization accepts unsigned entries. Admins are the keys under adminKeys in hob-org.json. Their signatures count only after you accept the admin keys in Trust, so a person who can write to the repository cannot add an admin alone. Confirm the fingerprints with your organization's admins before you accept them.
2. The entry is accepted. Edit the organization to choose its Members policy. Review each new member and change waits for you to accept each new member, new key, or other change in Trust. Trust this organization's member list accepts valid entries as they are.

Changes that remove trust apply at once, without a review: a removed member, a removed key or admin key, and a key changed to retired or revoked. A retired key keeps what it already signed. A revoked or removed key also loses what it signed. A key changed back to active waits for review again.

To join an organization, open Your keys > Add to organization. Choose the organization, a member ID, and your keys. hob gives you the member.json text, or for an existing member the key entries to add. Add it in a pull request; hob does not change the organization's repository. If your organization signs member entries, an admin signs the file after the change:

ssh-keygen -Y sign -n hob-member -f <admin key> members/<member-id>/member.json

Agents can read members with hob trust members and print an entry with hob trust member-entry. Only you accept admin keys and members.

Every trust decision in one place

Settings → Trust → Approvals lists every trusted skill and shared automation once, grouped under Skills and Automations. Filter them by name or source. Each row says whether the version that runs now is approved, or whether only earlier versions are. Expand a row to see each version, what it may do, and what approved it, for example Approved by you, Trusted by Acme's policy, Signed by Acme Signing, or Trusted by this project's setting. You can revoke your own approvals there. Other approvals change where they were set.

Revoke old approvals keeps only your approval of the current version. Use it on one row, or on a whole group. Revoke all removes every approval you gave an artifact. Its skill then waits for your review again, and its automation asks again before its next run. An approval whose organization you removed is marked Organization removed, and one whose tracked skill you stopped is marked No longer tracked; revoke it to free the copy hob keeps. Agents can read all of this with hob trust list; only you can change it.

Organization layout

hob-org.json
skills/<folders>/<name>/SKILL.md
members/<folders>/<member-id>/member.json
members/<folders>/<member-id>/member.json.sig   (optional admin signature)

hob-org.json makes the repository an organization:

{
  "schema": 1,
  "id": "<a new lowercase UUID>",
  "name": "Acme",
  "refreshSeconds": 3600,
  "adminKeys": [{ "key": "ssh-ed25519 AAAA...", "label": "IT" }]
}

refreshSeconds is optional, from 300 (5 minutes) to 604800 (7 days). adminKeys is optional; each key is a public key in authorized_keys form.

A member.json looks like this. The member ID is the folder name:

{
  "schema": 1,
  "id": "alice",
  "name": "Alice Example",
  "keys": [
    { "publicKey": "ssh-ed25519 AAAA...", "label": "laptop", "status": "active", "added": "2026-09-27" }
  ]
}

hob accepts Ed25519, ECDSA, RSA (2048 bits or more), and hardware security keys ([email protected]). A key belongs to one member; a key listed by two members makes both unusable. A member folder can hold an icon.png, icon.webp, or icon.jpg picture, with the same rules as skill icons.

The id and the repository URL together identify the organization, so a repository that copies another's hob-org.json is a different organization. A repository without the file is not an organization; use Import for skills from other repositories.

Put each skill in its own folder under skills/. Up to four folders above a skill, for a department or kind, help you match CODEOWNERS. Folders never change a skill's identity: a skill that moves keeps its approval and its installation. Skill names and UUIDs must be unique across the repository; a duplicate makes both skills unusable, and the Skills view shows the error. An optional metadata.tags in SKILL.md, such as tags: "release, ops", helps you find skills; tags never affect trust. An optional metadata.version, such as version: "1.2.0", labels each version as v1.2.0 · a1b2c3d; the content, not the label, decides whether a skill changed.

A skill folder can hold an icon.png, icon.webp, or icon.jpg: square, at most 512×512 pixels and 64 KiB. hob shows it in the Skills view and the slash menu and never sends it to an agent. Other icons are ignored with a warning.

Create or edit a skill

Select New skill in the Skills view or the command palette. hob creates a draft at once and opens the New Skill screen: a builder agent on the left, and the skill on the right. Describe the skill to the agent, or fill in Configuration yourself: the title, the name, and the description. A new skill takes its name from the title until you type one, and the name is checked as you type. Until the first save you can also choose where the skill goes:

• This project: .hob/skills/<name> in the project.
• An organization: skills/<name> in a local checkout of an organization you added. hob checks that the checkout's hob-org.json names that organization.
• Your personal skills: for every project.

The agent and you edit a draft that hob keeps outside every repository, so nothing reaches the destination until you save. The File tab shows the skill's files and a live check. Unsaved work is listed under Drafts. If you leave a new skill before you change it or write to its agent, hob deletes the draft.

The builder and its agent stay with the skill after the first save. To change a project, personal, or organization skill, select Edit on its row: the same builder opens, and its agent continues with everything it knows about the skill. For an organization skill, choose your local checkout first. You can change its title, name, and description, but not its destination. A new name takes effect when you save: hob renames the skill's folder and keeps its UUID, your approvals, and your choices for the name. Installed organization skills and tracked skills change in their own repositories.

Create skill or Save changes shows the differences and the check, then writes the skill. A check error stops the save, and so does a name that the destination already uses. The check reports what a new skill's template still holds, such as its placeholder name, description, or steps, so an untouched draft cannot be saved. After a save, Try /name opens an agent with the skill in its message. For the project and your personal skills, saving also approves exactly that version. For an organization, saving approves nothing: commit the skill and open a pull request, and the organization's policy trusts it after the merge and the next fetch. If the skill changed on disk since the draft was made, choose whether to replace those changes. Discard changes returns the draft to the saved skill and keeps the agent. Deleting a new skill's draft deletes its agents too.

To start over with a fresh agent, for example when its backend is no longer available, open the agent's menu and select New agent. It uses your current agent defaults. Earlier agents stay under Agent history in the same menu, and you can return to one there, as in the automation builder.

Import skills you already have

Under Import, choose where the skills are: Claude Code, Codex, or OpenCode, a folder on this computer, or a Git repository (with an optional branch or tag and folder). hob uses your own Git credentials and never prompts. Then:

• Copy selected to this project: each copy gets its own UUID and waits for review. The original does not change.
• Copy to personal: personal skills are trusted as your own work, so hob shows the skill's review first, and your approval is recorded with the copy.
• Track updates (Git only): install one skill from the repository and keep it linked. hob checks it like an organization; every update needs your review, unless a publisher you trust signed a higher version. A skill without a UUID gets one that hob keeps; nothing is written to the repository. A tracked skill never takes a /name that another skill uses. Stop tracking removes it.

hob records where each copy came from. Tracked skills are also listed in Settings → Trust → Publishers and tracked skills.