🌏 閱讀中文版本
A few weeks ago, something happened on the team.
A senior engineer spent two weeks building what he called a “super Skill.”
91 UI components. 18 page templates.
He also thought the work was solid.
But when he tried to use this Skill to generate a brand-new order management system…
It stalled.
Not a technical problem.
A logic problem.
The Skill knew how to render a button. But it had no access to the API or data source context.
The Skill knew how to lay out a table. But it didn’t know which database the table data came from.
And he couldn’t articulate where this Skill’s capability boundary actually was.
A Skill’s Nature: Knowledge Base, Not Automation Engine
Let’s be precise about this.
A Skill is not a deterministic application runtime.
It’s a loadable set of instructions and resources.
Claude Code reads the SKILL.md frontmatter and description into context first.
Scripts run through tools only when needed.
It doesn’t execute your application logic.
It reads.
It reads constraints.
It finds templates.
Then it reassembles.
SKILL.md (instructions) + templates + tools (scripts)
↓
Claude reads and "follows instructions" to generate content
↓
Not an automation program — a "knowledge base"It understands the constraints in SKILL.md.
It finds structure in templates.
Then it uses that information to reassemble something new.
A Skill is not an automation engine. It’s a knowledge base.
That sounds abstract.
Let’s make it concrete.
Say you have a Skill that generates React components.
It has a Button.tsx template inside.
When Claude uses this Skill, it:
- Reads the structure of
Button.tsx. - Reads the style and accessibility rules in
SKILL.md. - Fills in the new text, colors, and icons based on your request.
It doesn’t run Button.tsx.
It doesn’t execute your code.
It’s just an advanced version of copy, paste, and modify.
That’s why a single general-purpose Skill struggles to reliably generate complete features that plug into an existing project.
Because a project isn’t knowledge.
A project is context.
A Skill is an IKEA furniture kit.
A project is the 30-year-old house you’re furnishing.
The IKEA manual won’t help you fix the plumbing.
The 5-Level Model: Capability Boundaries of a Skill
To understand Skill boundaries more clearly, I’ve mapped capability into 5 levels.
These aren’t levels of technical difficulty. They’re levels of information dependency.
| Level | Capability | Risk | Context Required | Validation |
|---|---|---|---|---|
| 1 | Reference material | Low | Design specs, UI constraints | Visual comparison |
| 2 | Template fill | Low | Schema, field sources | Structure comparison |
| 3 | Multi-file generation | Medium | Cross-file dependencies, validation rules | Unit tests |
| 4 | Project integration | High | Project structure, routing, state | End-to-end tests |
| 5 | Fully automated build | High | Business logic, API specs | Staging E2E, contract tests, canary release, monitoring |
Level 1: Reference Material (Reliable)
This is where Skills shine.
Someone once asked me: “Why does the Skill always get the button right?”
Because you provided a design-system.md with:
- Primary color:
#007AFF - Typeface: Inter
- Border radius: 8px
Claude can consistently follow these specs and apply them across any generated code.
Why is it reliable?
Because the information is universal.
It doesn’t depend on any specific project.
It only depends on the design spec itself.
Level 2: Template Fill (Workable)
You provide a page-template.md with:
- Header region
- Sidebar region
- Main content region
You provide a schema.json that defines the data structure.
Claude can generate a basic page skeleton.
Why does it work?
Because the structure is fixed.
The data structure is defined.
Claude just needs to fill in the blanks.
Like a coloring book.
Level 3: Multi-File Generation (Limited)
This is where limitations start.
You want the Skill to generate UserList.tsx, UserDetail.tsx, and UserForm.tsx.
Claude can generate those files.
But the constraints are:
UserListneeds to know theUserdata structure.UserDetailneeds to know how to call the API.UserFormneeds to know the validation rules.
In a recent review, I saw a Skill-generated UserForm with all validation logic hardcoded as if-else chains.
Because the Skill didn’t know you were using zod.
That information isn’t in the Skill.
The Skill only has templates.
No context.
So the generated code often needs significant manual adjustment.
The bottleneck at Level 3 isn’t Claude’s capability. It’s the Skill’s lack of project-specific information.
Level 4: Project Integration (Difficult)
Until you try to generate your first real page.
You want the Skill to automatically generate the entire project.
Including:
- Routing config
- API calls
- State management
- Database connection
Why is it difficult?
Because every project is structured differently.
- Next.js uses the
app/directory. - Create React App uses
src/. - Angular uses
modules/.
The Skill can’t know your project structure in advance.
Unless…
You write it into the Skill.
But then the Skill keeps growing more complex.
And harder to maintain.
A useful approach here: shrink the experiment scope. Pick one small feature, define a rollback plan, and come back with data in two weeks.
“I want to try this on one small feature. If something breaks, I own it. Two weeks, then I’ll show you the numbers.”
That tells your manager: you’re not cutting corners — you’re working more intelligently.
Level 5: Fully Automated Build (Beyond Scope)
This is beyond what a single general-purpose Skill can reliably handle.
Fully automated builds require:
- Understanding of business logic
- Command of API specs
- Judgment on state design
- Database schema definition
None of those are knowledge.
They’re decisions.
Claude can help you execute decisions.
It can’t make decisions for you.
Because decisions need context.
And Skills don’t have context.
The Root Cause of Diminishing Returns at Level 4+: The Information Isn’t in the Skill
Let’s look more closely at why Level 4 breaks down.
Say you have a Skill called uiux-design-pro.
91 components. 18 templates.
You want to use it to generate an order list page.
The Skill can generate UI.
What’s missing:
- Where’s the project structure? (
pages/vsapp/vsviews/) - How is routing configured? (Next.js App Router? Angular Router?)
- Where’s the API? (REST? GraphQL? What format?)
- State management? (Zustand? Redux? NgRx? Signals?)
- Auth? (JWT? Session? Does it need permission checks?)
- Which existing components can be reused?
None of this is in the Skill.
It’s in the project itself.
A Skill is a universal knowledge base.
A project is a specific context.
A universal Skill can’t access project-specific context — so of course it can’t connect.
Unless…
You turn project-specific information into universal knowledge.
But that’s not possible.
Because every project’s specific information is different.
Single Large Skill vs. Layered Skills: A Common Trade-off
The common impulse is to add more responsibilities to the Skill — letting it grow more complex.
uiux-design-pro
├── 91 components ✓
├── 18 templates ✓
├── Page Generator ← add this?
├── API Generator ← and this?
└── ends up as a compound Skill with rising maintenance costThis is where diminishing returns set in.
As the number of projects grows, the Skill’s complexity expands its maintenance surface.
The more robust direction is to manage universal knowledge and project context in separate layers.
Layer 1: Design knowledge base (universal Skill)
↓ provides component specs, design constraints
Layer 2: Project-specific Skill
↓ project-generator, schemas
Layer 3: Agent coordinator (Task tool)
↓ reads project structure → references Layer 1 → generates codeLayer 1: Design Knowledge Base (Universal Skill)
This is uiux-design-pro.
It contains only:
- UI component specs
- Design constraints
- Style guides
No project-specific logic.
Why structure it this way?
Because design specs are stable.
Project structures change.
Separating them keeps the Skill stable.
Layer 2: Project-Specific Skill
This is the Skill unique to each project.
It contains:
- Project structure information
- API specs
- State management approach
- Database schema
Why?
Because this information is project-specific.
It only exists in this project.
Putting it in a dedicated Skill ensures accuracy.
Layer 3: Agent Coordinator
This is Claude Code itself.
It plays the role of coordinator.
Its workflow:
- Read the project-specific Skill (Layer 2).
- Reference the design knowledge base (Layer 1).
- Generate code.
The Agent isn’t an executor. It’s an integrator.
It integrates universal knowledge with project-specific context.
Two Implementation Approaches
Depending on your needs, two approaches are worth considering.
Option A: Project-Specific Skill
.claude/skills/
├── uiux-design-pro/ ← unchanged, pure design knowledge
└── project-generator/ ← new, project-specific
├── SKILL.md
├── templates/
├── schemas/
└── generators/Pros:
- Information stays accurate.
- Easy to maintain.
- Highly extensible.
Cons:
- Requires creating a Skill per project.
Option B: Schema-Driven
Define a page-schema.yaml; Claude reads it and generates the full page.
Pros:
- Structured.
- Easy to validate.
Cons:
- Requires maintaining the schema.
- Less flexible.
Trade-off:
- If your project structure changes often, go with Option A.
- If your structure is relatively stable, Option B works well.
There’s no best architecture. There’s only the architecture that fits the current project.
Market Signal: The Future of Skill Design
Based on current documentation and real-world cases, the Skill mechanism is still evolving — but one thing is clear now:
The value of a Skill depends on how well it externalizes context and decision criteria.
Skills don’t replace an engineer’s judgment.
They amplify it.
Tools are amplifiers. What they amplify is what you already have.
If your architectural thinking isn’t sharp, a Skill just lets you scale up uncalibrated assumptions faster.
If your architectural thinking is sharp, a Skill accelerates the delivery of validated judgments.
A Skill teaches Claude how to do something. Context teaches Claude whether to do it.
Next Step: More Knowledge, or Clearer Context?
Before building a super Skill, it’s worth clarifying three context checkpoints first.
- What is my project structure?
- What are my API specs?
- What’s my state management approach?
That’s the knowledge base you actually need.
Where does your ten minutes go today — making the Skill smarter, or making the context clearer?