Skills

A skill is a folder with a SKILL.md file that teaches Hull how to do one kind of task, such as releasing a package, writing a migration or following your API design rules. Skills follow the open Agent Skills format, so skills written for other agents work in Hull too.

Unlike instructions, skills don't fill up every session. Hull sees only each skill's name and description. When a task matches, the agent loads the full skill, and any files it points to.

How Hull uses a skillCopy Anchor Link

1. When a session starts, Hull finds every skill and reads its name and description.
2. The agent sees that list. When your request matches a description, it calls the skill tool to load the instructions.
3. The agent follows the instructions, and reads bundled files or runs bundled scripts as needed.

The description is what the agent matches against, so write it the way people ask for the task. You can also ask for a skill by name ("use the release skill"), or run it directly as a slash command: every skill is also available as /<skill-name>.

Create a skillCopy Anchor Link

Create a folder for the skill with a SKILL.md inside:

.hull/skills/
└── release/
    ├── SKILL.md
    └── scripts/
        └── bump-version.sh

SKILL.md starts with YAML frontmatter, followed by the instructions:

---
name: release
description: Release a new version of the package. Use when asked to cut, publish or tag a release.
---

# Release

1. Make sure the working tree is clean and `main` is up to date.
2. Run `scripts/bump-version.sh <major|minor|patch>`.
3. Update CHANGELOG.md with the changes since the last tag.
4. Commit, tag `v<version>` and push the tag.

Other fields from the Agent Skills format, such as license and metadata, are allowed.

Put supporting files next to SKILL.md, for example in scripts/, references/ or assets/, and mention them in the instructions so the agent knows when to use them.

Where skills liveCopy Anchor Link

Hull also reads skill/ as well as skills/, and the legacy .hullcode/ folders. Project skills load only after you trust the project.

To load skills from other folders or from a URL, add them to hull.json:

{
  "skills": {
    "paths": ["./tools/skills", "~/shared-skills"],
    "urls": ["https://example.com/.well-known/skills/"]
  }
}

Set HULL_DISABLE_EXTERNAL_SKILLS=1 to skip the .agents/ and .claude/ folders.

Give every skill a unique name. If two skills share a name, Hull loads only one of them and logs a warning.

Hull ships with one built-in skill, hull-config, which helps the agent answer questions about Hull's own configuration. A skill of yours with the same name replaces it.

Control which agents can use skillsCopy Anchor Link

Skills follow the skill permission. For example, to let an agent use only two skills:

{
  "agent": {
    "docs-writer": {
      "permission": {
        "skill": { "*": "deny", "docs-style": "allow", "release-notes": "allow" }
      }
    }
  }
}

Find and share skillsCopy Anchor Link

• Install skills from the Marketplace.
• Commit project skills in .hull/skills/ to share them with your team.
• Publish a folder of skills at a URL and add it to skills.urls.

See and reload skillsCopy Anchor Link

• In the CLI, run /skills to browse skills. Run hull debug skill to list every skill Hull found.
• In VS Code, open Settings > Agent Behaviour > Skills.
• After adding or editing a skill, run /reload in the CLI, or Hull Code: Reload Config and Skills in VS Code. A new session also picks up changes.

When the agent uses a skill, you'll see a skill tool call in the conversation.

TroubleshootingCopy Anchor Link

• The skill doesn't appear. Check that the file is named SKILL.md, sits directly in the skill's folder (skills/<name>/SKILL.md) and has a name in its frontmatter. Then reload.
• The agent doesn't use it. Make the description more specific about when to use the skill, or ask for it by name.
• A project skill is missing. Check that you trusted the project.

RelatedCopy Anchor Link

• Instructions and rules
• Commands and workflows
• Custom agents