Deploy Skills to Agents

Push skill updates from infra/skills/ to one or all agent servers.

Important constraints

• Never use delete: true in the Ansible playbook — clients create their own custom skills on their agents. Deleting would wipe client work.
• Skills are Markdown files in infra/skills/<skill-name>/SKILL.md with optional references/ and templates/ subdirectories.
• Target path on agents: ~/.openclaw/workspace/skills/

Pre-deployment validation

Before deploying, validate the skills:

# Check all skills have a SKILL.md
for dir in infra/skills/*/; do
  if [ ! -f "$dir/SKILL.md" ]; then
    echo "MISSING: $dir/SKILL.md"
  fi
done

# Check for YAML frontmatter in each SKILL.md
for file in infra/skills/*/SKILL.md; do
  if ! head -1 "$file" | grep -q '^---'; then
    echo "NO FRONTMATTER: $file"
  fi
done

Deploy to all agents

ansible-playbook -i infra/ansible/inventory/hosts.ini \
  infra/ansible/playbooks/deploy-skills.yml \
  --vault-password-file infra/ansible/.vault_pass

Deploy to a specific agent

ansible-playbook -i infra/ansible/inventory/hosts.ini \
  infra/ansible/playbooks/deploy-skills.yml \
  --vault-password-file infra/ansible/.vault_pass \
  --limit <server-name>

Deploy a single skill

ansible-playbook -i infra/ansible/inventory/hosts.ini \
  infra/ansible/playbooks/deploy-skills.yml \
  --vault-password-file infra/ansible/.vault_pass \
  -e "skill_name=<skill-name>"

Post-deployment verification

After deploying, spot-check one agent:

# SSH into an agent and verify skills are present
ssh -i ~/.ssh/livia_deployer root@<IP> "ls -la ~/.openclaw/workspace/skills/"

# Check OpenClaw recognizes the skills (restart may be needed)
ssh -i ~/.ssh/livia_deployer root@<IP> "systemctl restart openclaw && sleep 2 && systemctl status openclaw"

Rollback

If a skill deployment causes issues:

1. Revert the skill file in git: git checkout HEAD~1 -- infra/skills/<skill-name>/
2. Re-deploy: run the deploy playbook again
3. Verify: check agent logs for errors