Skill Authoring

Skills are reusable prompts for Claude Code. They are defined as SKILL.md files and version-controlled.

SKILL.md structure

---
name: my-skill
display_name: My Skill
description: A one-line description of the skill
---

Write your prompt body here.

Frontmatter

Field	Required	Description
name	Yes	Slug identifier (/^[a-z0-9-]+$/)
display_name	Yes	Human-readable display name
description	Yes	One-line description of the skill
requires	No	Dependency declarations (see below)

Declaring requirements

Skills can declare external dependencies in the requires block. These are checked before workflow execution to verify the minion has the necessary tools and configuration.

---
name: lancers-compe-search
description: Search Lancers competitions
requires:
  mcp_servers: [playwright, supabase]
  cli_tools: [git, node]
  env_vars: [LANCERS_EMAIL, LANCERS_PASSWORD]
---

Field	Description
mcp_servers	Required MCP servers (checked against ~/.mcp.json)
cli_tools	Required CLI tools (any tool name — dynamically checked via which on the minion)
env_vars	Required environment variables (checked across minion-local variables/secrets and HQ-injected project/workflow variables)

Skills without a requires block are treated as having no external dependencies.

Prompt body

Written in Markdown format. Claude Code receives this text as instructions and executes accordingly.

Variables and Secrets

Skills can reference external values using two mechanisms: template variables for configuration parameters, and secrets for sensitive credentials.

Template variables ({{VAR_NAME}})

Use {{VAR_NAME}} syntax in your skill body to insert variable values at execution time.

---
name: deploy-site
description: Deploy a website to the target environment
---

Deploy {{SITE_URL}} to {{DEPLOY_TARGET}}.

Variables are defined at four scopes. When the same key exists in multiple scopes, higher-priority scopes override lower ones:

Priority	Scope	Where to set	Description
1 (lowest)	Workspace	HQ Dashboard → Workspace Settings	Shared across every minion and project in the workspace
2	Project	HQ Dashboard → Project Settings	Shared across project members
3	Workflow	HQ Dashboard → Workflow Settings	Per-workflow overrides
4 (highest)	Minion	HQ Dashboard → Minion Settings, or PUT /api/variables/:key	Per-minion final override applied at runtime (12-factor style)

• Variable names: alphanumeric and underscores only (\w+)
• Undefined variables remain as {{VAR_NAME}} in the output (no error)
• Template expansion happens at execution time, not when the skill is deployed
• Workspace/project/workflow values are expanded by HQ before the SKILL.md reaches the minion; the minion-local variables are layered last so a minion operator can always override deployed defaults without coordinating a HQ change

Secrets ($SECRET_NAME)

Secrets are injected as environment variables into the execution process. Use them for API keys, passwords, and other sensitive values.

---
name: check-api
description: Health check an external API
requires:
  env_vars: [API_KEY]
---

Call the API endpoint using the API key from the $API_KEY environment variable.

Secrets are set via the HQ Dashboard (Minion Settings) or PUT /api/secrets/:key. Unlike variables:

• Secret values are never returned by the list API (keys only) and are never persisted in HQ DB. HQ acts as a pass-through; values live exclusively on the minion.
• Secrets are not expanded as {{VAR}} templates — they are available as $ENV_VAR in the process environment
• Use requires.env_vars in frontmatter to declare required secrets for pre-execution validation

Secret scopes (multi-workspace)

A minion can serve multiple workspaces. To prevent leakage, secrets are stored per scope on the minion:

Scope	Stored as	Seen by sessions where…
Minion-wide	workspace_id=''	Always (any workspace, ad-hoc commands)
Workspace-scoped	workspace_id=<uuid>	The runner’s execution is bound to that workspace

When the same key exists in both scopes, the workspace value wins. Skills don’t need to know which scope a secret came from — they reference it as $KEY either way.

Pick the scope when setting a secret in the dashboard:

• Minion-wide for credentials shared across every workspace this minion serves (e.g. the operator’s personal OPENAI_API_KEY for development).
• Workspace-scoped for customer- or tenant-specific credentials. Setting it on each workspace independently ensures workspace A’s keys are never visible during workspace B’s execution.

Skill management

Local deployment

Skills are placed at ~/.claude/skills/<name>/SKILL.md on the minion.

# List locally deployed skills
minion-cli skill list --local

Syncing with HQ

# List skills on HQ
minion-cli skill list

# Fetch a skill from HQ and deploy locally
minion-cli skill fetch <name>

# Push a local skill to HQ (new version auto-created)
minion-cli skill push <name>

Accompanying files

Skills can include template and configuration files alongside SKILL.md. All files in the same directory are managed as part of the skill.

~/.claude/skills/my-skill/
├── SKILL.md           # Prompt body
├── template.html      # Template file
└── config.json        # Configuration file