Skills — When to write one
Decide between a Skill, a Function, an App, or just exec.
You can solve almost any user request with hrbr exec. So why publish
anything? Because published artifacts (Skills, Functions, Apps)
get reused. The question is which form fits.
Decision tree
Mermaid render failed: org.eclipse.elk.core.UnsupportedConfigurationException: Layout algorithm 'layered' not found for Root Node root
Skills carry intent + procedure
A Skill is a markdown file with a YAML frontmatter manifest. The body is the human-readable explanation; the manifest is the machine-readable trigger + workflow.
Trigger: "Use when the user names a Sentry issue and wants a Linear ticket created."
Workflow:
sentry.get_issue→linear.create_issuewith arg mapping.
Agents discover skills via the agent-skills protocol and invoke them when the user intent matches the trigger description. Without skills, the agent has to guess.
Skills vs Functions
| Skill | Function | |
|---|---|---|
| Trigger | User intent (LLM-routed) | Explicit name (CLI / API / App) |
| Format | Markdown + manifest | TypeScript defineJob |
| Reuse | LLM hosts pick it up | Dashboard or SDK clients can invoke it |
| Versioning | Workspace history / git | Explicit @vN |
| Best for | Things you describe in English | Things you describe in code |
The same logic can ship as both — see Recipe: incident-triage where the same Sentry→Linear→Slack flow appears as an exec, a Function, and a Skill.
When NOT to write a Skill
- The user calls the same code from the CLI or a script — Functions are faster to invoke and pricier to maintain as a Skill.
- The work is one-off / experimental — stay in
hrbr exec. - The trigger is "every Monday at 9 AM" — schedule a Function instead.
- The trigger is "POST hits this URL" — that's an App.