Lesson 05 — Add a skill

You are here: Lesson 5 of 8 · ← LLM model · Hub · Next: Workflow →

Goal

Author a skill card in Git (skills/aac-hello.md) and sync the card body into the tenant catalog so the agent can discover and load it with the built-in search_skill / load_skill tools.

What you will change

skills/aac-hello.md
Full root: steps/05-skill/

Why it matters

Personas should stay short. Repeatable procedures belong in skills (discoverable cards) and runbooks (stage SOPs — next lessons). Skills are how teams share “how we do X” without pasting essays into every agent.

ELI5: The persona is the job title. The skill is a laminated checklist the agent can pull from the drawer.

Critical gotcha — apply ≠ upload

Artifact	Uploaded by `tofu apply`?
Agent	Yes
Skill file in git	No — source only
Skill body in tenant catalog	No — needs skillsync
Stage `skill_refs` (names)	Yes (Lesson 06 pins the name)

Full ops guide: Skills sync.

Built-in skill tools (no HITL entry needed)

search_skill, load_skill, note, and read_notes are already on Aiden’s always-allowed list. Do not re-list them under hitl.always_allowed — that section is for tools that are not built-in (for example ${integration_name}_test_connection from Lesson 03).

resource "sg_agent" "tutor" {
  # ...
  # Skill tools work without adding them here.
  hitl = {
    always_allowed = [
      "${local.github_integration_name}_test_connection",
    ]
  }
}

Skill card shape

---
name: aac-hello
description: Short greeting procedure for the Agent as Code tutorial agent.
---

# AAC hello skill

When the user asks for a greeting...

The front-matter name must match what you later put in skill_refs.

Apply & verify

cd examples/scenarios/agent-as-code/steps/05-skill
tofu init && tofu apply
tofu output skill_source_path
tofu output tutorial_skill_name

Then:

In Aiden OS, register a skill source pointing at examples/scenarios/agent-as-code/steps/05-skill/skills/ (or your fork path).
Run skillsync and wait for success.
Chat with aac-tutor using this sample prompt:

Search for the aac-hello skill, load it, and follow it exactly.

Assert: The agent calls search_skill / load_skill and replies with:

Hello from Agent as Code.
Skill: aac-hello

(The body should match the git skill file.)

Gotchas

Green apply with failing search_skill almost always means skillsync was skipped.
Lesson 06 pins skill_refs on the workflow stage so the procedure is not discovery-only.

Checkpoint

Skill file committed in the step folder
Skillsync completed for that path
Agent can search_skill / load_skill aac-hello

Next: Lesson 06 — Workflow (one stage)