Skill Se Kit

Skill Self-Evolution Kit (Agent-Native)

1. Overview

This document is the complete operational specification for the Agent-Native Skill Self-Evolution Kit. Any AI agent that reads this file gains the ability to manage self-evolving skills through structured file operations.

Agent-Native paradigm: The agent IS the runtime. There are no external libraries, no daemon processes, no programmatic dependencies. The agent reads JSON files, applies semantic reasoning, makes decisions via decision trees defined here, and writes JSON files. All matching, scoring, and synthesis operations use the agent's native language understanding rather than algorithmic implementations.

Protocol compatibility: All artifacts produced by this kit conform to the Skill Evolution Protocol v1.0.0. Manifests, proposals, and experience records can interoperate with any protocol-compliant system.

Architecture: Dual-loop design inspired by AutoSkill (ECNU ICALK Lab & Shanghai AI Lab) and XSKILL (HKUST, Zhejiang, HUST).

• Left Loop (Execution): Retrieve relevant skills, inject as context, execute task.
• Right Loop (Learning): Extract feedback, record experience, update skill bank.

---

2. Quick Start

1. Initialize workspace (Section 3.1).
2. Execute a task with the Execution Loop (Section 4).
3. After execution, run the Learning Loop (Section 5).
4. On next task, the Execution Loop retrieves accumulated skills automatically.

Minimum viable cycle: init workspace, execute one task, extract one lesson, write one skill entry.

---

3. Workspace

3.1 Initialize New Workspace

Create the following directory structure:

{workspace_root}/
  manifest.json
  skill_bank.json
  experience/
  audit/
  snapshots/

Step 1: Create directories.

experience/
audit/
snapshots/

Step 2: Create manifest.json from this template:

{
  "schema_name": "SkillManifest",
  "schema_version": "1.0.0",
  "protocol_version": "1.0.0",
  "skill_id": "{lowercase-kebab-case-identifier}",
  "name": "{Human Readable Skill Name}",
  "version": "0.1.0",
  "description": "{What this skill does}",
  "governance": {
    "mode": "standalone",
    "official_status": "local"
  },
  "capability": {
    "level": "native",
    "summary": "{Brief capability description}"
  },
  "compatibility": {
    "min_protocol_version": "1.0.0",
    "max_protocol_version": "1.0.0"
  },
  "metadata": {
    "owner": "{owner identifier}",
    "contract": {
      "min_feedback_confidence": 0.35,
      "synthesis_threshold": 15,
      "auto_promote": true,
      "managed_files": [
        {"path": "SKILL.md", "kind": "markdown"}
      ]
    }
  }
}

Step 3: Create skill_bank.json:

{
  "skills": []
}

Step 4: Determine governance mode.

IF the skill operates independently (single agent, personal workspace)
  → Set governance.mode = "standalone"

ELSE IF the skill is part of a multi-agent system or requires approval workflow
  → Set governance.mode = "governed"
  → See Section 6.3 for governed mode behavior

3.2 Resume Existing Workspace

1. Read manifest.json
   IF file is missing or unparseable
     → ABORT. Workspace is corrupt. Re-initialize (Section 3.1).

2. Validate manifest structure:
   - REQUIRED fields: schema_name, skill_id, version, governance.mode
   IF any required field is missing
     → ABORT. Manifest is invalid.

3. Read skill_bank.json
   IF file is missing
     → Create empty skill bank: {"skills": []}
   IF file is unparseable
     → ABORT. Skill bank is corrupt. Restore from latest snapshot (Section 7.2).

4. Verify directory existence: experience/, audit/, snapshots/
   IF any directory is missing
     → Create it.

5. Workspace is ready. Proceed to Execution Loop (Section 4).

---

4. Execution Loop (Left Loop)

Execute Sections 4.1 through 4.3 in sequence for every task.

4.1 Skill Retrieval

1. Read skill_bank.json → extract the skills array.

2. IF skills array is empty
     → Set skill_guidance = "" (empty string)
     → Proceed to Section 4.3

