writing-skills

name	writing-skills
description	Author or revise a Usd Optimize skill (.agents/skills/<name>/SKILL.md). Use when adding, restructuring, or reviewing a skill so it matches house conventions and is registered in the index.
version	1.0.0
allowed-tools	Shell, Read, Write, Edit, Glob, Grep
metadata	{"author":"NVIDIA Corporation","tags":["meta","authoring","documentation","skills"]}

Writing Skills

Author a new skill, or revise an existing one, so it matches the conventions every other skill in this repo follows and is discoverable by agents.

What this skill covers

• When to write a skill — and when not to (use a reference doc instead).
• General Guidelines — the rules that keep skills consistent and readable.
• Inputs — what to gather before writing.
• Step 1 — create the skill directory and SKILL.md.
• Step 2 — write the frontmatter (required + optional fields).
• Step 3 — write the body (the "What this skill covers" block, sections, length).
• Step 4 — register the skill in .agents/skills/README.md.
• Step 5 — verify (frontmatter, links, invocation).
• Frontmatter reference — every field, with examples.
• House conventions — the rules that keep skills consistent.
• Anti-patterns — what reviewers will flag.

Companion docs: .agents/skills/README.md (the cross-skill index you must update), and the existing skills themselves — new-operation and inspect-asset are good full-length references; testing is a good shorter one.

---

When to write a skill

Write a skill when you are capturing a workflow — a repeatable, step-by-step task an agent performs ("run an operation", "validate an asset", "diff two stages"). Per the repo philosophy: skills are workflows, not references.

Do not write a skill when the content is reference material — facts, schemas, parameter tables, API surfaces. These belong in the docs under docs/ and under skill references in .agents/skills/<name>/references/.

If you find yourself writing a skill that is mostly a lookup table with no "do this, then that", then it should be a reference doc instead.

---

General Guidelines

A lot of information exists in the public facing docs under docs/. Before writing a skill, check if the content already exists in a reference doc. If it does, link to it instead of duplicating it. This keeps the information consistent and avoids drift. For example, if you are writing a skill that uses a specific operation, link to the operation's rst doc file under docs/operations/<operation>.rst.

Likewise if writing information that should be public facing and not necessarily just for agents this information can be added to the docs and linked to from the skill.

Skills should be focused on a single workflow. Avoid adding unrelated information and overly verbose explanations. They should read more like a technical manual than a tutorial.

Avoid making sweeping changes to the skills. If you find yourself wanting to make a lot of changes to multiple skills, consider whether the changes are necessary and if they can be made in a more focused way.

Don't use em dashes in the skill text. Use a colon or parentheses instead.

---

Inputs

Gather these before writing:

Input	Required	Example	Notes
Skill name	yes	compare-stages	kebab-case. Becomes the directory name and the /<name> slash command.
One-line purpose	yes	"Structured diff between two USD stages"	Becomes the basis of the description and the README index row.
When to use it	yes	"before/after optimization"	The trigger condition — drives the description (agents match on it).
Section list	yes	(the steps)	Each becomes a "What this skill covers" bullet and a body section.
Tools used	no	Shell, Read, Write	For allowed-tools.
Related skills / docs	no	run-operations, docs/<doc>.rst	For cross-references in the body and README.

If the user only gives a goal, help them name the skill and decompose the workflow into ordered steps first.

---

Step 1 — create the directory and file

Skills live one-per-directory:

.agents/skills/<name>/SKILL.md

mkdir -p .agents/skills/<name>

---

Step 2 — write the frontmatter

Every SKILL.md opens with YAML frontmatter, then the SPDX header comments. Copy this shape (see the full Frontmatter reference below for each field):

---
name: <name>
description: <what it does>. Use when <trigger>.
version: "1.0.0"
allowed-tools: Shell, Read, Write, Glob, Grep
metadata:
  author: NVIDIA Corporation
  tags: [<tag>, <tag>]
---

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

The description is load-bearing: agents that don't auto-run the skill inventory .agents/skills/ and read each frontmatter description to decide which skill applies. Write it as what it does + when to use it, in one sentence. Lead with the action.

---

Step 3 — write the body

After the frontmatter and SPDX comments:

