Why You Shouldn't Nest Skills Inside Other Skills (And What to Do Instead)

A community discussion about skill composition patterns sparked an important warning: nesting skills can hurt your agent's performance.

The Question

In the OpenClaw Discord, a user asked a reasonable question:

"Can we include a skill in another skill? Like referencing it include ./../skill-name/SKILL.md?"

It seems elegant—DRY principles applied to AI skills. But the community response was a clear warning.

Why Nested Skills Are Problematic

A seasoned community member explained:

"Nested skills increase the risk of problems and context drift. If nested skills were a good idea, Anthropic would recommend it."

The Context Drift Problem

When you nest skills, you're stacking context on context. Each skill adds instructions that shape how the model behaves. When skill A includes skill B:

• Token bloat: Your context window fills up faster
• Instruction conflict: Skills may have competing priorities or conflicting guidance
• Unpredictable behavior: The model has to reconcile multiple overlapping instruction sets
• Harder debugging: When something goes wrong, which skill caused it?

The Anthropic Guidance

The reference to Anthropic is telling. Claude's official guidance emphasizes keeping system prompts focused and avoiding unnecessary complexity. Their best practices favor:

• Clear, single-purpose instructions
• Explicit rather than implicit behavior
• Minimal indirection layers

What to Do Instead

1. Keep Skills Atomic

Each skill should do one thing well. If you need multiple capabilities, let your agent load multiple skills independently rather than chaining them.

2. Use Shared Utilities Sparingly

If you have truly shared code (like a CLI wrapper), put it in a scripts/ folder in your skill rather than creating dependency chains.

3. Compose at Runtime

Instead of nesting skills, design them to work alongside each other. OpenClaw's skill system already handles loading multiple skills—let it do its job.

4. Document Dependencies Clearly

If skill A genuinely requires skill B to be present, document it in your skill's README rather than trying to auto-include it.

The Takeaway

Simplicity wins. Your agent will be more reliable, debuggable, and predictable with clean, focused skills that don't try to include each other.

When you're tempted to nest skills, ask: "Can I just enable both skills separately?" The answer is almost always yes—and your agent will thank you.

---

Discussion surfaced in #users-helping-users on the OpenClaw Discord. Join the community to share your own skill composition patterns!