AI_AGENT_OS/.ai/templates/SKILL_TEMPLATE.md,

# [Skill Name]

Version: 0.1.0
Status: CANDIDATE

## Purpose

Describe the reusable job this skill performs.

A good purpose answers:

```text
What class of problem does this skill solve?
```

Keep the purpose specific.

Avoid vague purposes such as:

```text
"Help with development."
```

Prefer:

```text
"Safely import delimited text files into Microsoft Access while validating schema, row counts, errors, and rollback conditions."
```

---

# 1. Trigger Conditions

Use this skill when:

* [trigger]
* [trigger]
* [trigger]

Do not use this skill when:

* [non-trigger]
* [non-trigger]

Trigger conditions should make it obvious when an agent should load the skill.

---

# 2. Inputs

Required inputs:

```text
INPUT 1:
Description

INPUT 2:
Description
```

Optional inputs:

```text
OPTIONAL INPUT 1:
Description
```

If an input can be discovered from the project, inspect the project before asking the user.

---

# 3. Preconditions

Before executing this skill, verify:

```text
[ ] required inputs exist

[ ] relevant project instructions have been read

[ ] required tools or dependencies are available

[ ] destructive actions have appropriate safeguards

[ ] assumptions are documented
```

Add domain-specific preconditions when necessary.

---

# 4. Output Contract

The skill should produce:

```text
OUTPUT 1

OUTPUT 2

OUTPUT 3
```

Define what success looks like.

Avoid vague output descriptions such as:

```text
"Provide a good solution."
```

Prefer:

```text
"Produce a verified PowerShell script, list required permissions, provide rollback steps, and report the exact verification commands used."
```

---

# 5. Procedure

Follow this process.

## Step 1 — Discover

Inspect:

* relevant files
* existing implementations
* configuration
* dependencies
* tests
* documentation

Do not assume project facts that can be discovered.

---

## Step 2 — Understand

Identify:

```text
OBJECTIVE

CURRENT STATE

DESIRED STATE

CONSTRAINTS

DEPENDENCIES

RISKS
```

---

## Step 3 — Execute

Describe the reusable procedure.

Example:

```text
1. validate input
2. inspect destination
3. prepare change
4. execute change
5. capture result
6. verify
```

Keep steps concrete and executable.

---

## Step 4 — Verify

Define verification methods.

Prefer:

```text
automated test

build

static analysis

query

command output

row-count comparison

smoke test

direct inspection
```

A skill without verification is incomplete.

---

## Step 5 — Handle Failure

If verification fails:

```text
STOP

CAPTURE ERROR

IDENTIFY FAILURE POINT

DIAGNOSE

CORRECT ROOT CAUSE

RETRY VERIFICATION
```

Do not continue as though the operation succeeded.

---

# 6. Decision Rules

Add decision rules when the procedure contains branches.

Example:

```text
IF destination exists
    inspect compatibility

IF destination does not exist
    create it

IF schema differs
    stop and reconcile mapping

IF import errors occur
    capture rejected rows
```

Prefer explicit decisions over vague instructions.

---

# 7. Safety Rules

Document any important safety boundaries.

Examples:

```text
do not delete source data before verification

do not overwrite production configuration without backup

do not log secrets

do not disable security controls to make a procedure work

do not perform destructive migration without rollback
```

Remove this section if the skill has no meaningful safety considerations.

---

# 8. Failure Handling

Known failure classes:

## Failure Type 1

Symptoms:

```text
...
```

Likely cause:

```text
...
```

Response:

```text
...
```

---

## Failure Type 2

Symptoms:

```text
...
```

Likely cause:

```text
...
```

Response:

```text
...
```

Do not attempt to list every theoretical failure.

Document recurring or high-impact failures.

---

# 9. Verification Checklist

Before considering this skill complete:

```text
[ ] required inputs validated

[ ] procedure completed

[ ] output exists

[ ] expected behavior verified

[ ] errors checked

[ ] regressions considered

[ ] destructive changes validated

[ ] result communicated clearly
```

Customize this checklist for the skill.

---

# 10. Examples

## Example 1 — Normal Case

### Input

```text
...
```

### Process

```text
...
```

### Expected Output

```text
...
```

---

## Example 2 — Edge Case

### Input

```text
...
```

### Expected Handling

```text
...
```

Examples are optional when the procedure is already obvious.

They are strongly recommended for complex skills.

---

# 11. Interaction Rules

Specify whether this skill should:

```text
run autonomously

ask questions

pause before destructive action

operate interactively

produce a complete result
```

Example:

```text
Ask only when a critical variable cannot be discovered.

Do not ask for confirmation for reversible low-risk steps.

Require explicit user approval before destructive production changes.
```

---

# 12. Tool Guidance

If the skill commonly uses specific tools, describe them here.

Example:

```text
Prefer repository search before broad file reads.

Use build/test tools when available.

Use database queries to validate imported row counts.

Use version-control diff inspection before completion.
```

Do not hard-code tools unless they are truly part of the skill.

---

# 13. Related Skills

Related skills:

```text
.ai/skills/[skill]/SKILL.md
```

Use related skills rather than duplicating their full procedures.

Example:

```text
Use mirror-audit before high-risk implementation.

Use red-team after verification.

Use retrospective after substantial work.
```

---

# 14. Self-Improvement Rules

This skill may be improved when:

```text
a recurring failure is discovered

a step is repeatedly unclear

a better verification method is found

a project pattern becomes reusable

the procedure produces unnecessary work
```

Before changing this skill:

```text
1. capture evidence
2. identify the failure or improvement
3. make the smallest useful edit
4. test the revised procedure
5. update the version
6. update this changelog
7. update .ai/CHANGELOG.md when appropriate
```

Do not expand the skill based only on speculative edge cases.

---

# 15. Versioning

Use:

```text
PATCH
```

for:

* clarification
* typo
* small missing check

Use:

```text
MINOR
```

for:

* new behavior
* new procedure branch
* new verification method

Use:

```text
MAJOR
```

when:

* purpose changes
* trigger changes incompatibly
* output contract changes incompatibly
* the skill is fundamentally redesigned

---

# 16. Changelog

## 0.1.0

Initial candidate skill.

### Evidence

[What real work justified creating this skill?]

### Verification

[How was the skill tested?]

### Result

PENDING