3. FOR each skill entry in the skills array:
     Score the entry against the current task using these signals:
     a. task_signature exact or partial match (highest weight)
     b. keywords overlap with task description
     c. Semantic similarity between skill content and task context

4. Rank all skill entries by relevance score (descending).

5. Select the top N entries where N = min(5, number of entries with non-trivial relevance).
   IF no entries have meaningful relevance
     → Set skill_guidance = "" (empty string)

6. Proceed to Section 4.2 with selected entries.

4.2 Context Injection

Format selected skill entries into a guidance block using this template:

=== Skill Guidance (from evolution history) ===
[1] {title} (v{version})
{content}

[2] {title} (v{version})
{content}

[N] {title} (v{version})
{content}
=== End Skill Guidance ===

Inject this block into the execution context before task processing. The agent treats this as advisory context, not hard constraints.

4.3 Task Execution

Execute the task with the enriched context from Section 4.2. Retain the execution result (output, errors, user responses) in session memory for the Learning Loop.

---

5. Learning Loop (Right Loop)

Execute Sections 5.1 through 5.6 in sequence after task execution completes.

5.1 Feedback Extraction

Apply the following decision tree to extract structured feedback from the execution:

IF explicit user feedback is present
   (user stated: "this worked", "this failed", "the problem was...", "good job on...",
    "这个有效", "这个有问题", "失败原因是...")
  → status   = infer from user statement ("positive" or "negative")
  → lesson   = user's stated insight, normalized to a reusable guideline
  → source   = "explicit"
  → confidence = 0.9

ELSE IF execution produced an error, exception, or observable failure
  → status   = "negative"
  → lesson   = what went wrong and how to avoid it in future executions
  → source   = "execution_result"
  → confidence = 0.7

ELSE IF execution succeeded with observable improvement over previous attempts
  → status   = "positive"
  → lesson   = what worked well and should be repeated
  → source   = "execution_result"
  → confidence = 0.6

ELSE IF user input contains preference markers:
   English: "always", "never", "should", "avoid", "prefer", "make sure", "don't"
   Chinese: "每次都", "必须", "不要", "避免", "优先", "一定要", "千万别"
  → status   = "positive"
  → lesson   = normalized preference statement (rewrite as a directive)
  → source   = "user_input"
  → confidence = 0.8

ELSE
  → status   = "positive"
  → lesson   = "No specific insight extracted. Current approach maintained."
  → source   = "default"
  → confidence = 0.2

The output is a Feedback object: {status, lesson, source, confidence}.

5.2 Confidence Gate

Read manifest.json → metadata.contract.min_feedback_confidence
  IF value is absent → use default: 0.35

IF feedback.confidence  synthesis_threshold
    → ACTION = SYNTHESIZE (applied after the primary action)
    → Compress the content:
        1. Remove exact duplicate bullets
        2. Merge bullets that express the same idea in different words
        3. Abstract specific examples into general patterns where possible
        4. Retain the most general and reusable formulations
    → Bump PATCH version: x.y.z → x.y.(z+1)
    → Updated content should have noticeably fewer bullets than before

Proceed to Section 5.5 with the determined action.

5.5 Mutate Skill Bank

BEFORE any mutation, execute ALL of the following in order:

1. Create snapshot (Section 7.1).
   Reason: "Before {ACTION} on skill entry {skill_entry_id or 'new'}"

2. Read current skill_bank.json.

3. Apply the decided action:
   IF ACTION = ADD
     → Append the new skill entry to the skills array

   IF ACTION = MERGE
     → Find the target skill entry by skill_entry_id
     → Update its content, version, source_experience_ids, updated_at

   IF ACTION = SUPERSEDE
     → Find the target skill entry by skill_entry_id
     → Overwrite its content, version, source_experience_ids, updated_at

   IF ACTION = SYNTHESIZE
     → Find the target skill entry by skill_entry_id
     → Replace its content with the synthesized version
     → Update version, updated_at

4. Write the updated skill_bank.json.

5. Write audit entry (Section 5.6).

