skill-evolve
- Repo stars 434
- Author updated Live
- Author repo OneResearchClaw
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @gaotiexinqu · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: skill-evolve
description: Optional sidecar skill for controlled feedback-driven skill evolution. Not part of the default p…
category: other
runtime: Python
---
# skill-evolve output preview
## PART A: Task fit
- Use case: Optional sidecar skill for controlled feedback-driven skill evolution. Not part of the default pipeline. Only activates when explicitly requested. Skill Evolve is a controlled, opt-in framework for turning real user feedback into skill improvements over time. runs entirely locally; runs on Python. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “What This Skill Is / What This Skill Is NOT / When to Use This Skill” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Optional sidecar skill for controlled feedback-driven skill evolution. Not part of the default pipeline. Only activates when explicitly requested. Skill Evolve is a controlled, opt-in framework for turning real user feedback into skill improvements over time. runs entirely locally; runs on Python. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “What This Skill Is / What This Skill Is NOT / When to Use This Skill” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/path`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “What This Skill Is / What This Skill Is NOT / When to Use This Skill”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-evolve
description: Optional sidecar skill for controlled feedback-driven skill evolution. Not part of the default p…
category: other
source: gaotiexinqu/OneResearchClaw
---
# skill-evolve
## When to use
- Optional sidecar skill for controlled feedback-driven skill evolution. Not part of the default pipeline. Only activate…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “What This Skill Is / What This Skill Is NOT / When to Use This Skill” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-evolve" {
input -> user goal + target files + boundaries + acceptance criteria
context -> What This Skill Is / What This Skill Is NOT / When to Use This Skill
rules -> SKILL.md triggers / order / output contract
runtime -> Python | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} Skill Evolve (Optional Sidecar)
This is an OPTIONAL sidecar capability, NOT part of the default pipeline.
What This Skill Is
Skill Evolve is a controlled, opt-in framework for turning real user feedback into skill improvements over time.
It is designed to:
- Collect and normalize user feedback
- Generate minimal patch proposals
- Require manual review/refinement of generated patch proposals before real patch application
- Test reviewed patches in isolated workspaces
- Run regression gates
- Promote verified patches to new stable versions
- Preserve the default
.cursor/skills/tree unchanged unless a human later chooses to merge approved changes manually
What This Skill Is NOT
This skill must NOT:
- Run automatically during normal report generation
- Modify stable skills without explicit evolve flow
- Replace human judgment with automated decisions
- Make the default pipeline behave differently
When to Use This Skill
Use this skill when:
- User explicitly requests "skill evolution" or "feedback-driven improvement"
- User provides feedback that should be tracked and potentially addressed
- User wants to analyze and improve the skill framework
Do NOT use this skill when:
- Generating reports (use
one-reportinstead) - Running normal pipeline operations
- User has not explicitly requested skill evolution
Controlled Evolve Loop Flow
When explicitly invoked, follow this controlled flow:
Step 1: Collect Feedback
Use collect_feedback.py to ingest raw user feedback:
python .cursor/skills/skill-evolve/scripts/collect_feedback.py --interactive
# OR
python .cursor/skills/skill-evolve/scripts/collect_feedback.py --text "feedback text"
# OR
python .cursor/skills/skill-evolve/scripts/collect_feedback.py --file /path/to/feedback.txt
Raw feedback preserves user language and is saved to:
{WORKSPACE}/.skill-evolve-data/feedback/raw/
Step 2: Normalize Feedback
Convert raw feedback to structured format:
python .cursor/skills/skill-evolve/scripts/normalize_feedback.py \
--feedback-id FB-XXXXXX \
--stage <grounding|research|summary|review|export> \
--skill <skill-name>
Normalized feedback is saved to:
{WORKSPACE}/.skill-evolve-data/feedback/normalized/
Step 3: Propose Minimal Patch
Generate a patch proposal from normalized feedback:
python .cursor/skills/skill-evolve/scripts/propose_skill_patch.py \
--feedback-id FB-XXXXXX,FB-YYYYYY
Patch proposals are saved to:
{WORKSPACE}/.skill-evolve-data/patch_proposals/proposed/
Change Unit
A patch proposal is not just a single modified skill file, but a complete change unit containing:
- Main File: The skill being modified
- Dependency References: All other skills/agent configs that reference this skill
- Auto-generated Assertions: For regression gate verification
Dependency Reference Scanning
When generating a proposal, the agent must:
- Identify Main File: Determine which skill is the modification target
- Scan Dependencies: Search all skills and agent configs to find references to the main file
- Check other skills' "What This Skill Is" or invocation chain descriptions
- Check agent configs for skill references
- Check prompting templates for skill paths
- Declare Reference Points: List all locations requiring sync updates in the proposal
- Analyze Impact Scope: Distinguish between "description update only" and "behavior sync required" references
Example:
If the modification target is grounded-review:
- Main File:
.cursor/skills/grounded-review/SKILL.md - Dependency References:
.cursor/skills/one-report/SKILL.md(as sub-process reference).cursor/agents/reviewer.md(agent config)
Auto-generated Assertions
The proposal script should auto-generate assertions rather than relying on manual creation:
Analyze planned_changes:
- If
beforecontent exists → generatenot_containsassertion to verify old content removed - If
aftercontent exists → generatecontainsassertion to verify new content added - Numeric changes (90→95) → generate
regex_matchassertion
- If
Minimal Assertion Set:
- Core semantic changes must be covered by assertions
- Avoid redundant assertions (one
containscan verify content without splitting) - Empty tests cannot pass vacuously (reject if no changes)
Cross-file Assertions:
- If dependency references also need updates, those points should have corresponding assertions
- Ensure consistency between main file and reference points
Auto-generated Assertion Example (threshold 90→95):
{
"assertions": [
{
"name": "threshold_updated_to_95",
"type": "contains",
"file": "grounded-review/SKILL.md",
"pattern": "weighted total >= 95"
},
{
"name": "old_threshold_90_removed",
"type": "not_contains",
"file": "grounded-review/SKILL.md",
"pattern": "weighted total >= 90"
},
{
"name": "one_report_sync",
"type": "contains",
"file": "one-report/SKILL.md",
"pattern": "review threshold"
}
]
}
Step 4: Review and Refine Patch Proposal
Before applying any changes, review and refine the proposed planned_changes so they contain concrete, safe edits.
Do not treat an auto-generated proposal as ready-to-apply by default.
Step 5: Apply Patch Candidate
Apply the reviewed patch to an isolated workspace for testing:
python .cursor/skills/skill-evolve/scripts/apply_patch_to_workspace.py \
--proposal-id PP-XXXXXX \
--apply-changes
This creates a candidate workspace without modifying stable skills.
Step 6: Run Regression Gate
Test the patch against evaluation cases:
python .cursor/skills/skill-evolve/scripts/run_regression_gate.py \
--proposal-id PP-XXXXXX
Results are saved to:
{WORKSPACE}/.skill-evolve-data/evaluations/results/
Regression Gate for Change Units
Regression gate must verify the complete change unit:
- Main File Assertions: Verify core changes in the main skill file
- Dependency Reference Assertions: Verify sync updates for all dependency reference points
- Consistency Checks: Ensure descriptions/behaviors match between main file and references
Assertion File Path Resolution
The file field in assertions is resolved relative to workspace root:
grounded-review/SKILL.md→{workspace}/grounded-review/SKILL.mdone-report/SKILL.md→{workspace}/one-report/SKILL.md.cursor/agents/reviewer.md→{workspace}/.cursor/agents/reviewer.md
Failure Handling
If any assertion fails (main file or dependency reference), gate result is reject:
{
"decision": "reject",
"reason": "Dependency reference out of sync: one-report/SKILL.md missing review threshold update"
}
Step 7: Promote or Reject
If gate passes, promote the candidate:
Standard promotion (creates versioned directory only):
python .cursor/skills/skill-evolve/scripts/promote_skill_version.py \
--gate-id GR-XXXXXX \
--notes "Description of changes"
Sync promotion (also updates stable skills/):
python .cursor/skills/skill-evolve/scripts/promote_skill_version.py \
--gate-id GR-XXXXXX \
--notes "Description of changes" \
--sync
Result (standard):
- Original
.cursor/skills/remains untouched - New
.skill-evolve-data/skills-versions/v002/created with patches applied
Result (--sync):
- Versioned directory created as above
- Additionally: stable
.cursor/skills/is updated with approved patches - Consistency checks run to ensure no old patterns remain
Consistency Check Feature: The promote script now runs full line-by-line checks on patched files to ensure:
- No remaining old patterns (e.g.,
weighted_total >= 90when it should be>= 95) - Cross-file consistency (all related files updated together)
- Report any missed updates before finalizing
If gate fails, the patch is rejected and stable version remains unchanged.
Version Management
Stable Version Pointer
Located at: {WORKSPACE}/.skill-evolve-data/stable/current_version.json
Contains:
- Current stable version ID
- Path to version manifest
- Last update timestamp
Version Manifests
Located at: {WORKSPACE}/.skill-evolve-data/versions/vXXX/version_manifest.json
Contains:
- Version ID
- Based-on version
- Accepted patch IDs
- Passed gate IDs
- Rollback information
Safety Principles
- Opt-in Only: Nothing runs automatically
- Isolation: Patches are tested in isolated workspaces
- Human Approval: Promotion requires successful gate + explicit promotion call
- Rollback Ready: Every stable version knows its rollback target
- No Overwrite: Stable skills are never modified without explicit promotion
Directory Layout
Skill Code (in .cursor/skills/skill-evolve/)
.cursor/
skills/
skill-evolve/
SKILL.md # This file
scripts/ # Evolution workflow scripts
schemas/ # JSON schemas
Data Directory (in {WORKSPACE}/.skill-evolve-data/)
{WORKSPACE}/
.skill-evolve-data/
stable/
current_version.json
versions/
v001/
version_manifest.json
vXXX/
skills-versions/ # Versioned skill+agent snapshots (created on promotion)
v001/
agents/ # copy of .cursor/agents/
skills/ # copy of .cursor/skills/
v002/
agents/
skills/
feedback/
raw/ # Original user feedback
normalized/ # Structured feedback
patch_proposals/
proposed/ # Generated proposals
accepted/ # Successfully promoted
rejected/ # Failed or rejected
evaluations/
cases/ # Evaluation case definitions
results/ # Gate execution results
Key Design Principle
- Skill code stays in
.cursor/skills/skill-evolve/(git-managed) - Versioned snapshots go to
.skill-evolve-data/skills-versions/(each version contains bothagents/andskills/sub-dirs) - Runtime data goes to
{WORKSPACE}/.skill-evolve-data/(local, git-ignored)
Example Invocation
User explicitly requests skill evolution:
Use the skill-evolve framework to analyze my feedback and propose improvements.
My feedback: The grounded-research-lit skill sometimes opens fewer papers than the `MIN_OPENED_PAPERS` threshold set by `research_mode`. The cursor backend should ensure the configured minimum number of unique papers are opened before proceeding to summary.
Feedback ID reference: FB-280408 (collected earlier)
Agent would then:
- Normalize the feedback with appropriate stage and skill
- Propose a minimal patch
- Apply to candidate workspace
- Run regression gate
- Report results for human decision
Summary
| Aspect | Default Pipeline | Skill Evolve |
|---|---|---|
| Activation | Automatic | Explicit request only |
| Purpose | Report generation | Skill improvement |
| Modifications | None | Controlled via gate |
| Automatic changes | Yes | No |
| Human approval | N/A | Required for promotion |
Important Activation Rule
Promotion updates the Skill Evolve stable pointer and creates a new versioned snapshot such as .skill-evolve-data/skills-versions/v002/, which contains both agents/ and skills/ sub-directories. This ensures every version is self-contained and reproducible.
It does not automatically rewrite ordinary prompts or make the default .cursor/skills/ or .cursor/agents/ trees behave differently.
If a user wants to use a promoted version in a future chat, they must explicitly point the prompt at that versioned snapshot path or manually merge the approved changes back into .cursor/skills/ and .cursor/agents/.
Rejection Path
If a proposal is not suitable or fails the regression gate, archive it explicitly using:
python .cursor/skills/skill-evolve/scripts/reject_patch_proposal.py \
--proposal-id PP-XXXXXX \
--reason "Why this proposal is rejected"
Do not leave failed proposals ambiguous if you already know they should not be promoted.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review