skill-library-voyager

name	skill-library-voyager
description	Skill library patterns from Voyager — executable code as skills, semantic retrieval, composition, failure-driven refinement. Maps to Claude Agent SDK skills, skillkit, lifelong learning agents. Sources: rohitg00/ai-engineering-from-scratch (Apache-2.0).

/skill-library-voyager

When to Use

• Agent keeps re-deriving the same capability on every session (token waste)
• Building a lifelong-learning agent that accrues capability over time
• Implementing Claude Agent SDK skill files backed by a retrieval store
• Creating a composable capability library for a multi-agent system

Do NOT use for

• One-shot tasks where skill reuse has no value
• Tasks with highly unique, non-repeatable capabilities
• Simple tool-use patterns where a tool registry ([[react-agent-loop]]) suffices

---

Voyager: three components

1. Automatic curriculum   — curiosity-driven task proposer (bottom-up exploration)
2. Skill library          — executable code keyed on description + embedding
3. Iterative prompting    — on failure: errors + environment feedback → refine skill

Why action space = code: Voyager emits function bodies, not primitive commands. A skill is composable: craftIronPickaxe() calls mineIron(), mineStick(), placeCraftingTable(), craft(). Stored keyed on description + embedding. Loaded as program, not prompt.

---

Skill store

from dataclasses import dataclass, field
import hashlib, json, re

@dataclass
class Skill:
    name: str
    description: str
    code: str
    version: int = 1
    success_count: int = 0
    failure_count: int = 0

    @property
    def id(self) -> str:
        return hashlib.sha256(self.name.encode()).hexdigest()[:8]

    def reliability(self) -> float:
        total = self.success_count + self.failure_count
        return self.success_count / total if total else 0.0

@dataclass
class SkillLibrary:
    skills: dict[str, Skill] = field(default_factory=dict)

    def register(self, name: str, description: str, code: str) -> Skill:
        skill = Skill(name=name, description=description, code=code)
        self.skills[name] = skill
        return skill

    def retrieve(self, query: str, top_k: int = 3) -> list[Skill]:
        """Toy keyword retrieval — replace with embedding cosine similarity."""
        q_words = set(query.lower().split())
        scored = []
        for skill in self.skills.values():
            desc_words = set(skill.description.lower().split())
            overlap = len(q_words & desc_words)
            scored.append((overlap, skill))
        scored.sort(key=lambda x: (-x[0], -x[1].reliability()))
        return [s for _, s in scored[:top_k]]

    def update(self, name: str, new_code: str) -> str:
        if name not in self.skills:
            return f"[error] skill '{name}' not found"
        self.skills[name].code = new_code
        self.skills[name].version += 1
        return f"skill '{name}' updated to v{self.skills[name].version}"

    def record_outcome(self, name: str, success: bool) -> None:
        if name in self.skills:
            if success:
                self.skills[name].success_count += 1
            else:
                self.skills[name].failure_count += 1

---

Iterative prompting — skill refinement on failure

def build_skill_refinement_prompt(
    task: str,
    current_code: str,
    error_output: str,
    env_feedback: str,
) -> str:
    return f"""The following skill failed. Rewrite it to fix the errors.

Task: {task}

Current code:
```python
{current_code}

Execution errors: {error_output}

Environment feedback: {env_feedback}

Write an improved version that handles the failure. Return only the code block."""

---

## Agent using skill library

```python
def agent_with_skills(task: str, library: SkillLibrary, llm, executor) -> str:
    # 1. Retrieve relevant skills
    candidates = library.retrieve(task, top_k=3)
    skill_context = "\n\n".join(
        f"# {s.name} (reliability={s.reliability():.0%})\n{s.description}\n```python\n{s.code}\n```"
        for s in candidates
    )

    # 2. Ask LLM to compose or extend
    prompt = f"""Task: {task}

Available skills:
{skill_context}

Write a solution that composes these skills (or a new skill if none apply).
Return Python code."""
    code = llm(prompt)

    # 3. Execute with iterative refinement (max 3 attempts)
    for attempt in range(3):
        result, error = executor(code)
        if not error:
            # Register as new skill if solution is novel
            skill_name = extract_function_name(code)
            if skill_name and skill_name not in library.skills:
                library.register(skill_name, task, code)
            return result

        # Refine on failure
        refinement_prompt = build_skill_refinement_prompt(task, code, error, result)
        code = llm(refinement_prompt)

    return f"[failed after 3 attempts] last error: {error}"

def extract_function_name(code: str) -> str | None:
    import re
    m = re.search(r'def (\w+)\s*\(', code)
    return m.group(1) if m else None

---

Claude Agent SDK mapping

Voyager skill        → Claude Agent SDK skill file (SKILL.md)
Library registration → /plugin install or skills/ directory scan
Retrieval            → agent reads SKILL.md trigger patterns → loads matching skill
Refinement           → /improve-skill command (human-gated in YAMTAM)
Reliability score    → YAMTAM skill confidence / review_status field

---

Anti-Fake-Pass Checklist

❌ Code skills with side effects stored without sandboxing → a bad skill deletes files
❌ No reliability score → agent uses a skill with 20% success rate as confidently as one with 95%
❌ Unbounded library growth → retrieval quality degrades; add a consolidation / GC pass
❌ Skill registered before testing → new skills must pass at least one successful execution first
❌ Single embedding for description → add code body embedding for retrieval by implementation pattern
❌ No version tracking → bug-fixed skill replaces original silently; can't audit regressions