Meta-Skills — Patterns for Authoring Agent Skills

Purpose

Structure, compose, and improve agent skills using composition patterns and the Meta-Skilling Framework (Discovery → Practice → Capture → Validation → Iteration).

Side effects (disclosed): following this skill may (1) propose updates to skill files on disk — apply only after user confirmation; (2) optionally upload review images to $IMAGE_SERVER_URL, which must be localhost-bound (default http://localhost:8092), never an external host, and only after user confirmation.

Prerequisites

• Built Isaac Sim ($ISAAC_SIM_DIR or _build/linux-x86_64/release).
• NVIDIA GPU with a current driver (nvidia-smi).
• Shell env contract from isaac-sim-orchestrator: $ISAAC_SIM_DIR, $ISAAC_LAB_DIR, $WORKSPACE_DIR.
• User confirmation before skill-library writes or $IMAGE_SERVER_URL uploads.

Limitations

• Targets Isaac Sim 6 / Kit 110 unless a section states otherwise.
• Does not replace official NVIDIA documentation for unsupported edge cases.
• DISTILL proposes persistent skill updates; it does not silently rewrite the library.

Troubleshooting

Error / symptom	Cause	Solution
Extension or import not found	Wrong $ISAAC_SIM_DIR or stale build	Point env vars at _build/linux-x86_64/release or rebuild
Black or empty frames	Missing lights or non-RTX render mode	Add dome/key light; confirm RTX / PathTracing settings
Hang on stage load or first render	MDL compile or oversized stage	Follow isolation steps in isaac-sim-troubleshooting

Two parts:

1. Composition patterns: structuring and orchestrating skills.
2. Meta-Skilling Framework (MSF): building new skills from zero.

Core Operating Principle: Distillation Is Not Optional

Every user request follows a six-step loop: ORIENT → PLAN → EXECUTE → VALIDATE → DISTILL → DELIVER. The DISTILL step is mandatory as a proposal, not a silent write. If a task produced a new insight, workaround, correction, or procedure, draft the skill update (or new skill) and obtain explicit user confirmation before modifying skill files on disk. Skill files ARE persistent memory — what isn't written down doesn't exist next session; what is written without review can poison future sessions.

See:

• AGENTS.md — the universal request handling loop and skill index
• skills/skill-distillation/SKILL.md — the full distillation procedure, generalization rule, classification table, and draft-skill promotion gates
• references/quality-criteria.md — standing rubric (keep links one level deep from this file)

---

Part 1: Composition Patterns

Provenance note: Several patterns below attribute their origin to skills (ai-advisor, training-ops, pbt-system, llm-review-protocol, collaboration, multi-robot-franka, sortation-diverter) from the upstream isaac-claw library that are not imported into this repo. The pattern itself is reusable — treat the "Source:" line as historical context, not a navigation pointer.

1. Skill Routing

Pattern: A top-level orchestrator skill routes to specific sub-skills based on task category.

User request → Orchestrator reads context → Routes to specific skill
                                          → Provides shared patterns

Key insight: The orchestrator doesn't do the work — it identifies which specialist skill should handle it and provides cross-cutting concerns (units, naming, validation).

Example in this library: isaac-sim-orchestrator — turns natural-language requests into runnable sims and routes to usd-pipeline, isaac-sim-rendering, isaac-sim-validator, physics-simulation.

2. Chunked Processing

Pattern: Prevent context overflow by enforcing batch limits and tier-by-tier processing.

Rules:

• Never process more than N items at once (N=10-20 for complex assets)
• Process in tiers: leaf assets first, then composites, then top-level
• After each chunk, summarize and checkpoint before continuing
• Use explicit "processing X of Y" progress tracking

When to use: any time the input set is large enough that bulk-loading risks blowing the context window.

3. Quality Gates (from Collaboration / LLM Review)

Pattern: Mandatory external review before publishing any output.

Steps:

1. Generate output (render, code, asset)
2. With user confirmation, upload for review only to a localhost $IMAGE_SERVER_URL (typically http://localhost:8092) for vision LLM ingestion — refuse non-localhost URLs
3. Flood context — include full setup, known issues, what was tried
4. Require minimum score (e.g., 7/10) before sharing
5. Iterate based on prioritized improvement list

Source: llm-review-protocol, collaboration — Grok vision review before posting renders

4. Safety Rails for Autonomous Modification (from AI Advisor)

Pattern: When an AI agent autonomously modifies configuration:

• Max N× baseline per parameter (e.g., 10×)
• Absolute caps (e.g., 5000)
• No sign flips (penalty can't become reward)
• Audit trail of all changes with before/after
• Drift detection against baseline

Source: ai-advisor — SafetyRails for reward weight modification

5. Multi-Skill Composition (from Warehouse Builder)

Pattern: Complex tasks declare skill dependencies explicitly.

Dependencies:
  - spatial-reasoning            # all transform math
  - urdf-mjcf-to-usd-conversion       # robot asset import
  - usd-articulation             # multi-link validation
  - physics-simulation           # scene + per-prim physics
  - isaac-sim-rendering          # headless render + tone mapping

Each dependency is a complete skill that can be used independently. The composite skill orchestrates when to invoke each one.

6. Fleet Orchestration (from Training Ops + PBT)

Pattern: Manage distributed compute resources as a fleet.

• Pre-flight validation before any operation
• Zombie process cleanup is mandatory
• SSH-based deployment with git commit tracking
• Centralized monitoring via dashboard
• Population-based training for hyperparameter search

Source: training-ops, pbt-system

7. Progressive Disclosure (from Multiple Skills)

Pattern: Skill files should front-load the most common operations and put deep reference material later.

Structure:

1. Quick decision guide (table: symptom → action)
2. Most common operations with code
3. Configuration reference
4. Troubleshooting
5. Deep reference / edge cases

Source: Observed in the best-structured skills (spatial-reasoning, isaac-sim-troubleshooting)

---

Part 1b: Concise Skills (Anthropic-Compliant)

Hard constraints (Anthropic skill spec):

• SKILL.md body ≤ 500 lines
• description ≤ 1024 chars, third-person, includes WHAT + WHEN + trigger terms
• Cross-references one level deep only (no subdir/subdir/file.md)
• No hardcoded user paths, IPs, or time-sensitive phrases ("before August 2025")

The patterns below were extracted from a 170 → 132 library consolidation. They are the operational rules to keep the body ≤ 500 lines without losing knowledge.

9. Separation of Concerns — Three-File Pattern

A skill that grows past 300 lines almost always has three kinds of content intermixed. Split them into sidecar files.

Content	Lives in	Rule of thumb
What / When / How (procedure)	SKILL.md	Stays in the main file. ≤ 500 lines hard limit.
Executable code (≥ 20-line blocks, reusable helpers)	scripts/<name>.py	Importable module with docstrings. SKILL.md keeps a 1-line call-site example.
Deep reference / case studies / lessons	<topic>.md siblings	E.g. lessons.md, examples.md, advanced.md, recipes.md, workflow.md. Cross-link from SKILL.md once.

Trigger: if SKILL.md exceeds 500 lines, ≥ 50% of content is code blocks, OR the file has 5+ dated "Learned YYYY-MM-DD" sections → split.

Naming convention: sidecars get a single descriptive name (examples.md, not hard_lessons_2026_05.md). One sidecar per concern; don't fragment further.

10. Code-as-Reference, Not Code-as-Skill

A skill's body should describe what the code does and when to call it, not be the code. Concrete rules:

• ≥ 20-line code blocks → extract to scripts/<name>.py as a callable function. Replace in SKILL.md with: function signature + 1-line description + path link.
• 5–20-line blocks → keep inline if they're the primary illustration. Drop them if redundant with a sidecar function.
• ≤ 5-line one-liners and config snippets → embedded is fine. Add a comment with the API version they were validated against.
• Tables, decision trees, parameter ranges → keep inline (they're the agent-facing decision support, not the implementation).

Reasoning: a sidecar script can be imported, version-pinned, and tested independently. Embedded code becomes silently stale as upstream APIs evolve. See skill-distillation Part 3 ("Code in Skills — Reference, Don't Embed") for the full policy.

11. Description Budget — 1024 Chars Is Not Aspirational

The description is what the agent's discovery system uses to decide whether to load the skill. Long descriptions:

1. Hit the 1024-char hard limit and get truncated by tooling
2. Bury the trigger terms in prose

Structure that fits comfortably:

• Sentence 1 (≤ 200 chars): what the skill produces or covers
• Sentence 2 (≤ 200 chars): the key concepts/APIs it owns
• Sentence 3 (≤ 200 chars): "Use when …" with 3–5 specific trigger phrases
• Optional: a "See also …" pointer to sibling skills

Anti-pattern: description as a TOC. If you find yourself enumerating every section, you're writing the body twice. Save the detail for the body.

12. When to Split vs Merge vs Cross-Link

Decision tree for the most common library-evolution question:

Two skills overlap. What now?
│
├── One is a strict subset of the other?
│      → DELETE the subset; absorb unique bits into the superset.
│
├── They share substrate but specialize differently?
│      → EXTRACT shared substrate to a third skill; both depend on it.
│         (e.g. `navigation-primitives` shared by runtime nav + SDG)
│
├── They cover the same domain at different abstraction levels?
│      → MERGE into one with a "When to use this skill (vs siblings)" section.
│         (e.g. `physics-simulation` absorbing 10 PhysX/Newton skills)
│
└── They're distinct but frequently used together?
       → CROSS-LINK with explicit RECEIVES from / PRODUCES for sections.
          (e.g. `urdf-mjcf-to-usd-conversion` ↔ `usd-articulation`)

Anti-pattern: narrow-scope project artifacts. If a skill is named after a specific asset/task (e.g. multi-robot-franka, sortation-diverter) and its "reusable principle" is "do exactly this thing" — that's a project note, not a skill. Either fold its content into a general parent or delete.

13. Hierarchy with Routing, Quality Gates, and Distill-Before-Deliver

Pattern: A parent skill routes requests to specialist sub-skills, enforces quality gates at trust boundaries, and mandates distillation before delivery.

Request → Router (parent) → Specialist sub-skill → Quality gate → Distill → Deliver

Three structural concerns, none optional:

Concern	Owner	Artifact
Routing	Parent SKILL.md routing table	Signal → target → handoff contract
Quality gates	Parent or dedicated validator sub-skill	Standing checklist + decision tree + feedback loop
Distill-before-deliver	Phase 4 of the phase plan	Proposed skill update confirmed by user before write

When to use: Any hierarchy with 3+ sub-skills, pipeline stages with intermediate outputs, or domains where delivery defects have been recurring.

Authoring blueprint: keep the parent SKILL.md as the router, put the standing rubric in references/quality-criteria.md, and use one level of sub-skills only. Worked example notes: references/skill-hierarchy-authoring.md (sibling reference — do not nest further reference hops from that file into agent context unless needed).

Existing implementations:

• isaac-sim-orchestrator — routing table + four-phase plan
• isaac-sim-validator — quality gate with evolving criteria
• skill-distillation — the distill-before-deliver procedure (confirm before write)

14. Environment Variables, Not User Paths

Skills run on different machines. Every absolute path is a portability bug.

Replace	With
/home/user/IsaacSim	$ISAAC_SIM_DIR
/home/user/Projects/.../assets/...	$SIMREADY_ASSETS/...
localhost:8095	$KB_SERVICE_URL (default http://localhost:8095)
192.168.0.109:8092	$IMAGE_SERVER_URL (placeholder OK; never bake the IP)
C:\_Data\exts\content-pipeline\cip.bat	$CIP_ROOT/exts/content-pipeline/cip.bat (Windows skills declare platform in a preamble)

The orchestrator skill owns the env-var contract; per-skill files reference vars, never declare values. See isaac-sim-orchestrator § Environment.

---

Part 2: Meta-Skilling Framework (MSF)

A systematic, repeatable process for developing new skills from zero to competent in any domain. Designed for an AI agent with session-based memory loss where skill files ARE the persistent memory.

When to Use MSF

• Starting to learn any new tool, domain, or capability
• Building a skill hierarchy (e.g., Blender → modeling, materials, rigging...)
• Reviewing whether an existing skill needs iteration

The Five Phases

Phase 1: Discovery — define what you need to learn and why

1. Identify the need — what problem does this skill solve?
2. Define scope — boundaries; one skill or a hierarchy?
3. Break down sub-skills — list components, create hierarchy if complex
4. Research resources — official docs, API references, tutorials
5. Set competence goals — specific tasks you should be able to perform when done
6. Check existing skills — do any of your skills overlap? Link and reuse.

Output: Initial SKILL.md with purpose, scope, hierarchy, resources, goals.

Phase 2: Practice — build hands-on competence through structured experimentation

1. Follow the learning path — foundational, then advance
2. Do small practical tasks — don't just read; build
3. Take notes AS you go — commands, workflows, gotchas
4. Identify patterns — what's repeatable, what can be scripted
5. Track challenges — tag what's hard; these become iteration targets

Output: Raw practice notes, initial scripts, identified patterns.

Phase 3: Capture — convert raw learnings into structured, reusable knowledge

1. Organize — convert practice notes into structured sections
2. Standardize — follow the SKILL.md template (below)
3. Save scripts — working code in scripts/. Reference docs in references/.
4. Version — start at v0.1, increment on significant updates
5. Link related skills — cross-reference parent/child/sibling skills

Critical Rule: If it's not in the file, it doesn't exist next session.

Phase 4: Validation — prove the skill actually works

1. Test it — perform a real task using only what's documented
2. Check against goals — can you do what Discovery said you should?
3. Identify gaps — tag as "Validation Gaps" for iteration
4. Get feedback — from user, validator, or test results

Phase 5: Iteration — refine and expand based on real usage

1. Review gaps at session start
2. Research solutions
3. Update and version
4. Expand scope — add sub-skills once core is solid
5. Re-validate

Skill Hierarchy Pattern

domain/
├── SKILL.md              # Parent: overview, skill tree, progress tracker
├── sub-skill-1/
│   ├── SKILL.md          # Sub-skill: focused docs
│   ├── scripts/
│   └── references/
└── sub-skill-2/...

Rules: parent has the full skill tree with status indicators; sub-skills link back to parent; track dependencies; master foundational sub-skills before dependent ones.

SKILL.md Template

---
name: skill-name
description: >
  [1-3 sentences: what, when to use, triggers]
---

# [Skill Name]

## When to Use This Skill
- [task 1]
- [task 2]

## Related / Integration Points
- RECEIVES from: [skill] → [data]
- PRODUCES for: [skill] → [data]

## Core Concepts
[Organized knowledge]

## Key Workflows
[Step-by-step procedures with code]

## Decision Trees
[Branching logic for "it depends" situations]

## Failure Modes & Recovery
For each major workflow:
- FAILURE: [what goes wrong]
- SYMPTOMS: [how you notice]
- CAUSE: [why]
- RECOVERY: [fix]
- PREVENTION: [how to avoid]

## Expert Intuition
- Rules of thumb
- Smell tests
- Proportional judgments

## Context Matrix
| Context | Behavior Change |
|---------|----------------|

## Environment Requirements
Pre-flight checks and tool versions.

## Iteration Log
- v0.1 [date]: Initial capture

Cold-Start Expertise Patterns

Goal: BE competent the moment you read the skill file.

• Executable Knowledge Blocks (EKBs): IF [condition] THEN [action] BECAUSE [reasoning]
• Decision Trees: embed branching logic directly
• Failure Mode Catalog: FAILURE/SYMPTOMS/CAUSE/RECOVERY/PREVENTION
• Worked Examples: at least 2 per workflow, input→decisions→output
• Context Matrix: same skill across different situations
• Confidence Tags: verified, probable, theoretical

Anti-Patterns

• Learning without capturing — you WILL forget
• Starting too broad — focus on one sub-skill at a time
• Skipping validation — untested = unreliable
• Copy-pasting tutorials without adapting to YOUR context
• Ignoring existing skills — always check for overlap first
• Perfectionism before practice — rough working skill beats perfect plan

Session Start Protocol

1. Read this file to remember the framework
2. Read the PARENT skill for the domain you're working in
3. Read the specific SUB-SKILL you're focusing on
4. Check Challenges & Gaps — that's your TODO
5. Pick up where the last session left off