1. An H1 title in Title Case (# Writing Skills).
2. A one-to-three sentence summary of what the skill accomplishes.
3. A ## What this skill covers block — a bulleted list where each bullet names a section of the body in bold followed by a short gloss. This is the single most important structural convention: it lets an agent scan one block and know what's where without reading the whole file. List every section, including "Inputs" and any reference table at the end.
4. Companion docs line(s) right after the block, linking related skills and reference docs with relative paths.
5. A --- rule, then the sections, in the order the "covers" block lists them. Use ## Step N — <verb> for ordered workflows.

Length rules:

• Be as concise as possible while still being clear and complete. Long skills are only ok if the workflow is genuinely complex and requires it.
• Put load-bearing detail where it belongs, even if that's past line ~50. The README explicitly tells readers to read past the first 50 lines, so don't contort the structure to front-load everything — but do make the "covers" block point at it.
• Prefer tables for inputs, naming conventions, and option/flag references.
• Use fenced code blocks for every command and snippet. Show the exact invocation, not a paraphrase.

---

Step 4 — register the skill in README.md

A skill that isn't in .agents/skills/README.md is invisible to the per-session index. Add it in three places (skip any that don't apply):

1. The "When to use which skill" table — one row: | [](<name>/SKILL.md) | Use when … | Place it near related skills, not necessarily at the end.
2. The end-to-end loop diagram — only if the skill is part of the inspect → validate → interpret → operate → compare flow.
3. "Cross-references at a glance" — a bullet per load-bearing pointer to or from another skill or reference doc.

Match the existing terse, action-first phrasing ("Use when …").

---

Step 5 — verify

Run these checks before declaring done:

# Frontmatter present and parseable; name matches the directory.
head -12 .agents/skills/<name>/SKILL.md

# The skill is registered in the index.
grep -n "<name>" .agents/skills/README.md

# Relative links resolve (spot-check the paths you used).
ls .agents/skills/<name>/SKILL.md

Manual checklist:

• name: equals the directory name.
• description: says what it does and when to use it.
• SPDX header comments present (copyright + license).
• "What this skill covers" block lists every section.
• All commands are in fenced code blocks and are runnable as written.
• Cross-references use relative paths and point at real files.
• Registered in README.md (table row + any cross-reference bullets).
• If it composes with other skills, those skills' cross-reference bullets mention it too (links should be bidirectional where it matters).

---

Frontmatter reference

Field	Required	Example	Notes
name	yes	compare-stages	kebab-case; must equal the directory name. Drives /<name>.
description	yes	Structured diff between two USD stages. Use when comparing before/after optimization.	What + when, one sentence. This is how agents pick the skill.
version	recommended	"1.0.0"	Quoted string. Start at 1.0.0; bump on meaningful change.
allowed-tools	recommended	Shell, Read, Write, Glob, Grep	Comma-separated Claude Code tool names the skill needs.
metadata.author	recommended	NVIDIA Corporation	Default author unless the user specifies otherwise.
metadata.tags	optional	[meta, authoring]	Short topical tags for discovery.

The README index uses a slightly different frontmatter (name + description only) because it is an index, not a workflow — don't copy allowed-tools etc. into it.

---

House conventions

• Workflows, not references — see "When to write a skill".
• The "covers" block is mandatory and must map every section.
• Skills cite each other deliberately — when the canonical answer lives in another skill or reference doc, link it instead of duplicating it.
• One source of truth — if two skills need the same facts, factor them into a doc or reference doc.
• Terse, imperative, action-first — "Run …", "Create …", "Use when …".

---

Anti-patterns

Reviewers will push back on these:

• A skill that's really a reference doc — a wall of tables with no steps. Put it under docs/ (operation facts belong in docs/operations/*.rst) and point a skill at it.
• Missing or vague description — "Helps with stages" tells the dispatcher nothing. Say what it does and when to use it.
• No "What this skill covers" block, or one that omits later sections — the index promise ("scan one block to know what's where") breaks.
• Not registered in README.md — the skill won't surface in the per-session index and effectively doesn't exist for routing.
• Duplicated content — copying a parameter table or invocation snippet that already lives in a reference doc. Link instead; copies drift.
• Repeating the tool-translation table — it lives once in the root AGENTS.md; just use canonical tool names.