Feature Request: Hierarchical Skills Architecture for DRY Principles and Team Customization #380
Replies: 5 comments 1 reply
-
|
This is a well-structured proposal and you've correctly identified the three core failure modes of flat skill architectures at scale. I've hit all three of these in production agent systems. A few thoughts on the design: The Single inheritance ( ---
name: secure-user-stories
description: Create security-reviewed Azure DevOps user stories
mixins:
- public/azure-devops-user-stories
- public/security-review-checklist
---
## Composition Rules
When both base skills provide conflicting guidance, security requirements take precedence.The trigger collision problem is actually the harder one to solve. Inheritance helps with knowledge duplication, but the trigger collision issue needs its own mechanism. A ---
name: contoso-user-stories
extends: public/azure-devops-user-stories
overrides: true # explicitly suppresses parent from loading when this matches
scope: team/contoso
---On the maintenance burden math: Your 10 base x 50 teams x 3 customizations = 150 skills scenario actually understates the problem. The real cost isn't the file duplication — it's the drift detection. When a base skill gets updated, how do you know which derived skills need re-testing? This argues for a Strong proposal overall. The Docker/Terraform module analogy is apt — agent skill systems are heading toward the same package management patterns that every other ecosystem eventually needs. |
Beta Was this translation helpful? Give feedback.
-
You don't need
|
Beta Was this translation helpful? Give feedback.
-
|
Good proposal. I would be careful with classic inheritance, though, because skill activation is context-sensitive and not compile-time. Deep A pattern that might keep the benefits without brittle inheritance:
The important requirement for enterprise use is explainability. If a generated workflow behaves badly, admins need to answer: which skill matched, which shared rule applied, and which local override changed it. A hierarchy can help DRY, but only if resolution is deterministic and visible. |
Beta Was this translation helpful? Give feedback.
-
|
I think the way it should be is by creating an agent definition with a skills folder: i.e. an azure agent having the azure related skill set. |
Beta Was this translation helpful? Give feedback.
-
|
If you agree, you might want to upvote this one; it would solve the context bloat: anthropics/claude-code#12633 |
Beta Was this translation helpful? Give feedback.
-
|
We've implemented a version of this in production — sharing what worked and what surprised us. Our approach: 2-tier injection (always + lazy) with a manifest system # Each skill has SKILL.md with frontmatter
tier: always # ~100 tokens injected every session (15 skills)
tier: lazy # ~25 token stub injected, full INSTRUCTIONS.md read on demand (46 skills)What this looks like in practice (61 skills, 1M context window):
Key design decisions:
What surprised us:
What I'd add to this proposal: a "platform" dimension alongside hierarchy. Skills that only work on macOS (Apple Reminders, Sonos) shouldn't exist in the prompt on Linux. This is more impactful than inheritance for reducing noise. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
As Skills adoption scales across organizations, the current flat architecture creates maintenance burden, trigger collisions, and knowledge duplication. This proposal introduces a hierarchical skills system enabling skills to inherit from base skills, similar to proven patterns in Docker images, Terraform modules, and OOP inheritance.
Problem Statement
Current Architecture Limitations
The flat skills architecture works well for individual users but creates three critical problems at organizational scale:
1. Trigger Collision and Context Bloat
With the current triggering mechanism, skill discovery relies solely on the
descriptionfield in YAML frontmatter:azure-devops-user-stories Create user stories following INVEST criteria. Use when user says "create user story", "write user story" public contoso-user-stories Create user stories following INVEST criteria with Contoso-specific tags. Use when user says "create user story", "write user story" teamProblem: Both skills match the same user request → Claude loads both → context window bloat + potentially contradictory instructions.
2. Knowledge Duplication and DRY Violations
Teams wanting to customize public skills must fork and duplicate the entire skill:
Problem: When Azure DevOps best practices change, updating requires:
3. Maintenance Burden at Enterprise Scale
Consider an organization with:
Current state: 150 skills, each maintaining full copies of base logic
Desired state: 10 base skills + 150 lightweight customization layers
Proposed Solution: Skill Inheritance
Core Concept
Enable skills to declare inheritance relationships via an
extendsfield in YAML frontmatter:Real-World Use Cases
Use Case 1: Azure DevOps User Stories
Base Skill (Public): Microsoft's official Azure DevOps best practices
Team A (Finance): Extends base with:
Team B (Engineering): Extends base with:
Result: 1 authoritative base + 2 lightweight customizations vs. 2 full duplicates
Use Case 2: Brand Guidelines
Base Skill (Marketing): Corporate brand standards
Product Team: Extends base with:
Sales Team: Extends base with:
Use Case 3: Security Review Checklists
Base Skill (Security Team): OWASP Top 10 checks
Web Team: Extends base with:
API Team: Extends base with:
Beta Was this translation helpful? Give feedback.
All reactions