pi-skill-evolution

Hermes Agent-style automated skill creation and evolution for Pi Agent.

Pi Agent already has a great skills system and extension API, but lacks the closed-loop "auto-create, auto-modify, evolve skills" capability that Hermes Agent achieves through background_review and skill_manage. This repo fills that gap on top of Pi's event-driven architecture.

What it does

Capability	Description
Auto-create skills	After a complex task, the agent saves the workflow as a skill via skill_manage
Auto-patch skills	When an existing skill can be improved, uses patch for minimal, safe edits
Background review loop	After each session, the agent self-audits and decides whether to save/update skills
Progressive disclosure	Only skill names + descriptions sit in the system prompt; full content loads on demand
Usage tracking	Every skill_manage call records usage count + timestamp in .skill-stats.json
Weekly inactive-skill reminder	Every 7 days, Pi reminds you about skills unused for 30+ days
Disable/enable skills	Rename a skill dir to .disabled-<name> so Pi stops discovering it, without deleting it

Files

pi-skill-evolution/
├── README.md                      ← this file (EN)
├── README_ZH.md                   ← 中文说明
├── extensions/
│   └── skill-evolution.ts         ← Pi extension: skill_manage tool + review loop
├── skill-authoring/
│   └── SKILL.md                   ← Skill authoring playbook for the agent
└── LICENSE

Installation

Via npm (recommended)

pi install npm:pi-agent-skill-evolution

This installs the published npm package, which bundles the extension and the authoring skill. Pi auto-discovers both — no settings changes needed.

Browse the package gallery at pi.dev/packages.

Direct copy (lightweight)

# Extension
cp extensions/skill-evolution.ts ~/.pi/agent/extensions/

# Authoring skill (recommended)
mkdir -p ~/.pi/agent/skills/skill-authoring
cp skill-authoring/SKILL.md ~/.pi/agent/skills/skill-authoring/

Pi auto-discovers both — no settings changes needed.

Environment variables

Variable	Default	Description
PI_SKILL_EVOLUTION_DIR	~/.pi/agent/skills/	Directory where skills are stored

How it works

Usage statistics

Every time the LLM calls skill_manage (create, edit, patch, inspect, delete, list), the extension records:

• Count — total number of successful invocations
• lastUsed — ISO timestamp of the most recent successful call
• description — latest description passed (for create/edit)

Data is stored in ~/.pi/agent/skills/.skill-stats.json and persists across sessions.

Weekly inactive-skill reminder

On every session_start, the extension checks:

1. Is the reminder enabled? (default: yes)
2. Has it been ≥ 7 days since the last check?
3. Are there any skills that haven't been used in ≥ 30 days?

If all three pass, Pi sends a follow-up message listing inactive skills with suggestions to disable/remove them. The reminder can be toggled persistently via the /skill-evolution command (see below).

Disable / enable skills

Instead of deleting a skill you may want to keep, you can disable it:

• disable renames <name>/ → .disabled-<name>/, so Pi's skill discovery skips it
• enable renames it back, restoring it to active status
• Disabled skills still appear in stats but are excluded from skill_manage list and the inactive reminder scan

skill_manage tool

The extension registers a skill_manage tool callable by the LLM:

Operation	Required params	What it does
create	skillName, description, content?	Creates a new skill
edit	skillName, description, content	Full rewrite of an existing skill
patch	skillName, find, replace?	Exact find-and-replace inside SKILL.md (preferred — safest)
delete	skillName	Removes a skill
list	—	Lists all available skills
inspect	skillName, content?	Reads current skill content

Skill names are validated per the Agent Skills spec: 1–64 chars, lowercase letters, digits, hyphens only, no leading/trailing/consecutive hyphens.

System prompt injection

On before_agent_start, appends:

After completing a complex task (5+ tool calls), fixing a tricky error, discovering a non-trivial workflow, or recovering from an unexpected failure, save the approach as a skill using the skill_manage tool so you can reuse it next time.

Background review loop

On agent_settled (every 10th settled event), sends a brief one-line follow-up prompt that asks the agent to review the completed session and create or patch skills with skill_manage. The message is kept minimal (single line with timestamp) so it does not clutter the conversation history.

You can also trigger a review manually at any time with /skill-evolution review now.

/skill-evolution command (extended)

The /skill-evolution slash command now supports subcommands for managing usage tracking and inactive-skill reminders. All settings are persisted to .skill-stats.json and survive Pi restarts.

Command	What it does
/skill-evolution review now	Manually trigger a skill review session
/skill-evolution reminder on	Enable weekly inactive-skill reminder (default)
/skill-evolution reminder off	Disable the weekly reminder
/skill-evolution reminder status	Show whether reminders are on/off + last check time
/skill-evolution reminder check	Manually trigger an inactive-skill scan right now
/skill-evolution inactive	List skills unused for 30+ days
/skill-evolution stats	Show usage count + last-used for every tracked skill
/skill-evolution disable <name>	Rename <name>/ → .disabled-<name>/ (Pi stops discovering it)
/skill-evolution enable <name>	Rename .disabled-<name>/ → <name>/ (restore it)
/skill-evolution (no args)	Show help with all available subcommands

Disabled skills are excluded from:

• skill_manage list results
• The weekly inactive-skill reminder scan
• Pi's skill auto-discovery (they don't appear in the system prompt)

They are still tracked in usage stats and can be re-enabled at any time.

Skill authoring playbook

skill-authoring is a model-invoked skill that auto-loads when the agent uses skill_manage. Covers:

• Name rules, description best practices, leading words
• Information hierarchy (step / reference / external reference)
• Progressive disclosure and when to split skills
• Failure modes: premature completion, duplication, sediment, sprawl, no-op
• skill_manage operation cheat sheet with preference order: patch loaded → patch existing → create

Hermes Agent vs pi-skill-evolution

Dimension	Hermes Agent	pi-skill-evolution
Review trigger	Daemon thread (spawn_background_review)	agent_settled event + sendUserMessage followUp
Skill management	Python skill_manager_tool.py	TypeScript pi.registerTool()
Prompt injection	prompt_builder.py hardcoded layer	before_agent_start event chain
Skill format	agentskills.io SKILL.md	agentskills.io SKILL.md
Review agent	Separate sub-agent instance	Reuses main agent loop

Pi's implementation is cleaner — no extra agent instances needed, fully leverages Pi's existing event-driven architecture and session system.

Development

Test the extension standalone

pi --extension /path/to/extensions/skill-evolution.ts

pi --extension /path/to/extensions/skill-evolution.ts \
   -p "List all skills with skill_manage"

Publish a new version

The project is published as pi-agent-skill-evolution on npmjs. To release a new version:

cd pi-skill-evolution
npm version patch     # or minor/major
npm publish

The pi-package keyword in package.json ensures it appears on pi.dev/packages.

Compatibility

Requires Pi Agent ≥ 0.80 (needs pi.registerTool() dynamic registration and the agent_settled event).