# Adding Your Own Skills

Learn the `SKILL.md` structure needed to add a stage and route requests to it.

## Learning Objectives

By the end of this lesson, you’ll be able to:

- **Describe** the frontmatter and body of a `SKILL.md`.
- **Write** a `description` that routes the agent to your stage.
- **Ground** a skill in the base code so it never invents paths.

## Where Skills Live

Every skill is a single `SKILL.md` whose directory name matches the skill’s `name`. In the
source repo, skills live under `skills/`; when installed, they may live in your agent’s
configured skills directory.

```none
skills/
  i4h-workflow/SKILL.md            # routing / overview
  i4h-workflow-validate/SKILL.md   # per-stage skill
  i4h-workflow-<your-stage>/SKILL.md   # the one you'll add
```

## Anatomy of a SKILL.md

A skill has two parts: a YAML **frontmatter** block that tells the agent *when* to use the skill, and a Markdown **body** that tells it *what to do*.

The frontmatter that matters most is the `name` (must match the directory) and the
**`description`:** the routing summary used to decide when to invoke the skill.
The current i4h skills also carry `version`, `license`, and a `metadata` block with
`author` and `tags`.

### The Description Is the Router

Write the `description` as one capability sentence plus an explicit **“Use when…”** clause naming the trigger phrases a developer would actually say:

> *Roll out a policy against an env and record verification episodes. **Use when** the user asks to validate, evaluate, or rollout a policy or checkpoint.*

Use specific, non-overlapping verbs and nouns so the router can distinguish nearby skills.

### The Body Grounds in the Base Code

The body starts with **Purpose** and **Base Code**, then adds task-specific sections such as
**Basics**, **What to Load**, **Run**, **Validation**, **Limitations**, or
**Troubleshooting**. Ground each skill in the workflow tree it owns. Agentic skills resolve
`workflows/agentic/`; catheter-navigation skills resolve `workflows/catheter_navigation/`.
Use `[[other-skill]]` links to defer stages another skill already owns.

Before naming a command or file, inspect the checkout with `rg --files` and read the owning
script or configuration. Reference only paths and flags that exist. If a required component is
missing, report that prerequisite instead of inventing a replacement. This keeps the skill tied
to executable repository behavior.

### Base Code for an Agentic Workflow Skill

This block resolves the agentic workflow regardless of the working directory:

```bash
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/agentic" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"
  [ -d "$ROOT/workflows/agentic" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"
fi
export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"
```

## Authoring Checklist

**Frontmatter**

`name` matches the directory; a routing `description` with a “Use when…” or “Use for…” clause; `version`, `license`, `metadata.author`, and `metadata.tags`.

**Body**

Purpose, the Base Code block, task-specific instructions, runnable commands, validation, and any limitations or troubleshooting.

**Grounding**

Inspects the checkout, drives existing scripts in its owning workflow tree, reads the
source-of-truth config, and never invents paths or flags.

**Cross-Links**

`[[other-skill]]` references for stages you don’t re-implement.

## What’s Next?

You can now read, route, and author skills. In [Conclusion and Next Steps](https://docs.nvidia.com/learning/physical-ai/getting-started-with-isaac-for-healthcare/latest/agentic-workflows/10-conclusion.md), you’ll pull the whole workflow together and find where to go from here.