Skill Authoring
Skills are reusable prompts for Claude Code. They are defined as SKILL.md files and version-controlled.
SKILL.md structure
Section titled “SKILL.md structure”---name: my-skilldisplay_name: My Skilldescription: A one-line description of the skill---
Write your prompt body here.Frontmatter
Section titled “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
Section titled “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-searchdescription: Search Lancers competitionsrequires: 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
Section titled “Prompt body”Written in Markdown format. Claude Code receives this text as instructions and executes accordingly.
Variables and Secrets
Section titled “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}})
Section titled “Template variables ({{VAR_NAME}})”Use {{VAR_NAME}} syntax in your skill body to insert variable values at execution time.
---name: deploy-sitedescription: 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)
Section titled “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-apidescription: Health check an external APIrequires: 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_VARin the process environment - Use
requires.env_varsin frontmatter to declare required secrets for pre-execution validation
Secret scopes
Section titled “Secret scopes”A minion belongs to one workspace, and its secrets are stored on the minion for that workspace. A run gets only the secrets its skill declares in requires.env_vars. If the minion still keeps anything for another workspace, it removes that (secrets included) the next time it connects.
Minions of the previous version (Node.js) also have a minion-wide scope (workspace_id=''), seen by every session on the minion; a workspace value with the same key wins over it.
Skill management
Section titled “Skill management”On the minion
Section titled “On the minion”When a minion runs a skill, Minion Workspace hands it the skill’s current version, placed at ~/.claude/skills/<name>/SKILL.md on the minion. Editing that copy changes nothing: the next run gets the skill from Minion Workspace again.
Changes a minion makes
Section titled “Changes a minion makes”A minion can propose a change to a skill (or a new skill) with hq push skill <name>. On Minion (the current version), it arrives as a draft: the skill doesn’t change, and no run uses the draft, until someone in the workspace reviews it under Skills → Drafts from minions and publishes it.
Minions of the previous version (Node.js) use minion-cli skill list|fetch|push; their push creates a new version directly.
Accompanying files
Section titled “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 fileSharing outside the workspace
Section titled “Sharing outside the workspace”You can publish a skill so people outside your workspace can read it, and copy it into their own workspace. See Public sharing for how, and What gets published for what they can see.