skill2gep

# skill2gep A generic tool that is NOT tied to any specific agent platform. Input: any procedural Skill document (written for humans). Output: two kinds of GEP assets. The essential distinction (per the GEP protocol definition): | Asset | What it is | Where it comes from | Can be distilled directly from a document? | |---|---|---|---| | **Gene** | Reusable strategy template. Defines "under which signals, do what, avoid what, how to validate" | An abstraction of experience. An empty template | Yes | | **Capsule** | Audit record of one concrete execution (outcome, env_fingerprint, trigger, reference to the Gene used) | Gene + one real execution | **No.** Must start from an existing Gene and run it once to produce a result | This is a hard constraint. Violating it = fabricating a Capsule = destroying the "from validation" foundation of GEP. ## Core principles (non-negotiable) 1. **From validation only**. An unvalidated Gene must not be installed; a Capsule without a real execution must not exist. 2. **Genes serve control density**. Target 200-300 tokens, hard ceiling 500 tokens. If you cannot fit within 500, you are under-splitting the dimensions, not the Gene's fault. 3. **Capsules serve auditability**. Must reference a concrete Gene `id`, must carry a real `outcome`, must carry an `env_fingerprint`. 4. **Failure experience is distilled into `AVOID:` lines**, never mixed into normal strategy steps ("failure warnings only" is the strongest form per Wang et al., *From Procedural Skills to Strategy Genes*, arXiv:2604.15097). 5. **No hallucination**. Every `signals_match`, `strategy` step, and `AVOID` line must trace back to a specific passage in the source document or a real failure record. ## Workflow overview ``` Source Skill document | +-- Phase 1: Read and analyze the source +-- Phase 2: Recall / deduplicate (local + community) +-- Phase 3: Split by dimension, draft candidate Genes (strategy only) +-- Phase 4: Gene local validation (hard gate: schema + dry-run + scenario replay) +-- Phase 5: Install into local Gene pool + record_outcome | +-- [Path A] Gene only: stop here | +-- [Path B] Capsule needed (executable path + audit record): | +-- Phase 6: Pick a real scenario + inject an accepted Gene + execute for real | +-- Phase 7: Capture outcome / blast_radius / env_fingerprint / diff | +-- Phase 8: Assemble the Capsule (type=Capsule, gene=<id>, outcome=...) | +-- Phase 9: Validate the Capsule locally -> write to local Capsule pool | +-- [Optional] Phase 10: Publish to EvoMap community via evolver / EvoMap API ``` By default, produce both Gene and Capsule. Skip one path only when the user explicitly asks for just one kind of asset. --- ## Phase 1: Read and analyze the source Skill Use any file-reading tool to load the Skill document the user points to. Common locations: - Cursor skill: `~/.cursor/skills/<name>/SKILL.md` or `.cursor/skills/<name>/SKILL.md` - Claude / Anthropic skill: project-root `SKILL.md` or `skills/<name>/SKILL.md` - Any procedural document: an explicit path given by the user (a README "Workflow" section counts) Extract the following material (**each item must trace back to a source line**, otherwise it is hallucination): | Material | Which section of the document it comes from | Which Gene field it feeds | |---|---|---| | Trigger scenarios, keywords, error signals | Frontmatter `description`, body "Use when / Scenario / Trigger" | `signals_match` | | Ordered executable steps | Workflow / Quick Start / flow diagram | `strategy` | | Explicit pitfalls, anti-patterns, "do not ..." | Pitfalls / Common Mistakes / AVOID / Anti-Patterns | `strategy` entries starting with `AVOID:` | | Modification scope, forbidden areas | Scope / path constraints / "do not touch ..." | `constraints.max_files`, `constraints.forbidden_paths` | | Executable validation | Validation / Feedback loop / "run xxx to confirm" | `validation` array | | Real cases | Examples / Case Study / user-provided history | Used in Phase 4.3 scenario replay and Phase 6 execution | **If the source has no validation section**: Phase 4 will block. Go back to the user to nail down "exactly what signal proves this Gene worked". Do not paper over it with "manual check" or "looks reasonable". **If the source has no Examples at all**: Path A (Gene only) can still proceed; **Path B (Capsule) must stop** and inform the user "no real scenario available, cannot produce Capsule". --- ## Phase 2: Recall / deduplicate (local + community) Before drafting candidates, query three channels to avoid duplication. Using the `evomap-gep` MCP as the reference implementation: ``` MCP: evomap-gep / gep_list_genes -> local gene pool MCP: evomap-gep / gep_recall -> historical experience MCP: evomap-gep / gep_search_community -> community assets (both Gene and Capsule) ``` If the user runs a different GEP implementation, tool names may differ, but all three semantics must be covered: **local pool + historical events + community pool**. Match policy: - **Exact overlap** (a subset of `signals_match` plus the same strategy backbone): stop this distillation and reply "`<id>` already exists, reuse it". - **Partial overlap**: distill incrementally, only add new signals/strategies, and reference the existing one via `parent_gene: <asset_id>`. - **No overlap**: proceed to Phase 3. --- ## Phase 3: Split by dimension, draft candidate Genes A Skill is almost always a mixture of dimensions (happy path + validation + anti-patterns + scope). The point of splitting is to make each Gene's `signals_match` orthogonal so candidates do not steal each other's triggers. **Common splits** (let the source decide; do not force-fit): | Dimension | Gene `category` | Typical `signals_match` | |---|---|---| | Happy path | `optimize` or `innovate` | task keywords + `normal`, `first_run` | | Error / failure path | `repair` | `log_error`, specific error keywords | | Anti-patterns (AVOID-heavy) | `repair` | `tool_bypass`, specific bad-pattern keywords | | Performance / budget | `optimize` | `perf_bottleneck`, `timeout` | | Release / deployment wrap-up | `optimize` | `deployment_issue`, `release`, `tag` | > The GEP protocol category enum is `repair | optimize | innovate | explore`. > Skills almost always map to the first three (procedural knowledge). `explore` > exists for runtime investigation of uncharted capability space with no > concrete success target — it is valid but rarely the right fit for a > documented skill, so the table above does not suggest it. **Required fields per candidate Gene** (`asset_id` and `schema_version` are filled in automatically at install time): ```json { "type": "Gene", "id": "gene_<domain>_<intent>_<short_noun>", "category": "repair | optimize | innovate | explore", "signals_match": ["..."], "preconditions": ["..."], "strategy": [ "Step 1: ...", "Step 2: ...", "AVOID: <specific wrong action> - must first <corrective action>", "AVOID: ..." ], "constraints": { "max_files": 12, "forbidden_paths": [".git", "node_modules"] }, "validation": [ "<an agent-runnable command returning 0 / non-zero>" ] } ``` **Writing constraints (hard)**: - Every `strategy` / `AVOID` line: one imperative sentence, one action. Do not explain "why" (put rationale in `preconditions`). - `signals_match`: lowercase snake_case. Reuse well-known signals (`log_error`, `perf_bottleneck`, `user_feature_request`, `capability_gap`, `deployment_issue`, `test_failure`, `tool_bypass`) and add domain-specific ones on top. - `validation`: every entry must be "runnable and gives a clear pass/fail". Never write "check whether the output looks reasonable". No-ops like `echo ok`, `true`, `: ` are rejected by the validator. - Estimate tokens per Gene (~= 0.5 token per character). Anything over 500 must be split further. Keep all candidates in memory first. **Do not write to disk yet.** --- ## Phase 4: Gene local validation (hard gate) Three layers. Failing any one forbids Phase 5. ### 4.1 Schema check Run `scripts/validate_gene.js <candidates.json>`. It checks: - All required fields present, `type == "Gene"`, `id` matches `^gene_[a-z0-9_]+$`, no duplicate ids - `category` is one of the enum, `signals_match` non-empty and all snake_case - `strategy` has at least one entry, and at least one `AVOID:` entry (if the source genuinely has no failure experience, the agent must explicitly set the waiver flag) - `constraints.max_files` is a positive integer, `forbidden_paths` is an array - Each `validation` entry looks runnable (a command, not a human instruction; no-ops are rejected) - Estimated tokens ≤ 500 - No private path literals leaked (`/home/<user>`, private repo names, etc.) ### 4.2 Dry-run on declared validation commands The script dry-runs each `validation` entry: - `node scripts/xxx.js` → `node --check` syntax validation + file existence - `npx vitest run <path>` → path existence - `python -m pytest <path>` → path existence - anything else → `bash -n -c` syntax validation Goal: block fake Genes whose `validation` is just a placeholder string. ### 4.3 Scenario replay (semantic validation, done by the agent itself) This step is the soul of "from validation": 1. Pick 1-2 real scenarios from the source Skill's `## Examples` section or from user-provided historical tasks. 2. For each candidate Gene: - Check that at least one `signals_match` entry matches the scenario keywords; otherwise this Gene is irrelevant for this scenario. - Read the `strategy`: if followed literally, does it solve the example? Are any steps contradicted by the example? Are all pitfalls from the example covered by AVOID lines? 3. Mark Genes that fail as `rejected` or `needs_rewrite`. ### 4.4 Produce a validation report ``` gene_id | schema | dry-run | replay | decision gene_uvvis_peak_unit_convert | pass | pass | pass | accept gene_uvvis_find_peaks_misuse | pass | pass | pass | accept gene_uvvis_overview_blah | pass | pass | FAIL(no hit) | reject ``` Only Genes marked `accept` proceed to Phase 5. --- ## Phase 5: Install into the local Gene pool ### 5.1 Recommended: install through MCP / GEP runtime ``` MCP: evomap-gep / gep_install_gene { "gene": { ... full Gene JSON ... } } ``` The runtime fills in `asset_id` (SHA-256 content addressing) and `schema_version`. ### 5.2 Fallback: write the asset file directly (when MCP is unavailable) Append to the GEP runtime's `assets/gep/genes.jsonl` (one JSON object per line). **Do not modify `genes.json` directly** (it is seed data). The exact path depends on the GEP implementation; typically: ``` <evolver or GEP runtime>/assets/gep/ ``` After writing, load the file back with the runtime's loader to confirm it parses. ### 5.3 Record outcome For every Gene successfully persisted, call: ``` MCP: evomap-gep / gep_record_outcome { "geneId": "<new gene id>", "signals": ["skill_distillation", <domain signals from the source>], "status": "success", "score": 0.85, "summary": "Distilled <skill-name> into Gene <gene-id> by <splitting strategy>; validated via <brief validation summary>" } ``` This makes the distillation itself part of the memory graph so it can be recalled later. **Path A ends here.** Stop if the user only asked for Genes. --- ## Path B: Produce a Capsule (executable path + audit record) Prerequisite: Phase 5 produced at least one accepted Gene, and the source has a real executable scenario (or the user supplies one). **Iron rule for Capsules**: a Capsule is not distilled from the document. It is **collected** from the execution of "injecting a Gene into a real task and running it once". If no execution happened, there is no Capsule. Fabricating a Capsule (writing `outcome: success` off the top of your head) destroys GEP's trust foundation. ### Phase 6: Pick a Gene + pick a real scenario + run for real 1. **Pick a Gene**: from the Phase 5 accepted list, pick the one whose `signals_match` overlaps most with the target scenario. 2. **Pick a scenario**: prefer a concrete case from the source Skill's `## Examples` section; otherwise ask the user for a real historical task. **Invented tasks are not accepted.** 3. **Run for real**: execute the Gene's `strategy` step by step in an agent-controlled workspace. This is essentially what the GEP runtime does — if evolver (or an equivalent runtime) is available, let it run; otherwise the agent may run by hand, but must: - Record the actual command sequence (as `execution_trace`) - Run every command in the `validation` array and record each one's exit code and an output tail - Collect the list of modified files and the total changed line count (as `blast_radius`) - Collect an environment fingerprint (OS / Node or Python version / key dependency versions, as `env_fingerprint`) **Absolutely forbidden**: skipping real execution and fabricating an outcome. ### Phase 7: Determine the outcome Fill the following fields from the Phase 6 measurements: | Field | How to fill | |---|---| | `outcome.status` | All `validation` passed → `success`; any failure → `failed` | | `outcome.score` | On `success`, score 0.6 - 1.0 based on pass rate and quality; on `failed`, 0.0 - 0.4 | | `blast_radius.files` | Actual number of modified files | | `blast_radius.lines` | Total added + removed lines | | `success_reason` | On `success`, one sentence explaining why the Gene worked here (≤ 200 chars) | | `env_fingerprint` | `{ "os": "...", "node": "...", "python": "...", "key_deps": {...} }` | **Failed Capsules are valuable too**: they are stored as `failed_capsule` and become input samples for future `repair` Genes. Do not throw them away just because they failed. ### Phase 8: Assemble the Capsule Minimum required fields (aligned with the capsule-generation logic in evolver's `solidify.js`): ```json { "type": "Capsule", "id": "cap_<timestamp>_<short_hash>", "gene": "<accepted gene id from Phase 5>", "trigger": ["<signals that actually fired in this execution>"], "summary": "<one sentence: real result of applying Gene X to scenario Y>", "confidence": 0.0, "blast_radius": { "files": 0, "lines": 0 }, "outcome": { "status": "success | failed", "score": 0.0 }, "success_reason": "<required on success>", "env_fingerprint": { "...": "..." },