5.6 Audit Logging

Write an audit entry for every decision that modifies or intentionally does not modify the skill bank.

Generate the audit entry:

{
  "audit_id": "aud-{12 lowercase hex chars}",
  "created_at": "{current UTC ISO 8601}",
  "event_type": "{see event_type table below}",
  "skill_id": "{from manifest.json skill_id}",
  "subject_id": "{the skill_entry_id or experience_id affected}",
  "actor": "{agent model identifier, e.g., 'claude-opus-4-6'}",
  "details": {
    "action": "{ADD|MERGE|SUPERSEDE|DISCARD|SYNTHESIZE|RECORD|GATE_BLOCKED}",
    "lesson": "{the lesson text}",
    "confidence": 0.0,
    "reasoning": "{why this decision was made}"
  }
}

Event type mapping:

| Action | eventtype | |------------|--------------------| | ADD | skilladded | | MERGE | skillmerged | | SUPERSEDE | skillsuperseded | | DISCARD | skilldiscarded | | SYNTHESIZE | skillsynthesized | | RECORD | experiencerecorded| | GATEBLOCKED | experience_recorded |

Write to file path: audit/{audit_id}.json

---

6. Governance

6.1 Mode Detection

Read manifest.json → governance.mode

IF governance.mode = "standalone"
  → Follow Section 6.2

ELSE IF governance.mode = "governed"
  → Follow Section 6.3

ELSE
  → Default to "standalone"

6.2 Standalone Mode

In standalone mode, the agent has full authority over the skill bank. The Learning Loop (Section 5) executes directly: experience is recorded, skill bank is mutated, and audit entries are written without external approval.

Read manifest.json → metadata.contract.auto_promote

IF auto_promote = true (default)
  → All skill bank mutations apply immediately after snapshot

IF auto_promote = false
  → Write proposed changes to audit/ as a proposal (Section 6.3 format)
  → Apply the mutation immediately afterward
  → The proposal serves as a detailed change record, not a gate

6.3 Governed Mode

In governed mode, skill bank mutations require governor approval. The Learning Loop diverges after Section 5.4 (Skill Update Decision).

Instead of executing Section 5.5 directly:

STEP 1: Create a SkillProposal document.

  {
    "schema_name": "SkillProposal",
    "schema_version": "1.0.0",
    "protocol_version": "1.0.0",
    "proposal_id": "prop-{12 lowercase hex chars}",
    "skill_id": "{from manifest.json skill_id}",
    "created_at": "{current UTC ISO 8601}",
    "proposer": {
      "authority": "local",
      "id": "{agent identifier}"
    },
    "status": "candidate",
    "proposal_type": "{new_skill|skill_update}",
    "base_version": "{current manifest.json version}",
    "target_version": "{version after proposed change}",
    "change_summary": "{description of proposed change}",
    "proposed_action": "{ADD|MERGE|SUPERSEDE|SYNTHESIZE}",
    "proposed_payload": {
      "{the skill entry to add or the updated fields}"
    },
    "artifacts": [
      {
        "type": "evidence",
        "ref": "{experience_id}"
      }
    ]
  }

STEP 2: Write proposal to audit/{proposal_id}.json

STEP 3: Write audit entry.
  event_type = "proposal_created"
  subject_id = "{proposal_id}"
  details.action = "PROPOSE"
  details.reasoning = "Governed mode: awaiting governor decision"

STEP 4: DO NOT mutate skill_bank.json.

STEP 5: When a PromotionDecision document is received:

  IF outcome = "promoted"
    → Create snapshot (Section 7.1)
    → Apply the proposed mutation to skill_bank.json
    → Write audit entry: event_type = "proposal_accepted"

  ELSE IF outcome = "rejected"
    → Write audit entry: event_type = "proposal_rejected"
    → Do not mutate skill_bank.json

  ELSE IF outcome = "deferred"
    → Write audit entry: event_type = "governance_decision", details.action = "DEFERRED"
    → Retain proposal for future processing

---

7. Rollback

7.1 Create Snapshot

