Evolution

Name: Evolution
Author: dwsy

dwsy/agent

11 installs
17 repo stars
Updated July 25, 2026
dwsy/agent

Lets a Pi Agent self-improve by capturing learnings, correcting skill errors, and validating docs via hooks.

About

A skill that lets a Pi Agent continuously self-improve: it hooks into tool results and session events to capture reusable patterns, detect when skill advice causes errors, and validate that skill content stays accurate, routing updates through issues and pull requests. A solo builder reaches for it to keep their agent's skill library sharpening itself over time.

Captures reusable patterns during development
Auto-detects and fixes faulty skill advice
Hooks-driven self-validation of skill content

Evolution by the numbers

11 all-time installs (skills.sh)
Ranked #508 of 781 Skill Development skills by installs in the Skillselion catalog
Data as of Jul 29, 2026 (Skillselion catalog sync)

npx skills add https://github.com/dwsy/agent --skill evolution

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/dwsy/agent/evolution.svg)](https://skillselion.com/skills/dwsy/agent/evolution)

Installs	11
repo stars	★ 17
Last updated	July 25, 2026
Repository	dwsy/agent ↗

What it does

Lets a Pi Agent self-improve by capturing learnings, correcting skill errors, and validating docs via hooks.

Who is it for?

Builders maintaining an evolving agent skill library

Skip if: One-off scripts with no agent framework

Files

SKILL.mdMarkdownGitHub ↗

Evolution Skill

This skill enables Pi Agent to self-improve continuously during development by capturing learnings, correcting errors, and validating skills.

Quick Navigation

Topic	Description
Hooks Integration	Auto-trigger evolution with Pi Agent hooks
When to Evolve	Triggers and classification
Evolution Process	Step-by-step guide
Self-Correction	Auto-fix skill errors
Self-Validation	Verify skill accuracy
Workhub Integration	Issue/PR management

---

Hooks Integration

Evolution uses Pi Agent's hooks system to automatically detect opportunities for improvement.

Hook Installation

Create or edit ~/.pi/hooks/evolution.ts:

import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";

export default function (api: HookAPI) {
  // Monitor tool results for error detection
  api.on("tool_result", async (event, ctx) => {
    if (event.tool === "bash") {
      await detectErrorPatterns(event, ctx);
    }
  });

  // Monitor session end for learning capture
  api.on("session", async (event, ctx) => {
    if (event.reason === "shutdown") {
      await promptLearningCapture(ctx);
    }
  });

  // Monitor context for new patterns
  api.on("context", async (event, ctx) => {
    await detectNewPatterns(event, ctx);
  });
}

What Hooks Do

Hook Event	Trigger	Action
`tool_result`	After bash command	Detect compilation errors, suggest fixes
`session` (shutdown)	Session ends	Prompt to capture learnings
`context`	Context transformation	Analyze for new patterns

---

When to Evolve

Trigger skill evolution when any of these occur during development:

Trigger	Target Skill	Priority
New coding pattern discovered	Relevant skill	High
Error/debug solution found	troubleshooting skill	High
API usage pattern learned	core/reference skill	High
Build/packaging issue resolved	deployment skill	Medium
Project structure insight	getting-started skill	Low
Core concept clarified	core skill	Low

---

Evolution Process

Step 1: Identify Knowledge Worth Capturing

Ask yourself:

Is this a reusable pattern? (not project-specific)
Did it take significant effort to figure out?
Would it help other developers using Pi Agent?
Is it not already documented in existing skills?

Step 2: Classify the Knowledge

Coding Pattern           → relevant skill (e.g., typescript, patterns)
Error/Debug Solution     → troubleshooting skill
API Usage Pattern        → core/reference skill
Build/Deploy Issue       → deployment skill
Project Structure        → getting-started skill
Core Concept/API         → core skill

Step 3: Use Workhub to Create Issue

# From project root directory
cd /path/to/project
bun ~/.pi/agent/skills/workhub/lib.ts create issue "evolution: add new pattern" [category]

Step 4: Format the Contribution

For Patterns:

## Pattern N: [Pattern Name]

Brief description of what this pattern solves.

### Implementation
\`\`\`typescript
// TypeScript code
\`\`\`

### Usage
\`\`\`typescript
// Example usage
\`\`\`

For Troubleshooting:

### [Error Type/Message]

**Symptom**: What the developer sees

**Cause**: Why this happens

**Solution**:
\`\`\`typescript
// Fixed code
\`\`\`

Step 5: Mark Evolution

Add an evolution marker above new content:

<!-- Evolution: YYYY-MM-DD | source: project-name | author: @user -->

Step 6: Submit via Workhub PR

# Create PR for your contribution
bun ~/.pi/agent/skills/workhub/lib.ts create pr "evolution: add new pattern" [category]

---

Self-Correction

When skill content causes errors, automatically correct it.

Trigger Conditions

User follows skill advice → Code fails to compile/run
                      ↓
                 Detect error
                      ↓
         Suggest correction to user
                      ↓
         Create workhub issue with fix

Correction Flow

1. Detect - Skill advice led to an error 2. Verify - Confirm the skill content is wrong 3. Suggest - Propose fix to user 4. Create Issue - Document in workhub

Correction Marker Format

<!-- Correction: YYYY-MM-DD | was: [old advice] | reason: [why it was wrong] -->

---

Self-Validation

Periodically verify skill content is still accurate.

Validation Checklist

## Validation Report

### Code Examples
- [ ] All TypeScript code compiles
- [ ] All patterns work as documented
- [ ] All examples are up-to-date

### API Accuracy
- [ ] API references are correct
- [ ] Method signatures are accurate
- [ ] Dependencies are current

### Documentation
- [ ] Instructions are clear
- [ ] Examples are complete
- [ ] Links are valid

Validation Prompt

"Please validate skills against current Pi Agent version and dependencies"

---

Workhub Integration

Evolution skill extends workhub for documentation management.

Creating Evolution Issues

# From project root
bun ~/.pi/agent/skills/workhub/lib.ts create issue "evolution: [description]" "evolution"

Issue Template

# Evolution: [Title]

## Type
- [ ] New pattern
- [ ] Error fix
- [ ] API update
- [ ] Documentation improvement

## Source
- Project: [project-name]
- File: [file-path]
- Context: [brief description]

## Content
[Detailed content to add]

## Target Skill
[Which skill should this be added to?]

## Validation
- [ ] Code tested
- [ ] Documentation updated
- [ ] Examples verified

Creating Evolution PRs

# From project root
bun ~/.pi/agent/skills/workhub/lib.ts create pr "evolution: [description]" "evolution"

PR Template

# Evolution: [Title]

## Related Issue
#issue-number

## Changes
- [ ] Added new content
- [ ] Updated existing content
- [ ] Fixed errors
- [ ] Updated examples

## Files Changed
- [file1.md]
- [file2.md]

## Testing
- [ ] Tested locally
- [ ] Verified accuracy
- [ ] Checked for side effects

---

Auto-Evolution Prompts

Use these prompts to trigger self-evolution:

After Solving a Problem

"This solution should be added to skills for future reference. Use workhub to create an evolution issue."

After Creating a Pattern

"This pattern is reusable. Let me create an evolution issue to document it."

After Debugging

"This error and its fix should be documented. Create an evolution issue in workhub."

After Completing a Feature

"Review what I learned and create evolution issues if applicable."

---

Quality Guidelines

DO Add

Generic, reusable patterns
Common errors with clear solutions
Well-tested code examples
Platform-specific gotchas
Performance optimizations
TypeScript/JavaScript best practices

DON'T Add

Project-specific code
Unverified solutions
Duplicate content
Incomplete examples
Personal preferences without rationale

---

Continuous Improvement Checklist

After each development session, consider:

[ ] Did I discover a new coding pattern?
[ ] Did I solve a tricky error?
[ ] Did I find a better way to structure code?
[ ] Did I learn something about TypeScript/JavaScript?
[ ] Did I encounter and fix a confusing issue?
[ ] Would any of this help other developers?

If yes to any, use workhub to create an evolution issue!

---

References

Quick Start Guide

Verify Installation

# Check evolution skill
ls -la ~/.pi/agent/skills/evolution/SKILL.md

# Check evolution hook
ls -la ~/.pi/hooks/evolution.ts

# Check workhub dependency
ls -la ~/.pi/agent/skills/workhub/SKILL.md

Test Hook

Start a Pi Agent session and trigger an error:

pi
# Inside session:
# Run a command that will fail, e.g.:
# ts-node nonexistent.ts

The hook should detect the error and prompt to document it.

Manual Evolution

Create Issue

cd /path/to/project
bun ~/.pi/agent/skills/workhub/lib.ts create issue "evolution: new pattern" "evolution"

Create PR

cd /path/to/project
bun ~/.pi/agent/skills/workhub/lib.ts create pr "evolution: update skill" "evolution"

Common Commands

# View evolution skill
cat ~/.pi/agent/skills/evolution/SKILL.md

# View README
cat ~/.pi/agent/skills/evolution/README.md

# Check hook
cat ~/.pi/hooks/evolution.ts

# Use workhub integration
cd ~/.pi/agent/skills/evolution/workhub-integration
bun lib.ts --help

Evolution Markers

<!-- Evolution: 2025-01-15 | source: project-name | author: @user -->
<!-- Correction: 2025-01-15 | was: [old advice] | reason: [why] -->
<!-- Validation: 2025-01-15 | status: passed | version: 0.1.0 -->

Workflow Summary

1. Detect → Hook detects error/pattern 2. Confirm → System prompts for confirmation 3. Document → Create workhub issue 4. Implement → Update skill with fix/pattern 5. Submit → Create workhub PR 6. Validate → Verify changes work correctly

Next Steps

Read SKILL.md for detailed documentation
Read README.md for setup guide
Review templates for examples
Test the hook in a real session

Evolution Skill - Setup Guide

Overview

The Evolution skill enables Pi Agent to self-improve by capturing learnings, correcting errors, and validating skills through a semi-automated workflow integrated with workhub.

Installation

1. Verify Directory Structure

Ensure the following structure exists:

~/.pi/agent/skills/evolution/
├── SKILL.md
├── README.md
└── workhub-integration/
    ├── lib.ts
    └── templates/
        ├── issue-template.md
        └── pr-template.md

2. Install Hook

The evolution hook should already be installed at ~/.pi/hooks/evolution.ts.

Verify it exists:

ls -la ~/.pi/hooks/evolution.ts

3. Verify Workhub Dependency

Ensure workhub skill is installed:

ls -la ~/.pi/agent/skills/workhub/SKILL.md

If not installed, install it first.

Usage

Automatic Detection

The evolution hook automatically detects:

1. Compilation Errors: TypeScript/JavaScript errors in bash output 2. Session End: Prompts to capture learnings when session ends 3. Pattern Detection: Identifies potential new patterns in context

Manual Evolution

Create evolution issues manually:

# From project root
cd /path/to/project
bun ~/.pi/agent/skills/workhub/lib.ts create issue "evolution: new pattern" "evolution"

Using Workhub Integration

Use the helper scripts:

cd ~/.pi/agent/skills/evolution/workhub-integration

# Create issue
bun lib.ts create-issue --title "Fix TypeScript error" --content "$(cat issue.md)"

# Create PR
bun lib.ts create-pr --title "Update skill" --issue "123" --changes "Added pattern,Fixed error"

Workflow

1. Detect Opportunity

The hook detects:

❌ Compilation errors
💡 New patterns
📚 Learnings at session end

2. User Confirmation

The system asks:

"Document this error and solution?"
"Did you discover any new patterns?"

3. Create Workhub Issue

If confirmed, the system:

Formats the content
Prompts you to create workhub issue
Saves content to temp file

4. Implement Change

You:

Update the skill file
Add evolution marker
Test the changes

5. Create PR

Submit via workhub:

bun ~/.pi/agent/skills/workhub/lib.ts create pr "evolution: update" "evolution"

Evolution Markers

Always add markers to track evolution:

<!-- Evolution: YYYY-MM-DD | source: project-name | author: @user -->
<!-- Correction: YYYY-MM-DD | was: [old advice] | reason: [why] -->
<!-- Validation: YYYY-MM-DD | status: passed | version: 0.1.0 -->

Quality Guidelines

DO Add

✅ Generic, reusable patterns
✅ Common errors with clear solutions
✅ Well-tested code examples
✅ TypeScript/JavaScript best practices
✅ Performance optimizations

DON'T Add

❌ Project-specific code
❌ Unverified solutions
❌ Duplicate content
❌ Incomplete examples
❌ Personal preferences without rationale

Validation

Periodically validate skills:

## Validation Report

### Code Examples
- [ ] All TypeScript code compiles
- [ ] All patterns work as documented

### API Accuracy
- [ ] API references are correct
- [ ] Method signatures are accurate

### Documentation
- [ ] Instructions are clear
- [ ] Examples are complete

Troubleshooting

Hook Not Triggering

1. Verify hook is installed:

   ls -la ~/.pi/hooks/evolution.ts

2. Check Pi Agent settings:

   cat ~/.pi/agent/settings.json

3. Restart Pi Agent session

Workhub Issues Not Creating

1. Verify workhub is installed:

   ls -la ~/.pi/agent/skills/workhub/SKILL.md

2. Check you're in project root:

pwd

3. Run manually:

   bun ~/.pi/agent/skills/workhub/lib.ts create issue "test" "evolution"

Temp Files Not Found

Temp files are saved to /tmp/evolution-*.md:

ls -la /tmp/evolution-*.md

Examples

Example 1: Documenting an Error Fix

1. Hook detects error 2. System prompts: "Document this error and solution?" 3. You confirm and enter solution 4. System provides command to create issue 5. You execute command 6. Update skill with fix 7. Add marker: 

Example 2: Capturing a New Pattern

1. At session end, system prompts: "Did you discover any new patterns?" 2. You describe the pattern 3. System provides command to create issue 4. You execute command 5. Add pattern to relevant skill 6. Add marker: 

Integration with Workhub

The evolution skill extends workhub:

Issues: Track evolution items
PRs: Submit evolution changes
Categories: Use "evolution" category
Templates: Use provided templates

Support

For issues or questions:

1. Check SKILL.md for detailed documentation 2. Review workhub skill documentation 3. Check hook logs in Pi Agent session

Contributing

To improve the evolution skill:

1. Create evolution issue 2. Propose changes 3. Submit PR 4. Add evolution marker

---

Version: 1.0.0 Last Updated: 2025-01-15 Author: Pi Agent System

#!/usr/bin/env bash
# Evolution Skill Installation Verification Script

set -e

echo "🔍 Evolution Skill Installation Verification"
echo "============================================"
echo ""

# Colors
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Check function
check() {
  if [ -f "$1" ] || [ -d "$1" ]; then
    echo -e "${GREEN}✅${NC} $1"
    return 0
  else
    echo -e "${RED}❌${NC} $1"
    return 1
  fi
}

# Check evolution skill
echo "1. Checking Evolution Skill Files..."
check ~/.pi/agent/skills/evolution/SKILL.md
check ~/.pi/agent/skills/evolution/README.md
check ~/.pi/agent/skills/evolution/QUICKSTART.md
check ~/.pi/agent/skills/evolution/workhub-integration/lib.ts
check ~/.pi/agent/skills/evolution/workhub-integration/templates/issue-template.md
check ~/.pi/agent/skills/evolution/workhub-integration/templates/pr-template.md
echo ""

# Check evolution hook
echo "2. Checking Evolution Hook..."
check ~/.pi/hooks/evolution.ts
echo ""

# Check workhub dependency
echo "3. Checking Workhub Dependency..."
check ~/.pi/agent/skills/workhub/SKILL.md
echo ""

# Verify file contents
echo "4. Verifying File Contents..."

# Check SKILL.md has required sections
if grep -q "Hooks Integration" ~/.pi/agent/skills/evolution/SKILL.md; then
  echo -e "${GREEN}✅${NC} SKILL.md has Hooks Integration section"
else
  echo -e "${RED}❌${NC} SKILL.md missing Hooks Integration section"
fi

# Check hook exports default function
if grep -q "export default function" ~/.pi/hooks/evolution.ts; then
  echo -e "${GREEN}✅${NC} Hook exports default function"
else
  echo -e "${RED}❌${NC} Hook missing default export"
fi

# Check workhub integration lib
if grep -q "createEvolutionIssue" ~/.pi/agent/skills/evolution/workhub-integration/lib.ts; then
  echo -e "${GREEN}✅${NC} Workhub integration has createEvolutionIssue function"
else
  echo -e "${RED}❌${NC} Workhub integration missing createEvolutionIssue function"
fi

echo ""

# Test workhub integration
echo "5. Testing Workhub Integration..."
cd ~/.pi/agent/skills/evolution/workhub-integration

if command -v bun &> /dev/null; then
  if bun lib.ts --help &> /dev/null; then
    echo -e "${GREEN}✅${NC} Workhub integration lib.ts is executable"
  else
    echo -e "${YELLOW}⚠️${NC}  Workhub integration lib.ts has errors (run 'bun lib.ts --help' to see details)"
  fi
else
  echo -e "${YELLOW}⚠️${NC}  Bun not installed, skipping execution test"
fi

echo ""

# Summary
echo "============================================"
echo "✅ Installation Complete!"
echo ""
echo "Next Steps:"
echo "  1. Read the quick start guide:"
echo "     cat ~/.pi/agent/skills/evolution/QUICKSTART.md"
echo ""
echo "  2. Start a Pi Agent session to test the hook:"
echo "     pi"
echo ""
echo "  3. Create a manual evolution issue:"
echo "     cd /path/to/project"
echo "     bun ~/.pi/agent/skills/workhub/lib.ts create issue \"test\" \"evolution\""
echo ""
echo "For detailed documentation:"
echo "  cat ~/.pi/agent/skills/evolution/README.md"
echo "  cat ~/.pi/agent/skills/evolution/SKILL.md"
echo "============================================"

#!/usr/bin/env bun
/**
 * Evolution Workhub Integration
 * Helper scripts for creating evolution issues and PRs
 */

import { readFileSync, writeFileSync, existsSync } from "fs";
import { join } from "path";

const WORKHUB_PATH = "~/.pi/agent/skills/workhub/lib.ts";

/**
 * Create an evolution issue
 */
async function createEvolutionIssue(options: {
  title: string;
  content: string;
  category?: string;
}) {
  const { title, content, category = "evolution" } = options;

  // Create temp file for content
  const tempFile = `/tmp/evolution-issue-${Date.now()}.md`;
  writeFileSync(tempFile, content, "utf-8");

  try {
    // Run workhub create issue command
    const command = `bun ${WORKHUB_PATH} create issue "${title}" "${category}"`;
    console.log(`\n📝 Creating evolution issue...`);
    console.log(`📋 Title: ${title}`);
    console.log(`📂 Category: ${category}\n`);

    // Note: This would need to be executed by the user
    console.log(`\n🔧 Execute manually:\n`);
    console.log(`  cd $(pwd)`);
    console.log(`  ${command}`);
    console.log(`\n📄 Content saved to: ${tempFile}`);

    return tempFile;
  } catch (error) {
    console.error(`❌ Failed to create issue:`, error);
    throw error;
  }
}

/**
 * Create an evolution PR
 */
async function createEvolutionPR(options: {
  title: string;
  issueId?: string;
  changes: string[];
  category?: string;
}) {
  const { title, issueId, changes, category = "evolution" } = options;

  const content = formatPRContent({ title, issueId, changes });

  // Create temp file for content
  const tempFile = `/tmp/evolution-pr-${Date.now()}.md`;
  writeFileSync(tempFile, content, "utf-8");

  try {
    const command = `bun ${WORKHUB_PATH} create pr "${title}" "${category}"`;
    console.log(`\n📝 Creating evolution PR...`);
    console.log(`📋 Title: ${title}`);
    console.log(`🔗 Issue: #${issueId || "N/A"}`);
    console.log(`📂 Category: ${category}\n`);

    console.log(`\n🔧 Execute manually:\n`);
    console.log(`  cd $(pwd)`);
    console.log(`  ${command}`);
    console.log(`\n📄 Content saved to: ${tempFile}`);

    return tempFile;
  } catch (error) {
    console.error(`❌ Failed to create PR:`, error);
    throw error;
  }
}

