Skip to content

Skill Authoring

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

---
name: my-skill
display_name: My Skill
description: A one-line description of the skill
---
Write your prompt body here.
FieldRequiredDescription
nameYesSlug identifier (/^[a-z0-9-]+$/)
display_nameYesHuman-readable display name
descriptionYesOne-line description of the skill
requiresNoDependency declarations (see below)

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]
---
FieldDescription
mcp_serversRequired MCP servers (checked against ~/.mcp.json)
cli_toolsRequired CLI tools (any tool name — dynamically checked via which on the minion)
env_varsRequired 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.

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

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

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:

PriorityScopeWhere to setDescription
1 (lowest)WorkspaceHQ Dashboard → Workspace SettingsShared across every minion and project in the workspace
2ProjectHQ Dashboard → Project SettingsShared across project members
3WorkflowHQ Dashboard → Workflow SettingsPer-workflow overrides
4 (highest)MinionHQ Dashboard → Minion Settings, or PUT /api/variables/:keyPer-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 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

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.

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.

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.

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

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.