Major Features / Agent Skills

Agent Skills

Agent Skills teach Heddle how to use tools, workflows, and domain practices without flooding every turn with long instructions.

How skills work

A skill is a folder with a standard SKILL.md file. The frontmatter gives Heddle lightweight catalog metadata such as name and description; the body contains the full instructions the agent should read only when the task calls for that skill.

This is progressive disclosure: the agent sees the catalog at session load, but it does not receive every full skill body up front. When a skill becomes relevant, Heddle can load the full SKILL.md and any linked resources.

Skills are useful when a tool is not enough by itself. A browser automation tool can open pages and click elements, but a browser research skill can explain when to snapshot, what evidence to collect, and which actions require extra care.

What the agent sees

Before loading a skill

Skill name
Short description from SKILL.md frontmatter
Source, such as project, user, or built-in
File path for auditability

After loading a skill

Full SKILL.md instructions
Referenced resources that the skill explicitly asks the agent to read
Scripts or assets packaged inside the skill folder when the workflow needs them

Where skills live

Heddle discovers skills from standard skill roots. Skill files remain in those folders; Heddle only stores activation state in the workspace state directory.

.agents/skills/<skill-name>/SKILL.md     # Project skills
~/.agents/skills/<skill-name>/SKILL.md   # User skills
built-in skill roots                     # Skills packaged with Heddle

Activating and disabling skills

Use the web control plane settings page to review discovered skills, search by name or description, and enable or disable them for the current workspace.

Terminal users can run /skills to list discovered skills, /skills enable <name> to activate one, and /skills disable <name> to turn one off.

Activation is workspace-scoped. Heddle stores the activation list under .heddle/skills/activation.json so each workspace can choose a different skill set.

Built-in skills ship with Heddle code. User and project skills stay in skill folders such as .agents/skills or ~/.agents/skills; Heddle does not copy their contents into state.

Trust and responsibility

Skills are instructions and local resources that can change how an agent approaches work. Enable skills you trust, review their SKILL.md files, and prefer project-owned skills for team conventions that should be visible in the repository. Heddle makes activation explicit, but users remain responsible for the skills they choose to install and enable.

Example SKILL.md

---
name: browser-research
description: Research web pages with browser snapshots, evidence capture, and safe navigation.
---

# Browser Research

Use this skill when the user asks you to inspect websites, compare products, or gather current web evidence.

Start with a browser snapshot, cite the page state you observed, avoid checkout or account-changing actions, and ask for confirmation before leaving the allowed domain set.