Proposal: Extensible Skills standard — skill-memories as inheritance for SKILL.md

Problem

Skills (SKILL.md files) are getting duplicated across repositories. People copy a SKILL.md, change a few lines, and maintain a separate fork. There's no extension mechanism — no way to build on someone else's skill without forking it.

This is exactly the problem OOP solved with inheritance decades ago. Developers used to copy entire functions and maintain diverging copies. The solution was: extend the base class, don't copy it.

Proposal: Extensible Skills via skill-memories

Apply the SOLID Open/Closed Principle to Skills:

• SKILL.md = base class. Stable, version-controlled by the original author. Users don't modify it.
• **skill-memories/.md* = user extensions. Like subclass overrides. Project-specific rules, conventions, and behavioral overrides that sit alongside the original skill and are read at runtime.

The original skill keeps getting updates from its author. User customizations never conflict. No forking required.

Progressive Disclosure (three levels)

Skill memories support three levels of complexity:

Level 1 — Text rules (simple overrides)

- Always use React Hook Form with Zod validation
- Never use inline styles — Tailwind only

Level 2 — Conditional logic

- If the component exists in the design system (`src/components/ui/`), import it
- If it doesn't exist, create it following Atomic Design patterns
- If the file is a test, use `describe/it` blocks, never `test()`

Level 3 — Script references

- Before completing any task, run `.specweave/scripts/pre-validate.sh`
- After generating components, execute `npm run lint:components` to verify
- Use the output of `cat .specweave/standards/api-conventions.md` as the API style guide

Level 3 is key: the AI executes referenced scripts and tools as part of its workflow. This is progressive disclosure applied to AI behavior — from simple text rules to full automation pipelines, all written in English.

How it works at runtime

A hook runs on every skill invocation:

1. User invokes a skill (e.g., /sw:frontend)
2. Hook reads .specweave/skill-memories/frontend.md
3. Learnings are injected into context alongside the skill with clear instructions:

• Memories are project-specific overrides that take priority over base skill defaults
• If a memory contradicts the base skill, follow the memory
• If a memory references a script or tool, execute it as part of the workflow

How memories are created

Memories can be created manually or automatically:

• Manual: User writes .specweave/skill-memories/{skill-name}.md directly
• Automatic: A reflection system captures corrections during sessions (e.g., user says "don't use useState, use React Hook Form") and persists them as skill memories for future sessions

Reference Implementation

We built this in SpecWeave (open source, MIT):

• 68+ extensible skills using this pattern
• Hook-based injection: Single synchronous loader that injects memories on every skill invocation
• Atomic writes: Crash-safe persistence using temp-file + rename
• Automatic reflection: Captures corrections and saves as skill memories

Full documentation: https://spec-weave.com/docs/guides/extensible-skills

Repository: https://github.com/anton-abyzov/specweave

The OOP mapping

| OOP Concept | Extensible Skills |
|---|---|
| Base class | SKILL.md (core program) |
| Subclass override | skill-memories/*.md (user extensions) |
| Open for extension | Users can add or override anything — convention-based |
| Runtime polymorphism | Claude reads both and merges at runtime |
| Don't copy the class | Don't fork the skill |
| Extend the class | Write skill-memories |

What this enables for the ecosystem

1. Skill authors: Ship skills that users can extend without forking. Get adoption without losing control.
2. Marketplaces: Tag skills as "extensible" vs "non-extensible". Let consumers filter by extensibility.
3. Claude Code: Native support for a skill-memories loading pattern would make this a first-class feature rather than a hook-based workaround.

Questions for the Claude Code team

1. Would Claude Code consider native support for a skill-memories directory (e.g., .claude/skill-memories/) that auto-loads alongside SKILL.md?
2. Could SKILL.md frontmatter include an extensible: true field that signals the skill supports memories?
3. Would the Claude Code plugin/skills marketplace benefit from an "extensible" tag for discoverability?

I'd love feedback from @bcherny, @trq212, and the Claude Code team on whether this pattern aligns with the direction for Skills.