Skills

The skills command group lets you discover and use Hutly Skills — reusable capability bundles that Sammy and the agents route to. A skill is one of two shapes: a capability-only skill (an instruction set in Markdown, optionally shipping backing files as assets) that you load to read, or a workflow-backed skill that wraps a deployed workflow and can be executed with structured arguments.

A typical authoring flow is: skills new to scaffold a directory, edit content.md, skills validate to check it, then skills deploy to publish it. A typical consumer flow is: skills list to find a skill, skills describe for its metadata, and skills load (capability skills) or skills execute (workflow skills) to use it.

All skills subcommands operate against the organization resolved from your configuration (HUTLY_ORG_ID / .hutlyrc.yaml) and authenticate with your HUTLY_API_KEY. Discovery spans your org-owned skills plus the public catalog; your key’s role within the organization governs what you can deploy and execute.

Output is JSON by default. The --json flag is accepted everywhere as a no-op for compatibility, and --pretty pretty-prints the JSON.

The SKILL.yaml directory format

A skill lives in a directory containing a SKILL.yaml manifest plus its backing files. The manifest references those files through the same !include / !org_map / !var directives used by workflow YAML, so content is kept in a separate Markdown file and the workflow (if any) in its own YAML.

my-skill/
  SKILL.yaml      # manifest
  content.md      # the instruction body (via !include content.md)
  workflow.yaml   # optional backing workflow (referenced by the `workflow` field)
  assets/         # optional backing files bundled when assets: true

A scaffolded SKILL.yaml looks like:

name: my-skill
description: TODO — describe when Sammy should use this skill. Lead with the trigger phrase.
skillId: !org_map {}
category: my-category
visibility: private
content: !include content.md
tags:
  - my-skill
# Present only with --with-assets:
assets: true
requiredTools:
  - toolCode: code-interpreter
    configuration: {}

skills

skills new

Scaffolds a new skill directory with SKILL.yaml + content.md under <outDir>/<name>/.

hutly skills new my-skill
hutly skills new my-skill --category research --tags pdf,extract --public
hutly skills new my-skill --with-assets

skills list

Lists skills available to the org (org-owned + public). With -q, search defaults to semantic (embedding) matching so natural-language queries resolve hyphenated names (e.g. "web artifacts builder" finds web-artifacts-builder). Page through with --cursor when totalRows exceeds the page.

hutly skills list
hutly skills list -q "extract data from a pdf"
hutly skills list -q pdf --keyword
hutly skills list --include-internal
hutly skills list --cursor 20

Each row carries an executable flag (true when the skill has a backing workflow).

skills describe

Shows a skill’s metadata by ID — no content body. Use load to read the body.

hutly skills describe <skillId> --pretty

skills load

Loads a capability skill: prints its content and, if it ships assets, materialises them into ./skills/<name>/. Accepts a skill UUID or name — name lookup resolves across own-org + public skills, falling back to an exact-match semantic search. Asset downloads are cached against a local sha and skipped on a match unless --force is passed.

hutly skills load pdf-extract
hutly skills load <skillId> --no-assets
hutly skills load pdf-extract --out ./my-skills/pdf --force

skills execute

Executes a workflow-backed skill. Capability-only skills (no backing workflow) cannot be executed — load them to read their content instead. --args is a required JSON object matching the skill’s input schema (the backing workflow’s trigger schema).

hutly skills execute <skillId> --args '{"documentUrl":"https://…/lease.pdf"}'

skills deploy

Deploys a skill from a SKILL.yaml directory. Processes !include / !org_map / !var directives, validates tags and assets, deploys the backing workflow (if a workflow field is present), creates or updates the skill, and bundles + uploads declared assets. Lookup is by name, pinned to your own org’s private skills so a deploy never overwrites a same-named public skill seeded by another org. On success the resolved skillId is written back into SKILL.yaml — commit it.

hutly skills deploy ./skills/my-skill
hutly skills deploy ./skills/my-skill --dry-run
hutly skills deploy ./skills/my-skill --publish
hutly skills deploy ./skills/my-skill --var env=staging

skills validate

Validates a skill (SKILL.yaml + tag/asset checks + the backing workflow) without deploying. Accepts a skill directory, a direct SKILL.yaml path, or a container directory like skills/ to validate every skill underneath it.

hutly skills validate ./skills/my-skill
hutly skills validate ./skills/my-skill/SKILL.yaml
hutly skills validate ./skills --no-warnings

Top-level aliases

The following top-level commands mirror the skills subcommands.

deploy-skill

Alias for skills deploy. Deploys a skill from a SKILL.yaml directory; emits a deprecation notice steering you to skills deploy. Options match skills deploy (--publish, --dry-run, --force-new, -v, --var).

hutly deploy-skill ./skills/my-skill --publish

validate-skill

Alias for skills validate. Validates a skill, a SKILL.yaml file, or a container directory without deploying. Options match skills validate (--no-warnings, -v, --var).

hutly validate-skill ./skills

track-skill

Fetches a deployed skill by ID and reconstructs a local SKILL.yaml directory — writing SKILL.yaml, content.md, and workflow.yaml when the skill has a backing workflow. Use it to pull an existing skill into source control. The output directory defaults to a slugified ./<skill-name>/.

hutly track-skill <skillId>
hutly track-skill <skillId> --output ./skills/my-skill