MUST be called before every skill bank mutation. No exceptions.

{
  "snapshot_id": "snap-{12 lowercase hex chars}",
  "created_at": "{current UTC ISO 8601}",
  "reason": "{why this snapshot was created}",
  "manifest": {},
  "skill_bank": {}
}

Populate manifest with a complete copy of the current manifest.json contents. Populate skill_bank with a complete copy of the current skill_bank.json contents.

Write to file path: snapshots/{snapshot_id}.json

Write audit entry:

event_type = "snapshot_created"
subject_id = "{snapshot_id}"
details.action = "SNAPSHOT"
details.reasoning = "{reason}"

7.2 Restore from Snapshot

1. Identify the target snapshot.
   IF a specific snapshot_id is provided
     → Read snapshots/{snapshot_id}.json
   ELSE
     → List all files in snapshots/ directory
     → Sort by created_at descending
     → Select the most recent snapshot

2. IF snapshot file is missing or unparseable
     → ABORT. Cannot restore.

3. Overwrite manifest.json with snapshot.manifest

4. Overwrite skill_bank.json with snapshot.skill_bank

5. Write audit entry:
     event_type = "rollback_executed"
     subject_id = "{snapshot_id}"
     details.action = "ROLLBACK"
     details.reasoning = "{why rollback was triggered}"

---

8. File Format Reference

8.1 manifest.json (SkillManifest)

Protocol-compatible skill manifest with embedded evolution contract.

{
  "schema_name": "SkillManifest",
  "schema_version": "1.0.0",
  "protocol_version": "1.0.0",
  "skill_id": "{lowercase-kebab-case, e.g., 'code-review-assistant'}",
  "name": "{Human Readable Name}",
  "version": "0.1.0",
  "description": "{What this skill does}",
  "governance": {
    "mode": "{standalone|governed}",
    "official_status": "local"
  },
  "capability": {
    "level": "native",
    "summary": "{Brief capability description}"
  },
  "compatibility": {
    "min_protocol_version": "1.0.0",
    "max_protocol_version": "1.0.0"
  },
  "metadata": {
    "owner": "{owner identifier}",
    "contract": {
      "min_feedback_confidence": 0.35,
      "synthesis_threshold": 15,
      "auto_promote": true,
      "managed_files": [
        {"path": "SKILL.md", "kind": "markdown"}
      ]
    }
  }
}

Field constraints:

• skill_id: must match pattern ^[a-z0-9][a-z0-9._-]*$
• version: must match pattern ^\d+\.\d+\.\d+$
• governance.mode: one of "standalone", "governed"
• governance.official_status: one of "local", "submitted", "official", "deprecated"

8.2 skill_bank.json (SkillBank)

{
  "skills": [
    {
      "skill_entry_id": "skl-{12 lowercase hex chars}",
      "title": "{one-line summary}",
      "content": "- {bullet 1}\n- {bullet 2}\n- {bullet 3}",
      "version": "0.1.0",
      "task_signature": "{normalized task type}",
      "keywords": ["{keyword1}", "{keyword2}"],
      "source_experience_ids": ["{exp-id-1}", "{exp-id-2}"],
      "updated_at": "{ISO 8601 UTC}"
    }
  ]
}

Field constraints:

• skill_entry_id: must match pattern ^skl-[a-f0-9]{12}$
• title: non-empty string
• content: non-empty string, formatted as markdown bullet list
• version: semver string ^\d+\.\d+\.\d+$
• updated_at: ISO 8601 UTC timestamp ending with Z
• task_signature, keywords, source_experience_ids: optional but recommended

8.3 Experience Item (ExperienceItem)

{
  "experience_id": "exp-{12 lowercase hex chars}",
  "skill_id": "{from manifest.json}",
  "recorded_at": "{ISO 8601 UTC}",
  "task_signature": "{normalized task type}",
  "lesson": "{reusable insight}",

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [d-wwei](https://github.com/d-wwei)
- **Source:** [d-wwei/skill-se-kit](https://github.com/d-wwei/skill-se-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.