ironclaw/docs/drafts/agents/skills-format.mdx

---
title: SKILL.md Format
sidebarTitle: SKILL.md Format
description: YAML frontmatter schema for writing custom skills
---

A SKILL.md file has two parts: a YAML frontmatter block that controls when and how the skill activates, and a markdown body that gets injected into the LLM context when it does.

## Full Example

```yaml
---
name: kubernetes-deploy
version: 0.2.0
description: Kubernetes deployment and operations guidance
activation:
  patterns:
    - "deploy to.*production"
    - "rollback.*deployment"
    - "kubectl.*error"
  keywords:
    - deployment
    - kubernetes
    - kubectl
    - k8s
    - pod
    - namespace
  max_context_tokens: 2000
metadata:
  ironclaw:
    requires:
      bins:
        - kubectl
        - docker
      env:
        - KUBECONFIG
---

# Kubernetes Deployment Skill

You are operating in a Kubernetes environment. Follow these guidelines:

## Deployment Checklist

Before deploying to production:
1. Verify the image tag is pinned (never use `latest`)
2. Check resource limits are set on all containers
3. Confirm readiness and liveness probes are defined
4. Review the rollout strategy (RollingUpdate recommended)

## Common Commands

```bash
# Check rollout status
kubectl rollout status deployment/<name> -n <namespace>

# Rollback to previous version
kubectl rollout undo deployment/<name> -n <namespace>

# View pod logs
kubectl logs -l app=<name> -n <namespace> --tail=100
```

## Error Patterns

- `ImagePullBackOff` → Check image name, tag, and registry credentials
- `CrashLoopBackOff` → Check container logs and resource limits
- `Pending` → Check node resources and PVC availability
```

## Frontmatter Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique identifier for the skill. Used in `skill_list` output and log messages. Use kebab-case. |
| `version` | string | Yes | SemVer version string (e.g., `0.1.0`). Used for update detection from ClawHub. |
| `description` | string | Yes | One-line human-readable description. Shown in skill listings and registry search results. |
| `activation.patterns` | string[] | No | Regex patterns matched against the full incoming message. Any match raises the skill's score. |
| `activation.keywords` | string[] | No | Simple keyword matches (case-insensitive, substring). Each keyword match adds to the score. |
| `activation.max_context_tokens` | integer | No | Maximum tokens this skill may contribute per turn. Defaults to `SKILLS_MAX_TOKENS / 2` if omitted. |
| `metadata.ironclaw.requires.bins` | string[] | No | Binaries that must exist on `PATH`. Skill is gated out if any are missing. |
| `metadata.ironclaw.requires.env` | string[] | No | Environment variables that must be set. Skill is gated out if any are missing. |

## Activation Scoring

Skills are scored before selection. The scoring algorithm is deterministic:

- Each **keyword** match in the incoming message: +1 point
- Each **pattern** (regex) match: +3 points
- Skills with zero score are not injected (unless no other skills match)

When multiple skills score equally, they are ordered by `name` for reproducibility.

## Markdown Body

Everything after the closing `---` of the frontmatter is the skill's body. This is injected verbatim into the LLM system prompt when the skill activates.

Write the body as instructions to the agent:

```markdown
# My Skill

You are helping with [topic]. Follow these guidelines:

- Guideline one
- Guideline two

## Reference

Include tables, code examples, and structured information the agent
should have available when handling related requests.
```

### Body Guidelines

- Keep it concise — every token injected costs budget
- Write in second person ("You are...", "When the user asks...")
- Include concrete examples and reference tables where useful
- Avoid narrative prose — the agent prefers structured information
- Code blocks in the body are injected as-is into the prompt

## Minimal Skill Example

The simplest valid SKILL.md:

```yaml
---
name: git-helper
version: 0.1.0
description: Git workflow guidance
activation:
  keywords:
    - git
    - commit
    - branch
    - merge
---

# Git Helper

Follow conventional commits format: `type(scope): description`

Types: feat, fix, docs, style, refactor, test, chore

Always check `git status` before committing.
```

## File Location

Place your SKILL.md file in one of the trusted directories:

```bash
# Global skill (available everywhere)
~/.ironclaw/skills/my-skill/SKILL.md

# Workspace-scoped skill
<workspace>/skills/my-skill/SKILL.md
```

The directory name does not need to match the `name` field, but using the same value avoids confusion.

## Next Steps

<CardGroup cols={2}>
  <Card title="Skills Overview" icon="puzzle" href="/agents/skills">
    Activation pipeline, trust levels, and skill directories
  </Card>

  <Card title="ClawHub Registry" icon="package" href="/agents/clawhub">
    Share and discover skills from the community registry
  </Card>
</CardGroup>