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 three scopes. When the same key exists in multiple scopes, higher-priority scopes override lower ones:

Priority	Scope	Where to set	Description
1 (lowest)	Minion	HQ Dashboard → Minion Settings, or `PUT /api/variables/:key`	Minion-local configuration
2	Project	HQ Dashboard → Project Settings	Shared across project members
3 (highest)	Workflow	HQ Dashboard → Workflow Settings	Per-workflow overrides

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

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)
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

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