17KB
Skill Builder
Version: 1.0.0 Status: ACTIVE
Purpose
Create, revise, split, merge, test, version, and maintain reusable agent skills.
This skill governs the quality of the skill library.
Its purpose is to prevent self-improvement from becoming:
TOO MANY SKILLS
OVERLAPPING SKILLS
VAGUE SKILLS
UNTESTED SKILLS
GIANT SKILLS
PROJECT FACTS DISGUISED AS SKILLS
The goal is:
SMALL
CLEAR
REUSABLE
TESTABLE
MAINTAINABLE
skills.
1. Trigger Conditions
Use this skill when:
- creating a new
SKILL.md - materially revising an existing skill
- splitting an oversized skill
- merging overlapping skills
- changing a skill's trigger
- changing a skill's output contract
- adding important verification behavior
- promoting a candidate skill to active
- deprecating a skill
For initial discovery of whether a skill should exist, use:
.ai/skills/skill-extractor/SKILL.md
The extractor decides whether a reusable skill is justified.
The builder determines how to build it well.
2. Core Skill Model
A good skill can usually be described as:
TRIGGER
↓
INPUT
↓
PRECONDITIONS
↓
PROCEDURE
↓
OUTPUT
↓
VERIFICATION
↓
FAILURE HANDLING
If these cannot be defined clearly, the skill may not be ready.
3. One Coherent Job
Each skill should have one coherent responsibility.
Good:
iis-deployment
access-csv-import
database-migration
api-security-review
Weak:
windows-and-database-and-deployment-and-debugging
If a skill requires several unrelated triggers, it is probably too broad.
4. Skill Purpose Test
The purpose should answer:
What reusable job does this skill perform?
Good:
Safely deploy an IIS application with preflight checks,
rollback, restart, and health verification.
Weak:
Help with deployment.
The purpose should be precise enough that another agent can decide whether the skill applies.
5. Trigger Design
Triggers should be operational.
Good:
Use when deploying an application to IIS and the deployment
must handle service state, file replacement, rollback, and health checks.
Weak:
Use for IIS.
A broad trigger causes unnecessary skill loading.
6. Negative Trigger
When useful, define when NOT to use the skill.
Example:
Do not use for changing a single IIS binding
when no application deployment occurs.
This prevents scope creep.
7. Inputs
Define required and optional inputs.
Example:
Required:
APPLICATION_NAME
DEPLOYMENT_PACKAGE
TARGET_PATH
Optional:
APP_POOL
HEALTH_CHECK_URL
BACKUP_PATH
If an input is discoverable:
DISCOVER IT
before asking the user.
8. Preconditions
Define what must be true before the skill starts.
Examples:
deployment package exists
backup location is writable
database connection is available
source file is complete
required service account exists
Preconditions prevent failures from being discovered too late.
9. Procedure
Write the procedure as observable actions.
Good:
1. inspect current application state
2. validate deployment package
3. create rollback point
4. stop or drain application
5. deploy
6. restart
7. run health checks
8. rollback if verification fails
Weak:
1. think carefully
2. use best practices
3. deploy safely
Skills should describe behavior that can actually be followed.
10. Decision Rules
When a skill branches, make decisions explicit.
Example:
IF health check passes
mark deployment successful
IF health check fails
restore previous release
restart
rerun health check
Avoid burying important branches inside paragraphs.
11. Output Contract
Define exactly what the skill should produce.
Example:
DEPLOYMENT RESULT
VERIFICATION RESULT
ROLLBACK STATUS
ERRORS OR WARNINGS
RELEVANT LOG LOCATION
Another agent should know when the skill is complete.
12. Verification
Every meaningful skill must define verification.
Ask:
What evidence proves the procedure worked?
Possible verification:
tests
build
query
row counts
file existence
health endpoint
service status
checksum
response code
log inspection
“Looks correct” is not sufficient verification.
13. Failure Handling
Document expected handling for meaningful failure classes.
Examples:
missing input
invalid input
permission failure
dependency unavailable
partial execution
verification failure
rollback failure
Do not try to document every theoretical error.
Focus on realistic and consequential failures.
14. Safety Rules
Consequential skills should explicitly state what must not happen.
Examples:
do not delete source data before successful verification
do not disable security controls to complete deployment
do not continue a migration after integrity validation fails
do not expose credentials in logs
Safety rules should be concrete.
15. Scope Placement
Before adding a rule to a skill, ask whether it belongs somewhere else.
GLOBAL?
→ AGENTS.md
CLAUDE-SPECIFIC?
→ CLAUDE.md
PROJECT FACT?
→ project docs
WORKFLOW-WIDE?
→ WORKFLOW.md
SPECIALIZED PROCEDURE?
→ SKILL.md
Correct placement reduces duplication.
16. Avoid Root Rule Duplication
Do not repeat generic instructions already defined in AGENTS.md unless a short reminder is necessary.
Example:
If AGENTS.md already says:
Verify all substantial work.
the skill should define:
HOW THIS PARTICULAR SKILL IS VERIFIED
not repeat several paragraphs about general verification philosophy.
17. Avoid Skill Duplication
Before creating or revising:
SEARCH .ai/skills/
Check for:
same trigger
same procedure
same outputs
same domain
If overlap is high:
EXTEND
MERGE
OR REDEFINE SCOPE
instead of creating another skill.
18. Skill Granularity
A skill is too small when it represents something like:
how to call Get-Date
how to create one directory
how to print a message
unless the tiny procedure has unusual domain-specific constraints.
A skill is too large when it tries to cover:
all Windows administration
all database work
all web development
Aim for reusable operational units.
19. Split Test
Consider splitting a skill when:
it has unrelated triggers
different sections are used independently
agents load lots of irrelevant instructions
the file becomes hard to maintain
different parts need different versioning
Example:
windows-server-management
may split into:
openssh-installation
windows-firewall
iis-deployment
certificate-management
only if real usage supports those distinctions.
20. Merge Test
Consider merging skills when:
triggers overlap heavily
procedures duplicate each other
one skill always invokes the other
agents struggle to decide which to use
Example:
csv-import
tsv-import
pipe-delimited-import
may become:
delimited-file-import
with format parameters.
21. Skill Dependency
A skill may invoke another skill.
Example:
database-migration
↓
mirror-audit
then later:
red-team
Reference the skill.
Do not paste the entire dependency into the current file.
22. Avoid Circular Skill Dependencies
Bad:
Skill A → Skill B
Skill B → Skill A
If this appears, extract shared behavior.
Possible solution:
COMMON SKILL
or a root workflow rule.
23. Skill Status
Use:
CANDIDATE
DRAFT
TESTED
ACTIVE
DEPRECATED
Candidate
Observed but not sufficiently validated.
Draft
Formalized but not fully tested.
Tested
Passed defined scenarios.
Active
Approved for normal agent use.
Deprecated
No longer recommended.
24. Candidate to Active Flow
CANDIDATE
↓
DRAFT
↓
ORIGINAL TEST
↓
TRANSFER TEST
↓
SYSTEM AUDIT
↓
ACTIVE
Do not label an important new skill ACTIVE merely because the file was created.
25. Test Cases
At minimum, test:
NORMAL CASE
SECOND DIFFERENT CASE
When relevant also test:
FAILURE CASE
COUNTEREXAMPLE
The counterexample checks that the trigger does not activate incorrectly.
26. Normal Case
Use a realistic expected input.
Verify:
procedure is complete
output is useful
verification is clear
27. Transfer Case
Use a different scenario that should still use the skill.
This checks whether the skill was generalized correctly.
28. Failure Case
Create a realistic failure.
Example:
deployment package missing
Verify that the skill:
stops safely
reports the failure
does not continue into destructive steps
29. Counterexample
Use a task that should NOT activate the skill.
Example:
Skill:
iis-deployment
Counterexample:
Change one IIS custom header.
The agent should not force a full deployment workflow onto that task.
30. System Audit
After changing a skill, run:
.ai/skills/system-audit/SKILL.md
Check:
authority
scope
conflicts
duplication
references
behavior
regression
bloat
31. Versioning
Use semantic-style versions.
MAJOR.MINOR.PATCH
32. PATCH Changes
Examples:
wording clarification
missing check
better example
minor failure-handling correction
Example:
1.0.0 → 1.0.1
33. MINOR Changes
Examples:
new procedure branch
new supported scenario
new verification method
new non-breaking output
Example:
1.0.1 → 1.1.0
34. MAJOR Changes
Examples:
trigger changes incompatibly
skill changes purpose
output contract changes incompatibly
procedure is fundamentally redesigned
Example:
1.4.2 → 2.0.0
35. Skill Changelog
Each skill should maintain a short local changelog.
Example:
## 1.1.0
Added rollback verification after repeated
deployment failures showed that backup existence
did not prove restore usability.
Evidence:
three failed deployment exercises.
Verification:
normal deployment + failed deployment + rollback test.
36. Global Changelog
Meaningful skill changes should also update:
.ai/CHANGELOG.md
The local skill changelog explains detailed skill evolution.
The global changelog explains AI-OS evolution.
37. Evidence Requirement
Before substantial revision, identify:
WHAT OBSERVATION JUSTIFIES THIS?
Possible evidence:
user correction
failed task
failed test
repeated workaround
successful repeated pattern
project evolution
Avoid speculative feature creep in skills.
38. Smallest Useful Revision
When a skill fails, prefer:
one missing branch
one stronger trigger
one verification rule
one clearer constraint
before rewriting the whole skill.
Small changes are easier to validate.
39. Do Not Optimize for File Count
The self-improving system is not judged by:
NUMBER OF SKILLS
It is judged by:
USEFULNESS
REUSE
ERROR REDUCTION
CLARITY
A project with 12 excellent skills is better than one with 150 vague ones.
40. Skill Size
There is no rigid line-count limit.
However, when a skill becomes long, ask:
Does every section affect this one skill?
Could examples move to supporting files?
Could a domain branch become its own skill?
Is root guidance being duplicated?
Optimize for relevant context.
41. Supporting Files
A skill directory may contain:
SKILL.md
examples/
templates/
scripts/
tests/
references/
Example:
.ai/skills/iis-deployment/
├── SKILL.md
├── examples/
│ └── deployment-example.md
├── scripts/
│ └── health-check.ps1
└── tests/
└── scenarios.md
Only add supporting files when they improve execution.
42. Skill Tests
Important skills may maintain behavioral test scenarios.
Example:
## Test 1
Given:
Valid deployment package.
Expect:
backup → stop → deploy → start → health check.
## Test 2
Given:
Health check fails.
Expect:
rollback attempt.
## Test 3
Given:
Simple IIS header change.
Expect:
skill should not activate.
This makes skill evolution testable.
43. Self-Creation Rules
Agents may use Skill Builder to create additional supporting AI files if necessary.
Possible additions:
tests
examples
templates
prompts
validation scripts
But every new file should answer:
What reusable burden does this remove?
If none, do not create it.
44. Root Routing Rule
If a skill becomes an important standard workflow, add only a short routing rule to AGENTS.md.
Example:
For production IIS deployments, use `.ai/skills/iis-deployment/SKILL.md`.
This makes the skill discoverable without bloating root instructions.
45. Project-Specific Skills
Project-specific skills are allowed and encouraged when evidence supports them.
Examples:
classic-asp-controller
survey-question-import
maildat-certified-mail
territory-address-sort
These should encode real project procedures.
Do not generalize them unnecessarily if their value is specifically project-bound.
46. Generic Skills
Generic skills should avoid accidental project-specific assumptions.
Examples:
mirror-audit
red-team
prompt-debugger
retrospective
Keep generic skills portable.
47. Deprecation Procedure
When deprecating:
1. identify replacement or reason
2. mark Status: DEPRECATED
3. explain migration path if needed
4. update references
5. update changelog
6. remove later when safe
Do not leave active references pointing to deprecated skills.
48. Delete vs Deprecate
Deprecate when historical guidance or migration matters.
Delete when:
skill was experimental
skill was unused
skill duplicates another one
nothing references it
Version control should preserve history.
49. Quality Checklist
Before activating a skill:
[ ] Purpose is specific.
[ ] Trigger is clear.
[ ] Non-trigger is defined when useful.
[ ] Inputs are identified.
[ ] Discoverable inputs are not unnecessarily requested.
[ ] Preconditions are defined.
[ ] Procedure is executable.
[ ] Decision branches are explicit.
[ ] Output contract is clear.
[ ] Verification exists.
[ ] Failure handling exists.
[ ] Safety boundaries exist when relevant.
[ ] Existing skills were checked.
[ ] No obvious duplication exists.
[ ] Original scenario passes.
[ ] Transfer scenario passes.
[ ] Counterexample considered.
[ ] System audit passes.
[ ] Version is correct.
[ ] Changelog is updated.
50. Output Contract for Skill Builder
When creating a skill, produce:
SKILL NAME
PURPOSE
TRIGGER
FULL SKILL FILE
TEST SCENARIOS
VERSION
CHANGELOG UPDATE
When revising a skill, produce or apply:
OBSERVED PROBLEM
SMALLEST CHANGE
VERSION CHANGE
TEST RESULTS
CHANGELOG
51. Self-Improvement
Improve Skill Builder when:
- skill overlap continues growing
- skills are too broad or too narrow
- new skills repeatedly fail transfer tests
- agents struggle to choose triggers
- tests do not catch poor skill behavior
- skill files become unnecessarily large
The quality of the self-improving system depends heavily on this skill.
52. Changelog
1.0.0
Initial active version.
Introduced:
- coherent-job rule
- trigger and non-trigger design
- scope placement
- skill granularity
- split/merge criteria
- dependency management
- skill lifecycle/status
- normal/transfer/failure/counterexample testing
- versioning
- evidence-driven revision
- skill quality checklist