Step 5 of the request loop (`ORIENT -> PLAN -> EXECUTE -> VALIDATE -> DISTILL -> DELIVER`). Before delivering any response, extract new skills, skill updates, or procedure refinements and write them to the library. Triggers: user correction, novel problem solved, undocumented workaround, >3-iteration debugging, draft skill created mid-task, heartbeat retrospective, every request closure.
Step 5 of the request loop (`ORIENT -> PLAN -> EXECUTE -> VALIDATE -> DISTILL -> DELIVER`). Before delivering any response, extract new skills, skill updates, or procedure refinements and write them to the library. Triggers: user correction, novel problem solved, undocumented workaround, >3-iteration debugging, draft skill created mid-task, heartbeat retrospective, every request closure.
Skill Distillation
Step 5 of the universal request loop (see AGENTS.md and meta-skills). Every user request ends with a distillation pass before delivery. Skip it and the library decays; the next session rediscovers the same lessons.
Did I waste time on something a future agent would also waste time on?
Was there a procedure that worked but isn't documented?
Any yes -> extract.
2. Extract
What happened
What to extract
Debugging session found root cause
Decision tree (symptom -> diagnosis -> fix)
User said "do it this way instead"
Procedure update or new rule
Tried 5 approaches, only 1 worked
Anti-patterns + the working pattern
Used a tool in a new way
New workflow or technique
Combined skills in a novel way
Integration pattern
Task required a specific order
Phase-gated procedure
3. Classify
New knowledge
├── Fits existing skill -> UPDATE that skill
│ ├── New rule -> Key Rules
│ ├── New failure mode -> Failure Modes
│ ├── New procedure -> Key Workflows
│ └── Correction -> fix in place
├── Cross-cutting pattern -> UPDATE meta-skills
├── Entirely new capability -> CREATE new skill (MSF Phase 1-3)
└── One-off fact -> MEMORY.md, not skills
Rule: if the knowledge helps solve a different future problem, it belongs in a skill. If it's specific to this one situation, it belongs in memory.
4. Write
Skill updates: edit the specific section; bump the Iteration Log.
New skills: skills/<name>/SKILL.md from the meta-skilling template.
Procedure changes: update the orchestrator or relevant workflow skill.
Always: date and context ("Learned from SO-101 session 2026-04-08").
5. Verify
Re-read the file. Does it stand on its own?
Could a fresh agent follow it?
Is the lesson a procedure, not a fact?
What good distillation looks like
Bad: "The table had dual RigidBodyAPI which made it explode." This is a fact about one table; useless next session.
Good: "Before using any USD asset in physics, run the Asset Stability Check: load in isolation -> simulate 2 s -> if unstable, scan child meshes for rogue RigidBodyAPI." Reusable procedure.
Bad: "SO-101 needs hybrid IK + joint-space." Specific to one robot.
Good: "Arms with < 6 DOF cannot do lateral transport with pure differential IK. Use hybrid: IK for precision positioning, joint-space for large moves." Generalizes to any small-DOF arm.
The Generalization Rule
Always ask: "What's the general principle behind this specific fix?"
Specific fix
Generalized skill
Stripped RigidBodyAPI from table legs
Asset stability check procedure
Used file writes instead of print()
Headless debugging: stdout is unreliable
Added PhysxArticulationAPI.Apply()
Articulation setup checklist
Robot moved but didn't grasp
Visual validation must confirm task outcome, not just motion
User had to give detailed plan
Auto-decomposition: agent breaks down goals into phases
Integration with Orchestrator
The orchestrator's workflow should include distillation as a final step:
Phase 1: Verify Foundations
Phase 2: Incremental Integration
Phase 3: Polish & Deliver
Phase 4: Distill ← NEW (automatic, after delivery)
- What went wrong during this task?
- What workarounds were discovered?
- What feedback did the user give?
- Which skills need updating?
- Should a new skill be created?
Anti-patterns
Waiting to be asked. If you learned it, write it now.
Capturing facts instead of procedures. "X broke" is not a skill; "check X before running" is.
Over-generalizing from a single data point unless the user confirmed the pattern.
Under-generalizing: writing a per-asset fix when the pattern applies to all USD assets.
Skipping verification. An unreadable update is worse than none.
Duplicating across skills. One canonical location per procedure; cross-reference from others.
Embedding code in skills. See below.
Code in Skills — Reference, Don't Embed
Skills should reference canonical sources rather than embed code directly. Embedded code becomes stale when the upstream library or API changes — silently giving future agents wrong patterns to follow.
Rule
For any code pattern in a skill:
If it comes from Isaac Sim examples or docs: link to the doc page and/or local example file path. Describe the pattern in prose; let the agent read the actual file.
If it's a custom utility not in any upstream source: put it in a versioned script file in the workspace (e.g., isaac-sim/utils/grasp_utils.py), reference it by path, and note the version it was written for.
If it's a tiny one-liner or config snippet (e.g., a settings dict): embedding is acceptable, but add a comment with the Isaac Sim version it was validated against.
Why
Isaac Sim APIs change between versions. A skill with embedded code can silently guide agents down wrong paths.
Local example files ($ISAAC_SIM_DIR/source/standalone_examples/...) always reflect the installed/built version — they are the most accurate reference available.
Docs at docs.isaacsim.omniverse.nvidia.com are version-tagged — link to latest unless pinning to a specific release is intentional.
What to Write Instead of Code
The pattern name (e.g., "damped least-squares IK")
Where to find the canonical implementation (doc URL + local file path)
Key parameters and how to tune them (table form is fine)
What can go wrong and how to detect it
The conceptual flow in prose: what the code does step by step, without being the code itself
Library-Health Check (Run During Distillation)
Distillation isn't only "add new knowledge." Each pass should also detect when an existing skill has grown stale, bloated, or duplicate. Catch these at write time or they accrete until a full consolidation pass is needed.
Bloat detection
Before saving a skill update, eyeball the target file:
Cue
Action
Body > 500 lines after your edit
Offload to sidecar (see "Sidecar Offload" below). Anthropic spec hard limit.
