The current generation of AI coding agents makes it surprisingly easy to create a “skill.”
Write a Markdown file. Add instructions. Give it a name. Put it inside .claude/skills/. Done.
Except it isn’t.
As soon as you build more than a handful of skills, a different set of problems appears:
- Which skill should activate?
- Why did two skills activate at the same time?
- Why did the agent ignore an important instruction?
- What belongs in a skill versus a rule, agent, hook, or script?
- How much context should the skill load?
- How do you test whether the skill actually works?
- What happens when the underlying framework changes?
- How do you distribute skills?
- How do you retire obsolete skills?
- How do you prevent dozens of skills from becoming an unmaintainable mess?
At that point, AI skills stop looking like prompts and start looking like software systems.
A production-grade AI skill is not merely a Markdown prompt. It is a versioned, testable, routable, enforceable software component with a defined lifecycle.
1. The Skill Lifecycle
A useful way to understand an AI skill is to look at its entire lifecycle:
Runtime
↓
Scope / Fit
↓
Triggers
↓
Architecture
↓
Anatomy
↓
Content
↓
Enforcement
↓
Measurement
↓
Shipping
↓
Maintenance
↓
Portfolio
Enter fullscreen mode Exit fullscreen mode
Each stage answers a different question:
Stage Core question Runtime How does the skill load and execute? Fit & scope Should this be a skill at all? Typing & triggers When should it activate? Architecture How should the workflow operate? Anatomy What files make up the skill? Content How should instructions be written? Enforcement What can be enforced mechanically? Measurement How do we know it works? Shipping How do users receive it? Maintenance How does it survive change? Portfolio How do many skills coexist?The important insight is that skill engineering covers the entire lifecycle, not just the writing of SKILL.md.
2. Chapter 00 — How Skills Load and Run
Before designing a skill, understand the runtime.
A skill may look simple on disk:
.claude/
└── skills/
└── code-review/
└── SKILL.md
Enter fullscreen mode Exit fullscreen mode
But conceptually the runtime does something like:
User request
↓
Skill discovery
↓
Trigger evaluation
↓
Skill activation
↓
Instruction loading
↓
Reference/tool loading
↓
Agent execution
↓
Result
Enter fullscreen mode Exit fullscreen mode
The important question is:
What does the agent actually see, and when does it see it?
This matters because context is limited.
A skill might contain:
SKILL.md
references/
database.md
security.md
examples.md
architecture.md
scripts/
validate.js
check.sh
templates/
report.md
Enter fullscreen mode Exit fullscreen mode
You usually don’t want every file loaded for every request.
Instead:
Request
↓
SKILL.md
↓
Determine relevant task
↓
Load relevant reference
↓
Execute required script
Enter fullscreen mode Exit fullscreen mode
This is progressive context loading.
The main skill file acts as an entry point rather than a giant knowledge dump.
Context Is a Resource
One of the biggest mistakes in AI skill design is treating context as free.
It isn’t.
Design A — Everything in one file
SKILL.md
──────────────
3000 lines
50 examples
20 rules
10 workflows
15 edge cases
Enter fullscreen mode Exit fullscreen mode
Design B — Layered knowledge
SKILL.md
↓
Routing
↓
references/
├── workflow.md
├── security.md
└── examples.md
Enter fullscreen mode Exit fullscreen mode
The second design gives you more control over what enters the model’s context.
Design skills around context boundaries, not just file boundaries.
3. Chapter 01 — Fit and Scope
The next question is:
Should this behavior be implemented as a skill?
AI development environments often provide multiple primitives:
Skill
Rule
Agent
Hook
Script
Plugin
Enter fullscreen mode Exit fullscreen mode
They are not interchangeable.
Skill
A skill describes how to perform a class of task.
Example:
database-migration
Enter fullscreen mode Exit fullscreen mode
It might define:
1. Inspect schema
2. Inspect migration history
3. Design migration
4. Implement migration
5. Validate migration
6. Test rollback
Enter fullscreen mode Exit fullscreen mode
Rule
A rule is a constraint:
Never modify production data directly.
Enter fullscreen mode Exit fullscreen mode
That is policy, not a workflow.
Agent
An agent is useful when you need a distinct reasoning or execution role:
Main Agent
├── Research Agent
├── Security Agent
└── Testing Agent
Enter fullscreen mode Exit fullscreen mode
Hook
A hook responds to an event:
Before tool call
↓
Security check
Enter fullscreen mode Exit fullscreen mode
or:
After file modification
↓
Formatter
Enter fullscreen mode Exit fullscreen mode
Script
A script performs deterministic computation:
validate-schema.js
Enter fullscreen mode Exit fullscreen mode
The AI may decide when to run it. The script determines how validation works.
4. The Boundary Is More Important Than the Skill
A good skill should explicitly state what it does not do.
For example:
This skill handles:
- PostgreSQL schema migrations
- Migration generation
- Migration validation
- Rollback testing
This skill does not handle:
- Application architecture
- Production deployment
- Database backups
- Infrastructure provisioning
Enter fullscreen mode Exit fullscreen mode
Why?
Because skills tend to grow.
A developer starts with:
database migration
Enter fullscreen mode Exit fullscreen mode
Then adds:
database design
query optimization
backup strategy
production deployment
Enter fullscreen mode Exit fullscreen mode
Eventually the skill becomes:
database-engineering-everything
Enter fullscreen mode Exit fullscreen mode
and becomes difficult to reason about.
Scope is a defense against skill inflation.
5. Chapter 02 — Typing and Triggers
Once you know what a skill does, you need to answer:
When should it activate?
Imagine:
frontend-review
backend-review
security-review
performance-review
database-review
Enter fullscreen mode Exit fullscreen mode
The user says:
“Review my authentication API.”
Multiple skills may be relevant.
You now have a routing problem:
User request
│
┌─────────────┼─────────────┐
↓ ↓ ↓
Backend Security Performance
Enter fullscreen mode Exit fullscreen mode
If everything activates, the system becomes noisy.
If nothing activates, the skill is useless.
Activation Is a Classification Problem
Think of activation as:
User request
↓
Intent classification
↓
Skill candidates
↓
Relevance evaluation
↓
Activation
Enter fullscreen mode Exit fullscreen mode
Example:
Request Expected skill “Create a PostgreSQL migration” Database migration “Fix this React component” Frontend “Audit authentication” Security “Why is this query slow?” Database performance “Write a technical article” DocumentationA good skill therefore needs a clear activation signature.
False Positives and False Negatives
False positive
"Write a blog about PostgreSQL"
→ security skill activates
Enter fullscreen mode Exit fullscreen mode
False negative
"Why is my PostgreSQL migration failing?"
→ database migration skill does not activate
Enter fullscreen mode Exit fullscreen mode
Both are important.
Therefore, evaluate activation separately from execution.
6. Chapter 03 — Shape and Architecture
Once a skill activates, what does it actually do?
There are several useful workflow shapes.
Route
A route chooses a path:
Request
↓
classify
/ | / | Bug Feature Refactor
↓ ↓ ↓
Debug Implement Refactor
Enter fullscreen mode Exit fullscreen mode
Pipeline
A pipeline is sequential:
Research
↓
Analyze
↓
Plan
↓
Implement
↓
Test
↓
Review
↓
Report
Enter fullscreen mode Exit fullscreen mode
This is particularly useful for engineering skills.
Loop
A loop supports iteration:
Implement
↓
Test
↓
Failed?
/ Yes No
↓ ↓
Fix Complete
↓
Test again
Enter fullscreen mode Exit fullscreen mode
For coding agents, this is natural:
Write implementation
↓
Run tests
↓
Read failure
↓
Modify implementation
↓
Run tests again
Enter fullscreen mode Exit fullscreen mode
Failure becomes an expected workflow state rather than an exceptional event.
Map
A map splits a problem into independent pieces:
Research repository
│
┌─────────────┼─────────────┐
↓ ↓ ↓
Frontend Backend Database
↓ ↓ ↓
Findings Findings Findings
└─────────────┼─────────────┘
↓
Synthesis
Enter fullscreen mode Exit fullscreen mode
Combining Shapes
Real skills often combine these patterns:
Route
↓
Pipeline
↓
Map
↓
Loop
↓
Final report
Enter fullscreen mode Exit fullscreen mode
This is where AI skills start looking like workflow engines rather than prompts.
7. Chapter 04 — Anatomy
A mature skill might look like:
skills/
└── deep-research/
│
├── SKILL.md
│
├── references/
│ ├── research-methodology.md
│ ├── source-evaluation.md
│ └── evidence.md
│
├── scripts/
│ ├── validate-sources.js
│ └── generate-report.js
│
├── templates/
│ └── report.md
│
└── examples/
├── example-1.md
└── example-2.md
Enter fullscreen mode Exit fullscreen mode
Each part has a job.
SKILL.md Is the Hub
Think of SKILL.md as the router and operating manual.
It should explain:
What this skill does
When it activates
What it must accomplish
What references to load
What workflow to follow
What constraints apply
How to validate the result
Enter fullscreen mode Exit fullscreen mode
It should not necessarily contain every piece of knowledge.
Hub-and-Spoke Architecture
SKILL.md
/ | / | ↓ ↓ ↓
References Scripts Templates
Enter fullscreen mode Exit fullscreen mode
The hub provides orchestration.
The spokes provide specialized resources.
Data vs Instructions vs Code
Separate them:
Instructions
SKILL.md
Enter fullscreen mode Exit fullscreen mode
Tell the agent what to do.
Data
references/
Enter fullscreen mode Exit fullscreen mode
Provide knowledge.
Code
scripts/
Enter fullscreen mode Exit fullscreen mode
Perform deterministic operations.
This separation makes skills easier to maintain and test.
8. Chapter 05 — Writing the Content
Now we reach the instruction layer.
Compare:
Weak
You might want to check whether tests pass.
Strong
Run the test suite before declaring the task complete.
Stronger
Do not declare the task complete until the test suite passes.
The difference is binding strength.
Instructions Have Different Authority
Preference
Prefer TypeScript.
Enter fullscreen mode Exit fullscreen mode
Requirement
Use TypeScript for new files.
Enter fullscreen mode Exit fullscreen mode
Hard constraint
Do not create JavaScript files. New implementation files must use TypeScript.
Enter fullscreen mode Exit fullscreen mode
Important rules should be unambiguous.
Present-Tense Instructions
Instead of:
The agent should inspect the repository.
Enter fullscreen mode Exit fullscreen mode
write:
Inspect the repository before making changes.
Enter fullscreen mode Exit fullscreen mode
Instead of:
The agent will run the tests after implementation.
Enter fullscreen mode Exit fullscreen mode
write:
Run the tests after implementation.
Enter fullscreen mode Exit fullscreen mode
Direct instructions are easier to interpret.
Don’t Overload the Skill With Philosophy
Avoid thousands of words explaining philosophy.
Prefer operational instructions:
1. Inspect X.
2. Determine Y.
3. Run Z.
4. If Z fails, investigate.
5. Do not proceed until Y is verified.
Enter fullscreen mode Exit fullscreen mode
The skill should be operational.
9. Chapter 06 — Enforcement
This is one of the most important ideas.
Don’t rely on the model to enforce something that software can enforce.
Suppose your skill says:
Always run Prettier.
Enter fullscreen mode Exit fullscreen mode
The agent might comply.
But it might also forget.
A stronger design is:
AI modifies file
↓
Hook
↓
Prettier
↓
Formatted file
Enter fullscreen mode Exit fullscreen mode
Formatting no longer depends entirely on model memory.
AI Instructions vs Mechanical Enforcement
Consider:
Never commit secrets.
A prompt can say:
RULE:
Never commit API keys.
Enter fullscreen mode Exit fullscreen mode
But a stronger architecture is:
Agent
↓
git commit
↓
secret scanner
↓
Secret found?
├── Yes → Block commit
└── No → Continue
Enter fullscreen mode Exit fullscreen mode
Enforcement Hierarchy
A useful model is:
Human judgment
↓
AI instruction
↓
Automated validation
↓
Mechanical enforcement
Enter fullscreen mode Exit fullscreen mode
The further down the stack you go, the less you rely on model compliance.
Examples of good candidates for automation:
Formatting
Linting
Type checking
Schema validation
Tests
Secret detection
File naming
Generated artifacts
SQL safety
Permission boundaries
Enter fullscreen mode Exit fullscreen mode
The AI should focus on tasks requiring judgment.
10. Chapter 07 — Measurement
Now ask:
How do we know the skill works?
A skill should ideally be evaluated, not merely read and trusted.
There are two major dimensions.
Activation Evaluation
Did the correct skill activate?
Example:
Prompt:
"Create a PostgreSQL migration for the users table."
Expected:
database-migration → activated
Enter fullscreen mode Exit fullscreen mode
You can maintain an evaluation set:
┌────────────────────────────────────┐
│ Activation Evaluation │
├────────────────────────────────────┤
│ Prompt │
│ Expected skill │
│ Should activate? │
│ Actual skill │
│ Result │
└────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode
Behavior Evaluation
Once activated, did the skill behave correctly?
Suppose the migration skill requires:
Inspect schema
Check migration history
Create migration
Validate SQL
Test migration
Test rollback
Enter fullscreen mode Exit fullscreen mode
Behavior evaluation checks those requirements.
Skill
↓
┌────────┴────────┐
↓ ↓
Activation Behavior
↓ ↓
Correct skill? Correct workflow?
Enter fullscreen mode Exit fullscreen mode
A skill could have:
90% activation accuracy
40% behavior accuracy
Enter fullscreen mode Exit fullscreen mode
and still be a poor skill.
Measuring Skills Like Software
Useful metrics include:
Activation accuracy
correct activations / total activation tests
Enter fullscreen mode Exit fullscreen mode
False positive rate
incorrect activations / total tests
Enter fullscreen mode Exit fullscreen mode
False negative rate
missed activations / applicable tests
Enter fullscreen mode Exit fullscreen mode
Task success rate
successful executions / total executions
Enter fullscreen mode Exit fullscreen mode
Rule compliance
required behaviors satisfied / required behaviors
Enter fullscreen mode Exit fullscreen mode
Regression rate
previously passing cases now failing
Enter fullscreen mode Exit fullscreen mode
This turns skill development into an engineering discipline.
11. Auditing Against Prior Art
Another useful activity is comparing your skill against existing approaches.
Suppose you create:
deep-research
Enter fullscreen mode Exit fullscreen mode
Before declaring it complete, ask:
What existing research workflows already exist?
What evaluation techniques do they use?
What source-quality rules are common?
What am I missing?
Which practices are unnecessarily complicated?
Enter fullscreen mode Exit fullscreen mode
This is prior-art auditing.
You don’t need to reinvent every workflow.
12. Chapter 08 — Shipping
A skill isn’t useful if nobody can install it.
A typical flow is:
Development
↓
Repository
↓
Package / Plugin
↓
Distribution
↓
Installation
↓
Skill available
Enter fullscreen mode Exit fullscreen mode
Plugin Binding
A plugin can act as a distribution container:
Plugin
│
├── Skills
│ ├── research
│ ├── testing
│ └── code-review
│
├── Hooks
├── Commands
└── Configuration
Enter fullscreen mode Exit fullscreen mode
This lets users install a cohesive collection rather than manually copying individual files.
Versioning
Once users depend on a skill, versioning matters:
[email protected]
[email protected]
[email protected]
Enter fullscreen mode Exit fullscreen mode
Changing:
"prefer X"
Enter fullscreen mode Exit fullscreen mode
to:
"must use X"
Enter fullscreen mode Exit fullscreen mode
can change agent behavior significantly.
Therefore skill versions should be treated as meaningful behavioral versions.
Dormancy
A skill may sit unused for months.
Then:
Developer
↓
invokes old skill
↓
framework changed
↓
skill behaves differently
Enter fullscreen mode Exit fullscreen mode
This is skill dormancy.
Skills need lifecycle states and maintenance expectations.
13. Chapter 09 — Maintenance
AI skills exist inside rapidly changing ecosystems.
Things change:
AI models
Agent runtimes
APIs
CLI tools
Frameworks
Repository structures
Tool interfaces
Best practices
Security requirements
Enter fullscreen mode Exit fullscreen mode
Therefore:
A skill is software, and software drifts.
Drift
Suppose:
Tool v1
↓
Skill v1
Enter fullscreen mode Exit fullscreen mode
Later:
Tool v2
↓
behavior changed
Enter fullscreen mode Exit fullscreen mode
Your skill still assumes the old behavior.
That is drift.
Vendored Knowledge
Suppose your skill contains a copy of external documentation:
external methodology
↓
copy
↓
your skill
Enter fullscreen mode Exit fullscreen mode
The external source changes.
Your copy doesn’t.
Now:
Upstream
↓
Version 3
Your skill
↓
Version 1
Enter fullscreen mode Exit fullscreen mode
You have a maintenance obligation.
Review Gate
A good update flow is:
Upstream changes
↓
Detect change
↓
Review
↓
Update skill
↓
Run evaluation suite
↓
Check regressions
↓
Release
Enter fullscreen mode Exit fullscreen mode
Not:
Upstream changed
↓
blindly copy everything
Enter fullscreen mode Exit fullscreen mode
14. Chapter 10 — The Skill Portfolio
One skill is easy.
Two are manageable.
Ten are interesting.
Fifty become an architecture problem.
You may eventually have:
skills/
├── research/
├── frontend/
├── backend/
├── database/
├── security/
├── testing/
├── performance/
├── deployment/
├── documentation/
├── architecture/
├── debugging/
└── code-review/
Enter fullscreen mode Exit fullscreen mode
Now you need portfolio management.
Skill Collision
Suppose the user says:
“Review my API.”
Potential matches:
api-review
backend-review
security-review
performance-review
Enter fullscreen mode Exit fullscreen mode
Which one activates?
This is a collision.
If multiple skills activate, their instructions may conflict.
For example:
Skill A:
"Keep the implementation minimal."
Skill B:
"Add extensive validation."
Skill C:
"Refactor the architecture."
Enter fullscreen mode Exit fullscreen mode
A skill portfolio therefore needs routing and priority policies.
Skill Granularity
How large should a skill be?
Too broad:
software-engineering
Enter fullscreen mode Exit fullscreen mode
with everything inside it.
Too narrow:
read-file
write-file
check-import
check-variable
run-test
Enter fullscreen mode Exit fullscreen mode
You don’t want hundreds of microscopic skills.
A better structure might be:
Engineering
│
├── Research
├── Implementation
├── Testing
├── Security
└── Deployment
Enter fullscreen mode Exit fullscreen mode
Each skill owns a meaningful capability.
Router Families
A router can first identify the broad family:
User request
↓
Main Router
↓
┌───────────────┼───────────────┐
↓ ↓ ↓
Research Engineering Operations
↓ ↓ ↓
Research Backend Deployment
skill Security Monitoring
Testing
Enter fullscreen mode Exit fullscreen mode
Instead of asking:
“Which of these 100 skills should run?”
you ask:
Which family?
↓
Which subcategory?
↓
Which skill?
Enter fullscreen mode Exit fullscreen mode
Retirement
A healthy portfolio needs a retirement policy.
A skill may become obsolete because:
- the underlying tool disappeared
- the workflow became part of another skill
- the framework changed
- the skill is redundant
- another skill superseded it
- nobody uses it anymore
A lifecycle might be:
Experimental
↓
Active
↓
Stable
↓
Deprecated
↓
Retired
Enter fullscreen mode Exit fullscreen mode
This prevents the skill directory from becoming a graveyard.
15. The Deeper Architecture: Instructions + Tools + Enforcement + Evaluation
A mature skill can be viewed as four major layers:
┌──────────────────────────────────────┐
│ SKILL │
│ │
│ ┌────────────────────────────────┐ │
│ │ Instructions │ │
│ │ What the agent should do │ │
│ └────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────┐ │
│ │ Workflow │ │
│ │ Route / Pipeline / Loop / Map │ │
│ └────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────┐ │
│ │ Enforcement │ │
│ │ Hooks / Scripts / Tests │ │
│ └────────────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────────────┐ │
│ │ Evaluation │ │
│ │ Activation / Behavior / QA │ │
│ └────────────────────────────────┘ │
└──────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode
This is the important shift in thinking.
A skill is not merely:
prompt → answer
Enter fullscreen mode Exit fullscreen mode
It is closer to:
intent
↓
routing
↓
context
↓
workflow
↓
tools
↓
validation
↓
feedback
↓
result
Enter fullscreen mode Exit fullscreen mode
16. Example: Building a Deep Research Skill
Suppose you want:
deep-research
Enter fullscreen mode Exit fullscreen mode
Its directory could be:
deep-research/
├── SKILL.md
├── references/
│ ├── research-methodology.md
│ ├── source-quality.md
│ ├── evidence-evaluation.md
│ └── synthesis.md
├── scripts/
│ ├── validate-sources.js
│ └── generate-report.js
├── templates/
│ └── research-report.md
└── evals/
├── activation.json
└── behavior.json
Enter fullscreen mode Exit fullscreen mode
Step 1 — Define Scope
This skill performs structured research.
It handles:
- multi-source research
- source evaluation
- evidence synthesis
- contradiction analysis
- structured reporting
It does not handle:
- software implementation
- deployment
- generic writing
Enter fullscreen mode Exit fullscreen mode
Step 2 — Define Activation
Potential activation prompts:
"Research this topic deeply."
"Investigate the current state of..."
"Compare these technologies using external sources."
"Find evidence for and against this claim."
Enter fullscreen mode Exit fullscreen mode
Non-activation examples:
"Fix this React bug."
"Run the tests."
"Format this file."
Enter fullscreen mode Exit fullscreen mode
Step 3 — Define the Workflow
Understand question
↓
Decompose question
↓
Identify evidence requirements
↓
Search
↓
Evaluate sources
↓
Extract evidence
↓
Cross-check claims
↓
Synthesize
↓
Write report
↓
Validate citations
Enter fullscreen mode Exit fullscreen mode
Step 4 — Add a Loop
If two sources disagree:
Source A → Claim X
Source B → Claim Y
Enter fullscreen mode Exit fullscreen mode
then:
Conflict detected
↓
Investigate
↓
Find additional sources
↓
Re-evaluate evidence
↓
Resolve / report uncertainty
Enter fullscreen mode Exit fullscreen mode
Now the skill combines:
Pipeline + Loop
Enter fullscreen mode Exit fullscreen mode
Step 5 — Add Mechanical Validation
Instead of only telling the AI:
“Make sure every claim has a citation.”
build a validator:
Report
↓
Citation validator
↓
Missing citation?
├── Yes → fail
└── No → pass
Enter fullscreen mode Exit fullscreen mode
Step 6 — Evaluate Activation
Example:
Prompt:
"Do a deep investigation into DuckDB vs PostgreSQL for analytics."
Expected:
deep-research → YES
Enter fullscreen mode Exit fullscreen mode
And:
Prompt:
"Fix the DuckDB connection bug."
Expected:
deep-research → NO
Enter fullscreen mode Exit fullscreen mode
Step 7 — Evaluate Behavior
For a research request:
✓ question decomposition
✓ multiple sources
✓ source quality assessment
✓ evidence extraction
✓ conflicting evidence analysis
✓ synthesis
✓ citations
✓ final report
Enter fullscreen mode Exit fullscreen mode
Now regressions can be detected.
17. Applying This to an AI Engineering Harness
This model becomes especially interesting when building a larger AI development harness.
Imagine:
AI HARNESS
│
↓
Intent Router
│
┌───────────────┼───────────────┐
↓ ↓ ↓
Research Engineering Operations
│ │ │
↓ ↓ ↓
Skills Skills Skills
│ │ │
└───────────────┼───────────────┘
↓
Tools
↓
Enforcement
↓
Evaluation
↓
Reporting
Enter fullscreen mode Exit fullscreen mode
This is much more powerful than simply having a folder full of Markdown files.
18. Skills as a Policy Execution Layer
Traditional software:
Code
↓
Execution
↓
Result
Enter fullscreen mode Exit fullscreen mode
AI software:
Intent
↓
Skill
↓
Reasoning
↓
Tools
↓
Result
Enter fullscreen mode Exit fullscreen mode
But production AI systems need another layer:
Intent
↓
Skill
↓
Reasoning
↓
Tools
↓
Policy
↓
Validation
↓
Result
Enter fullscreen mode Exit fullscreen mode
The skill becomes a bridge between natural-language intent and deterministic engineering systems.
19. The Most Important Design Principle
If there is one idea to take away from all of this, it is:
Use AI for judgment. Use software for certainty.
Let the model handle:
Interpretation
Planning
Hypothesis generation
Trade-offs
Synthesis
Creative reasoning
Enter fullscreen mode Exit fullscreen mode
Let software handle:
Formatting
Validation
Testing
Schema checking
Permissions
Secret detection
Deterministic calculations
Policy enforcement
Enter fullscreen mode Exit fullscreen mode
For example:
AI:
"These three files probably need to change."
Software:
"Does the resulting code compile?"
AI:
"This migration should be safe."
Software:
"Does the migration actually execute successfully?"
AI:
"These sources support the conclusion."
Software:
"Are the required citations present?"
Enter fullscreen mode Exit fullscreen mode
That division produces more reliable systems.
20. Why Skill Engineering Will Become Important
As AI agents become more capable, the bottleneck increasingly shifts away from:
“Can the model write code?”
toward:
“Can we reliably control how the model works?”
That is a different engineering problem.
We need to reason about:
Activation
Context
Permissions
Workflow
Tools
Memory
Policies
Evaluation
Regression
Versioning
Distribution
Enter fullscreen mode Exit fullscreen mode
These are systems problems.
That is why skill engineering starts resembling:
software architecture
+
prompt engineering
+
workflow orchestration
+
testing
+
policy enforcement
+
package management
Enter fullscreen mode Exit fullscreen mode
21. Practical Checklist for Building a Skill
Scope
- [ ] Is this actually a skill?
- [ ] Could this be a rule?
- [ ] Could this be a hook?
- [ ] Could this be a script?
- [ ] What does the skill explicitly refuse to do?
Activation
- [ ] When should it activate?
- [ ] When should it not activate?
- [ ] What are the ambiguous prompts?
- [ ] Can it collide with another skill?
Architecture
- [ ] Is the workflow a route?
- [ ] Pipeline?
- [ ] Loop?
- [ ] Map?
- [ ] Combination of these?
Context
- [ ] Is
SKILL.mdconcise? - [ ] Can supporting information be loaded progressively?
- [ ] Are references separated from instructions?
Enforcement
- [ ] Which rules can be automated?
- [ ] Which checks should be hooks?
- [ ] Which checks should be scripts?
- [ ] Which requirements belong in CI?
Evaluation
- [ ] Does the skill activate correctly?
- [ ] Does it perform the correct workflow?
- [ ] Are there regression tests?
- [ ] Are failure cases tested?
Shipping
- [ ] Is the skill versioned?
- [ ] Can another developer install it?
- [ ] Is plugin/package integration defined?
Maintenance
- [ ] What external dependencies can drift?
- [ ] Are vendored references tracked?
- [ ] Is there a review process?
- [ ] Can the skill become deprecated?
Portfolio
- [ ] Does it overlap with another skill?
- [ ] Is the granularity appropriate?
- [ ] Does the router know where it belongs?
- [ ] What happens when the skill is obsolete?
22. Final Architecture
Putting everything together:
USER INTENT
│
▼
┌────────────────┐
│ ROUTER │
└───────┬────────┘
│
▼
┌──────────────────┐
│ SKILL │
│ │
│ Scope │
│ Instructions │
│ Workflow │
│ References │
└────────┬─────────┘
│
▼
┌─────────────────────┐
│ AI REASONING │
└──────────┬──────────┘
│
┌──────────┴──────────┐
↓ ↓
Tools / APIs Scripts
│ │
└──────────┬──────────┘
↓
┌─────────────────┐
│ ENFORCEMENT │
│ │
│ Hooks │
│ Policies │
│ Validators │
└────────┬────────┘
↓
┌─────────────────┐
│ EVALUATION │
│ │
│ Activation │
│ Behavior │
│ Regression │
└────────┬────────┘
↓
RESULT
Enter fullscreen mode Exit fullscreen mode
And around the whole system:
┌───────────────────────────────────┐
│ SKILL LIFECYCLE │
│ │
│ Version → Ship → Observe → │
│ Maintain → Update → Deprecate │
│ │
└───────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode
Conclusion: From Prompt Files to AI Engineering
The simplest way to build an AI skill is:
Write SKILL.md
Enter fullscreen mode Exit fullscreen mode
The professional way is:
Define scope
↓
Define activation
↓
Design workflow
↓
Structure context
↓
Write instructions
↓
Add tools
↓
Mechanically enforce critical rules
↓
Evaluate activation
↓
Evaluate behavior
↓
Version
↓
Ship
↓
Monitor drift
↓
Maintain
↓
Retire when necessary
Enter fullscreen mode Exit fullscreen mode
That is the fundamental shift.
AI skills should be treated less like prompts and more like software components.
A prompt tells an AI what you would like it to do.
A well-engineered skill defines:
- when it should act,
- what it should do,
- what context it should consume,
- how it should execute,
- which rules are mandatory,
- what software can enforce,
- how success is measured, and
- how the component evolves over time.
Once you start thinking this way, .claude/skills/ stops being a collection of Markdown files.
It becomes an AI-native software architecture layer.
The future of agent engineering is not just better prompts — it is better systems around prompts.