skill-evolution

Skill Evolution

Use this skill before creating, editing, or deciding whether to update any AI coding agent skill in this repository.

When to Update Skills

Update a skill when any of the following happens:

• A user corrects agent behavior in a way that should generalize.
• A command fails and the recovery path should be remembered.
• A reference link, command, component _type, or installation instruction is stale.
• Task routing is too broad, too narrow, or points to the wrong skill.
• A repeated instruction appears in multiple skills and should move to a shared entry point.
• A skill contains too much detail and should move detail into focused references.

Do not update skills for one-off user preferences, temporary local environment quirks, or speculative guidance that was not validated.

Update Workflow

1. Finish the user's requested task first unless the skill update is the task.
2. Identify the smallest skill that should change.
3. Keep each SKILL.md concise and task-oriented.
4. Move detailed examples or long reference material into that skill's references/ directory.
5. Update AGENTS.md when a new skill is added or task routing changes.
6. Run Markdown link checks through pre-commit on the changed skill files.

Naming and Layout

Use the flat skills layout:

skills/
  nat-installation/
    SKILL.md
    references/
  nat-workflow-creation/
    SKILL.md
    references/

Each skill folder must contain one SKILL.md with frontmatter:

---
name: skill-name
description: Use when ...
author: NVIDIA Corporation and Affiliates
license: Apache-2.0
---

Use author and license frontmatter instead of long license headers in SKILL.md files.

Use specific names that describe the task surface. Avoid catch-all folders that hide routing information.

Quality Bar

• Skills should tell agents what to do, what to read next, and what to validate.
• Prefer canonical repository docs over copied long-form explanations.
• Keep cross-skill links relative and valid.
• Use "NVIDIA NeMo Agent Toolkit" on first prose use, then "NeMo Agent Toolkit" or "the toolkit".
• Use nat only for technical identifiers such as the CLI, package name, Python namespace, paths, and environment variables.