---
name: deploy-skills
description: Deploy OpenClaw skills from infra/skills/ to agent servers via Ansible
---

# 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:

```bash
# 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

```bash
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

```bash
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

```bash
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:

```bash
# 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
