raydocs

Evolution Skills

Self-evolving skills for AI coding assistants.

AI 编程助手的自我进化技能系统。

English | 中文

---

English

Preface

Use only the skills you actually need. MCPs consume context, and skills consume context too. This system exists to help you build skills that solve your real work, not to wrap generic content from the internet. From personal experience, attention quality drops sharply beyond ~65k tokens, and default system/tool prompts can eat ~20k. If this is too long, just paste this GitHub link into your AI and ask how to use it.

What It Is

Evolution Skills is a documentation-first skill system for AI coding assistants. It ships structured specs and command templates that help capture reusable patterns, track their health, and keep guidance aligned with project style and framework versions.

Packages:

• Claude Code: claude-code/
• Factory Droid: factory-droid/

Why It Matters

• Preserve hard-won solutions as reusable patterns.
• Self-correct when suggestions fail.
• Build an automation-friendly learning loop so guidance improves with real usage.
• Track pattern health with deterministic rules.
• Adapt to project style and version constraints.

Feature Highlights

Capability	What it does	Where to learn more
Pattern capture	Save new patterns with /evolve	claude-code/README.md, factory-droid/README.md
Health reporting	Aggregate feedback markers via /skills-health	claude-code/README.md, factory-droid/README.md
Validation	Validate skills content with /validate-skills	claude-code/README.md
Version adaptation	Choose guidance based on detected versions	claude-code/README.md, factory-droid/README.md
Style profiling	Align output to project conventions	claude-code/README.md, factory-droid/README.md

Capability Checklist

Core loop:

• Capture proven fixes and patterns via /evolve
• Normalize entries with metadata (context, constraints, versions)
• Track health signals from deterministic feedback

Automation-friendly:

• Detect style and version constraints to guide output
• De-duplicate and update patterns when they fail
• Keep Claude and Factory guidance aligned by spec

Quick Start

Claude Code

cp -r claude-code/skills/* ~/.claude/skills/
cp -r claude-code/commands/* ~/.claude/commands/

Then run:

/evolve
/skills-health
/validate-skills

Factory Droid

cp -r factory-droid/skills/* ~/.factory/skills/
cp -r factory-droid/commands/* ~/.factory/commands/
cp -r factory-droid/droids/* ~/.factory/droids/   # optional

Then run:

/evolve
/skills-health

Command Overview

Command	Claude Code	Factory Droid	Purpose
/evolve	Yes	Yes	Save learned knowledge
/skills-health	Yes	Yes	Show health report
/validate-skills	Yes	No	Validate skills accuracy

Usage Guidance

Recommended workflow:

1. Solve a real issue, then run /evolve while context is fresh.
2. Review /skills-health regularly to find drift or failing patterns.
3. (Claude Code) Run /validate-skills after skill updates.

Authoring principles:

• Keep patterns small and specific (one problem, one pattern).
• Write constraints explicitly (version, style, environment).
• Prefer deterministic checks and clear success criteria.

Use Cases

• Capture a verified troubleshooting fix after resolving a build failure.
• Standardize a UI pattern across multiple projects.
• Keep guidance aligned with framework version upgrades.
• Detect stale patterns using health signals.

Automation & Learning Loop

1. Capture: validated fixes are saved via /evolve.
2. Normalize: entries are deduped and tagged with metadata.
3. Monitor: health is tracked through deterministic feedback rules.
4. Improve: patterns are updated or retired as failures accumulate.

Architecture

Dev Session
  |
  | triggers: /evolve, errors, usage
  v
Selection + Dedupe + Metadata
  |
  +--> ~/.claude/skills   (Claude Code)
  +--> ~/.factory/skills  (Factory Droid)
  |
  v
Health + Feedback Updates

This repo provides the specs and command templates. The assistant runtime applies them and writes entries as Markdown with metadata blocks.

Project Layout

claude-code/
  skills/
  commands/
factory-droid/
  skills/
  commands/
  droids/

Runtime storage lives under ~/.claude/skills or ~/.factory/skills. See the package READMEs for full details.

Documentation

• claude-code/README.md
• factory-droid/README.md

License

MIT

Contributing