# 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:

```text id="f0d4yc"
TOO MANY SKILLS

OVERLAPPING SKILLS

VAGUE SKILLS

UNTESTED SKILLS

GIANT SKILLS

PROJECT FACTS DISGUISED AS SKILLS
```

The goal is:

```text id="xhwcr8"
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:

```text id="e63wx4"
.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:

```text id="yv048y"
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:

```text id="xa81kb"
iis-deployment

access-csv-import

database-migration

api-security-review
```

Weak:

```text id="9v0cgq"
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:

```text id="3g0z0m"
What reusable job does this skill perform?
```

Good:

```text id="1hhks3"
Safely deploy an IIS application with preflight checks,
rollback, restart, and health verification.
```

Weak:

```text id="mjg9z9"
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:

```text id="9mi7hu"
Use when deploying an application to IIS and the deployment
must handle service state, file replacement, rollback, and health checks.
```

Weak:

```text id="pjmj2u"
Use for IIS.
```

A broad trigger causes unnecessary skill loading.

---

# 6. Negative Trigger

When useful, define when NOT to use the skill.

Example:

```text id="ix6ajz"
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:

```text id="8b3oxr"
Required:

APPLICATION_NAME
DEPLOYMENT_PACKAGE
TARGET_PATH

Optional:

APP_POOL
HEALTH_CHECK_URL
BACKUP_PATH
```

If an input is discoverable:

```text id="nbmaao"
DISCOVER IT
```

before asking the user.

---

# 8. Preconditions

Define what must be true before the skill starts.

Examples:

```text id="5vcdh8"
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:

```text id="x3ocra"
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:

```text id="actpsi"
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:

```text id="od2xoa"
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:

```text id="06j0ec"
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:

```text id="sezpzg"
What evidence proves the procedure worked?
```

Possible verification:

```text id="91z33f"
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:

```text id="c3szcd"
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:

```text id="28ffsy"
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.

```text id="v4qa2h"
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:

```text id="8gr9yf"
Verify all substantial work.
```

the skill should define:

```text id="d83yk8"
HOW THIS PARTICULAR SKILL IS VERIFIED
```

not repeat several paragraphs about general verification philosophy.

---

# 17. Avoid Skill Duplication

Before creating or revising:

```text id="p50x3h"
SEARCH .ai/skills/
```

Check for:

```text id="7e490m"
same trigger

same procedure

same outputs

same domain
```

If overlap is high:

```text id="okynw0"
EXTEND

MERGE

OR REDEFINE SCOPE
```

instead of creating another skill.

---

# 18. Skill Granularity

A skill is too small when it represents something like:

```text id="j3wf9p"
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:

```text id="8ipzly"
all Windows administration

all database work

all web development
```

Aim for reusable operational units.

---

# 19. Split Test

Consider splitting a skill when:

```text id="vdw82h"
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:

```text id="hfe1cq"
windows-server-management
```

may split into:

```text id="gkijba"
openssh-installation

windows-firewall

iis-deployment

certificate-management
```

only if real usage supports those distinctions.

---

# 20. Merge Test

Consider merging skills when:

```text id="q9tx2l"
triggers overlap heavily

procedures duplicate each other

one skill always invokes the other

agents struggle to decide which to use
```

Example:

```text id="10waw5"
csv-import

tsv-import

pipe-delimited-import
```

may become:

```text id="enqv7m"
delimited-file-import
```

with format parameters.

---

# 21. Skill Dependency

A skill may invoke another skill.

Example:

```text id="vsbihr"
database-migration
    ↓
mirror-audit
```

then later:

```text id="gwno8e"
red-team
```

Reference the skill.

Do not paste the entire dependency into the current file.

---

# 22. Avoid Circular Skill Dependencies

Bad:

```text id="xcnqph"
Skill A → Skill B

Skill B → Skill A
```

If this appears, extract shared behavior.

Possible solution:

```text id="c9qkwr"
COMMON SKILL
```

or a root workflow rule.

---

# 23. Skill Status

Use:

```text id="8c99ju"
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

```text id="7zs70k"
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:

```text id="77p8of"
NORMAL CASE

SECOND DIFFERENT CASE
```

When relevant also test:

```text id="r4s14u"
FAILURE CASE

COUNTEREXAMPLE
```

The counterexample checks that the trigger does not activate incorrectly.

---

# 26. Normal Case

Use a realistic expected input.

Verify:

```text id="0cx1pz"
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:

```text id="0j4j90"
deployment package missing
```

Verify that the skill:

```text id="qwgw20"
stops safely

reports the failure

does not continue into destructive steps
```

---

# 29. Counterexample

Use a task that should NOT activate the skill.

Example:

Skill:

```text id="cwra7u"
iis-deployment
```

Counterexample:

```text id="asr05y"
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:

```text id="d089rl"
.ai/skills/system-audit/SKILL.md
```

Check:

```text id="bxqb92"
authority

scope

conflicts

duplication

references

behavior

regression

bloat
```

---

# 31. Versioning

Use semantic-style versions.

```text id="fj9wth"
MAJOR.MINOR.PATCH
```

---

# 32. PATCH Changes

Examples:

```text id="07rmoc"
wording clarification

missing check

better example

minor failure-handling correction
```

Example:

```text id="kdjv4s"
1.0.0 → 1.0.1
```

---

# 33. MINOR Changes

Examples:

```text id="wey4wf"
new procedure branch

new supported scenario

new verification method

new non-breaking output
```

Example:

```text id="jqkcqe"
1.0.1 → 1.1.0
```

---

# 34. MAJOR Changes

Examples:

```text id="ieuw3g"
trigger changes incompatibly

skill changes purpose

output contract changes incompatibly

procedure is fundamentally redesigned
```

Example:

```text id="tns93g"
1.4.2 → 2.0.0
```

---

# 35. Skill Changelog

Each skill should maintain a short local changelog.

Example:

```text id="omub4c"
## 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:

```text id="dfrywv"
.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:

```text id="zmwrsv"
WHAT OBSERVATION JUSTIFIES THIS?
```

Possible evidence:

```text id="si9qcv"
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:

```text id="o76469"
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:

```text id="suy546"
NUMBER OF SKILLS
```

It is judged by:

```text id="j7926d"
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:

```text id="4r36cv"
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:

```text id="mi2d6x"
SKILL.md

examples/

templates/

scripts/

tests/

references/
```

Example:

```text id="rmz0rv"
.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:

```text id="5lz426"
## 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:

```text id="746fqy"
tests

examples

templates

prompts

validation scripts
```

But every new file should answer:

```text id="8ns177"
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:

```text id="saqyxc"
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:

```text id="vw1rmt"
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:

```text id="15ia0l"
mirror-audit

red-team

prompt-debugger

retrospective
```

Keep generic skills portable.

---

# 47. Deprecation Procedure

When deprecating:

```text id="u250wu"
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:

```text id="hoyqgv"
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:

```text id="ax92h5"
[ ] 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:

```text id="6sqwui"
SKILL NAME

PURPOSE

TRIGGER

FULL SKILL FILE

TEST SCENARIOS

VERSION

CHANGELOG UPDATE
```

When revising a skill, produce or apply:

```text id="4nwip5"
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