evo-asset - SKILL.md Agent Skill

name: evo-asset

description: >

Structure, validate, and locally manage evolution assets (Gene, Capsule, EvolutionEvent).

Use when the user wants to record a solution, document a bug fix, create a Gene or Capsule,

capture an evolution process, or compute an asset_id locally.

No network connection required. Trigger keywords: Gene, Capsule, EvolutionEvent,

evolution asset, asset_id, record solution, save fix, document repair.

evo-asset — Local Evolution Asset Management

This skill helps you structure any solved problem into a Gene + Capsule + EvolutionEvent

bundle, compute content-addressable IDs locally, and validate asset quality — all without

any network connection.

1. Core Concepts

| Term | Definition |

|---|---|

| Gene | A reusable strategy template describing how to approach a class of problems. Captures the abstract pattern (e.g., "retry with backoff"). |

| Capsule | A validated fix or optimization — a concrete implementation of a Gene applied to a specific problem. Captures what was done, confidence level, and scope of change. |

| EvolutionEvent | An audit record of the evolution process. Documents what was tried, how many attempts, and the final outcome. Strongly recommended in every bundle. |

| asset_id | A content-addressable fingerprint: sha256: + SHA256 hash of the asset's canonical JSON (with asset_id field excluded). Uniquely identifies each asset by its content. |

| Bundle | A Gene + Capsule (+ EvolutionEvent) published together. Gene and Capsule must always be paired. |

2. When to Use This Skill

Activate this skill when the user wants to:

Record or document a solution they just implemented
Create a Gene/Capsule/EvolutionEvent structure
Compute a local asset_id for any asset JSON
Validate whether a Capsule meets quality standards
Understand the Gene/Capsule/EvolutionEvent data model

3. Bundle Rules

Gene + Capsule must always be paired — never save a Capsule without its companion Gene.
EvolutionEvent is strongly recommended — always include it as the third element.
Each asset has its own independently computed asset_id.
Asset type values are case-sensitive: "Gene", "Capsule", "EvolutionEvent".
Categories / intents must be one of: repair, optimize, innovate.

4. Gene Structure

A Gene captures the abstract strategy — the why and how of a solution pattern.


{

  "type": "Gene",

  "schema_version": "1.5.0",

  "category": "repair",

  "signals_match": ["TimeoutError", "ECONNREFUSED"],

  "summary": "Retry with exponential backoff on timeout errors",

  "validation": ["node tests/retry.test.js"],

  "asset_id": "sha256:<computed>"

}

|---|---|---|---|

| schema_version | Yes | string | "1.5.0" |

5. Capsule Structure

A Capsule captures the concrete implementation — the what was done with measurable outcomes.


{

  "type": "Capsule",

  "schema_version": "1.5.0",

  "trigger": ["TimeoutError", "ECONNREFUSED"],

  "gene": "sha256:<gene_asset_id>",

  "summary": "Fix API timeout with bounded retry and connection pooling",

  "confidence": 0.85,

  "blast_radius": { "files": 3, "lines": 52 },

  "outcome": { "status": "success", "score": 0.85 },

  "success_streak": 4,

  "env_fingerprint": {

    "node_version": "v22.0.0",

    "platform": "win32",

    "arch": "x64"

  },

  "asset_id": "sha256:<computed>"

}

|---|---|---|---|

| schema_version | Yes | string | "1.5.0" |

| blast_radius | Yes | object | { "files": N, "lines": N } — scope of change |

| outcome | Yes | object | { "status": "success"/"failure", "score": 0–1 } |

| env_fingerprint | Yes | object | { "platform": "...", "arch": "..." } |

6. EvolutionEvent Structure

An EvolutionEvent records the evolution process that produced a Capsule.

Always include it — bundles without it have lower quality scores.


{

  "type": "EvolutionEvent",

  "intent": "repair",

  "capsule_id": "sha256:<capsule_asset_id>",

  "genes_used": ["sha256:<gene_asset_id>"],

  "outcome": { "status": "success", "score": 0.85 },

  "mutations_tried": 3,

  "total_cycles": 5,

  "asset_id": "sha256:<computed>"

}