/**
 * Format PR content
 */
function formatPRContent(options: {
  title: string;
  issueId?: string;
  changes: string[];
}): string {
  const { title, issueId, changes } = options;
  const date = new Date().toISOString().split('T')[0];

  let content = `# Evolution: ${title}\n\n`;
  content += `<!-- Evolution: ${date} -->\n\n`;

  if (issueId) {
    content += `## Related Issue\n#${issueId}\n\n`;
  }

  content += `## Changes\n`;
  changes.forEach(change => {
    content += `- [x] ${change}\n`;
  });
  content += `\n`;

  content += `## Files Changed\n`;
  content += `<!-- List modified files -->\n\n`;

  content += `## Testing\n`;
  content += `- [ ] Tested locally\n`;
  content += `- [ ] Verified accuracy\n`;
  content += `- [ ] Checked for side effects\n`;

  return content;
}

/**
 * Parse command line arguments
 */
function parseArgs(args: string[]) {
  const command = args[0];
  const options: Record<string, string> = {};

  for (let i = 1; i < args.length; i++) {
    const arg = args[i];
    if (arg.startsWith("--")) {
      const key = arg.slice(2);
      const value = args[++i];
      options[key] = value;
    }
  }

  return { command, options };
}

/**
 * Main entry point
 */
async function main() {
  const args = process.argv.slice(2);
  const { command, options } = parseArgs(args);

  switch (command) {
    case "create-issue":
      await createEvolutionIssue({
        title: options.title || "Evolution Update",
        content: options.content || "Evolution content",
        category: options.category
      });
      break;

    case "create-pr":
      await createEvolutionPR({
        title: options.title || "Evolution PR",
        issueId: options.issue,
        changes: options.changes?.split(",") || [],
        category: options.category
      });
      break;

    case "help":
    default:
      console.log(`
Evolution Workhub Integration

Commands:
  create-issue --title "TITLE" --content "CONTENT" [--category CATEGORY]
    Create an evolution issue in workhub

  create-pr --title "TITLE" [--issue ISSUE_ID] --changes "CHANGE1,CHANGE2" [--category CATEGORY]
    Create an evolution PR in workhub

Examples:
  bun lib.ts create-issue --title "Fix TypeScript error" --content "$(cat issue.md)"
  bun lib.ts create-pr --title "Update skill" --issue "123" --changes "Added pattern,Fixed error"
      `);
  }
}

// Run if executed directly
if (import.meta.main) {
  main().catch(console.error);
}

export { createEvolutionIssue, createEvolutionPR };

Related skills

Find SkillsSo their agent can intelligently recommend and install the right modular skills from the open ecosystem when they ask how to do something.3M27.9k

Lark Skill MakerRapidly create custom skills for Lark (Feishu) that can be invoked by their AI agents and automation workflows.513k

Skill CreatorGenerate, test, and iterate on new reusable agent skills directly inside their Claude or Cursor workflow.337k166k

BrainstormingTurn vague product ideas into clear, approved designs and specifications through guided collaborative dialogue before writing any code.307k265k

Writing Great SkillsCreate high-quality, reusable agent skills that other developers can discover and install from the Skillselion catalog.290k200k

Find SkillsInstantly surface the best relevant agent skills, MCP servers, and workflows across multiple registries before starting any new project.226k12

Skill Developmentagentsautomation