Tutorial 04 — Add a custom skill¶

The framework ships with 684 skills across 39 areas. This tutorial shows how to add a new one and have it discovered by the loader + router.

Prerequisites¶

Completed tutorials 01 + 02.

Step 1 — Choose an area¶

Skills live under <area>/.agents/skills/<skill_name>/. Pick an existing area or create a new one:

ls -d */.agents/skills 2>/dev/null | head -10

For this tutorial we'll add a skill under automation/:

mkdir -p automation/.agents/skills/scheduled-job/

Step 2 — Write the SKILL.md¶

Every skill is a markdown file with YAML frontmatter + body.

automation/.agents/skills/scheduled-job/SKILL.md:

---
name: scheduled-job
description: Set up a cron/systemd timer-based job with logging and rotation.
source_org: anthropic
sub_areas: [cron, systemd]
tier: gold
metadata:
  cost_estimate_usd: 0.05
  complexity: medium
---

# Scheduled Job

Use when the user wants a recurring task: backups, cleanups, polling, etc.

## When to use

- "I need to run X every Friday at 03:00"
- "Add a backup that runs nightly"
- "Schedule this script weekly"

## Steps

1. Identify the runtime (cron / systemd timer / Windows Task Scheduler).
2. Write the script (Python preferred for cross-platform).
3. Add logging with rotation.
4. Document timing + dependencies.
5. Provide a "test run" command.

## Output format

- The script file with shebang + permissions noted.
- The cron/timer definition.
- A README snippet for the runbook.

Step 3 — Validate with the loader¶

python -c "
from src.skills.loader import SkillLoader
ldr = SkillLoader()
ldr.load_all()
print('Total skills:', len(ldr.skills))
skill = ldr.skills.get('scheduled-job')
print('Found:', skill)
"

You should see the skill listed.

Step 4 — Run audits¶

python scripts/audit.py
python scripts/audit_semantic.py

Both must report CLEAN. If they don't, the most common issues are: - Missing frontmatter (the --- fences must be the first lines) - name: doesn't match the folder name - Invalid YAML (use 2-space indent, no tabs)

Step 5 — Add to the curated registry (optional)¶

If your skill should be discoverable via _skills-registry.yaml:

# docs/reference/registries/_skills-registry.yaml
scheduled-job:
  area: automation
  tier: gold
  description: Cron/systemd timer-based recurring job

Step 6 — Execute the skill via tool-use¶

With SkillExecutor, the skill becomes runnable code:

from src.skills.loader import SkillLoader
from src.skills.executor import SkillExecutor, SkillExecutorContext

ldr = SkillLoader()
ldr.load_all()
skill = ldr.skills["scheduled-job"]

# In Claude Code flow: you (Claude) would be the executor.
# Programmatic usage requires an anthropic-compatible invoker:
# ex = SkillExecutor(invoker=anthropic_invoker)
# result = ex.execute(skill=skill, agent_id="automation-specialist",
#                     task="Set up a nightly backup at 03:00 UTC",
#                     context=SkillExecutorContext(cwd=".", allow_write_paths=["scripts/", "deploy/"]))

What you just did¶

Added a new skill discoverable by SkillLoader
Made it executable via tool-use (SkillExecutor)
Added it to the curated registry for routing
Validated with the audit gates