|---|---|---|---|

| outcome | Yes | object | { "status": "success"/"failure", "score": 0–1 } |

7. Asset ID — Local Computation

Every asset's asset_id is a content-addressable hash computed locally.

Algorithm (language-agnostic)


1. Start with the asset JSON object (dict/object)

2. REMOVE the "asset_id" field if it exists

3. Sort ALL keys at ALL nesting levels alphabetically (canonical JSON)

4. Serialize to a compact string — no extra spaces, no newlines

5. Encode the string as UTF-8 bytes

6. Compute SHA256 of those bytes

7. Output:  "sha256:" + hex_digest

Critical: Keys must be sorted recursively at every level. A difference in key order

produces a different hash and will fail validation.

Using the provided scripts

Node.js:


node scripts/compute_asset_id.js examples/gene_example.json

# Output: sha256:3a7f2c...

Python:


# Linux / macOS

python3 scripts/compute_asset_id.py examples/gene_example.json



# Windows (Python Launcher)

py -3 scripts/compute_asset_id.py examples/gene_example.json



# Output: sha256:3a7f2c...

Both scripts produce identical output for the same input.

8. Capsule Quality Standards

A Capsule passes the local quality check when all of the following hold:

| Check | Requirement |

|---|---|

| Outcome score | outcome.score >= 0.7 |

| Blast radius: files | blast_radius.files > 0 |

| Blast radius: lines | blast_radius.lines > 0 |

| Summary length | summary.length >= 20 |

| Trigger signals | At least 1 signal, each >= 3 chars |

Additional factors that improve quality (not hard requirements):

Smaller blast_radius (more focused fix = higher precision)
Higher success_streak (more repeated successes = more reliable)
Confidence closer to 1.0

9. AI Operation SOP

When this skill is triggered, follow these steps:

Step 1 — Understand the problem

Ask (or infer from context):

What problem was solved? (brief description)
What type? repair (bug fix) / optimize (performance) / innovate (new capability)
What signals/errors triggered it? (e.g., error message, symptom)
How many files/lines were changed?
Did it succeed?

Step 2 — Fill the Gene

Create gene.json (without asset_id):

category = the problem type
signals_match = error keywords or symptom strings
summary = the abstract strategy (≥10 chars)

Compute: node scripts/compute_asset_id.js gene.json → save result as Gene's asset_id.

Step 3 — Fill the Capsule

Create capsule.json (without asset_id):

trigger = same signals as Gene's signals_match
gene = Gene's asset_id from Step 2
summary = what was concretely done (≥20 chars)
confidence = how confident the fix is (0–1)
blast_radius = actual files/lines changed (must be > 0)
outcome.score = effectiveness score (must be ≥0.7 to pass quality)
env_fingerprint = current platform info

Compute: node scripts/compute_asset_id.js capsule.json → save as Capsule's asset_id.

Step 4 — Fill the EvolutionEvent

Create event.json (without asset_id):

intent = same as Gene's category
capsule_id = Capsule's asset_id from Step 3
genes_used = [Gene's asset_id]
mutations_tried = number of approaches attempted
total_cycles = total iterations

Compute: node scripts/compute_asset_id.js event.json → save as EvolutionEvent's asset_id.

Step 5 — Validate & finalize

Run quality checks (Step 8). If passed, assemble the final bundle:


{

  "bundle": [

    { ...gene_with_asset_id... },

    { ...capsule_with_asset_id... },

    { ...event_with_asset_id... }

  ]

}

Save to a local file for archiving. Show the user the filled bundle and quality results.

Quick Reference

| What | How |

|---|---|

| Compute asset_id (Node) | node scripts/compute_asset_id.js <file.json> |

| Compute asset_id (Python/Linux) | python3 scripts/compute_asset_id.py <file.json> |

| Compute asset_id (Python/Win) | py -3 scripts/compute_asset_id.py <file.json> |

| Gene template | examples/gene_example.json |

| Capsule template | examples/capsule_example.json |

| EvolutionEvent template | examples/evolution_event_example.json |

| category/intent values | repair / optimize / innovate |

| Minimum score to pass | outcome.score >= 0.7 |