skill evolve
- Repo stars 434
- Author repo OneResearchClaw
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- 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
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Use `collect_feedback.py` to ingest raw user feedback: Raw feedback preserves user language and is saved to: `{WORKSPACE}/.skill-evolve-data/feedback/raw/`
Convert raw feedback to structured format: Normalized feedback is saved to: `{WORKSPACE}/.skill-evolve-data/feedback/normalized/`
Generate a patch proposal from normalized feedback: 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:
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.
Apply the reviewed patch to an isolated workspace for testing: This creates a candidate workspace without modifying stable skills.
Test the patch against evaluation cases: Results are saved to: `{WORKSPACE}/.skill-evolve-data/evaluations/results/` Regression Gate for Change Units Regression gate must verify the complete change unit:
If gate passes, promote the candidate: Standard promotion (creates versioned directory only): Sync promotion (also updates stable skills/): Result (standard): Original `.cursor/skills/` remains untouched
# 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-report` instead)
- 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:
```bash
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:
```bash
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:
```bash
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:
1. **Main File**: The skill being modified
2. **Dependency References**: All other skills/agent configs that reference this skill
3. **Auto-generated Assertions**: For regression gate verification
#### Dependency Reference Scanning
When generating a proposal, the agent must:
1. **Identify Main File**: Determine which skill is the modification target
2. **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
3. **Declare Reference Points**: List all locations requiring sync updates in the proposal
4. **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:
1. **Analyze planned_changes**:
- If `before` content exists → generate `not_contains` assertion to verify old content removed
- If `after` content exists → generate `contains` assertion to verify new content added
- Numeric changes (90→95) → generate `regex_match` assertion
2. **Minimal Assertion Set**:
- Core semantic changes must be covered by assertions
- Avoid redundant assertions (one `contains` can verify content without splitting)
- Empty tests cannot pass vacuously (reject if no changes)
3. **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):
```json
{
"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:
```bash
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:
```bash
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:
1. **Main File Assertions**: Verify core changes in the main skill file
2. **Dependency Reference Assertions**: Verify sync updates for all dependency reference points
3. **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.md`
- `one-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`:
```json
{
"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):
```bash
python .cursor/skills/skill-evolve/scripts/promote_skill_version.py \
--gate-id GR-XXXXXX \
--notes "Description of changes"
```
**Sync promotion** (also updates stable skills/):
```bash
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 >= 90` when 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
1. **Opt-in Only**: Nothing runs automatically
2. **Isolation**: Patches are tested in isolated workspaces
3. **Human Approval**: Promotion requires successful gate + explicit promotion call
4. **Rollback Ready**: Every stable version knows its rollback target
5. **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 both `agents/` and `skills/` 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:
1. Normalize the feedback with appropriate stage and skill
2. Propose a minimal patch
3. Apply to candidate workspace
4. Run regression gate
5. 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:
```bash
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.
Listed in source order.
sections -> What This Skill Is → What This Skill Is NOT → When to Use This Skill → Controlled Evolve Loop Flow → Step 1: Collect Feedback → Step 2: Normalize Feedback
terms -> This is an OPTIONAL sidecar capability, NOT part of the default pipeline. · controlled, opt-in framework · change unit · Main File · Dependency References · Auto-generated Assertions · Identify Main File · Scan Dependencies
files/cmd -> .cursor/skills/ · one-report · collect_feedback.py · {WORKSPACE}/.skill-evolve-data/feedback/raw/ · {WORKSPACE}/.skill-evolve-data/feedback/normalized/ · {WORKSPACE}/.skill-evolve-data/patch_proposals/proposed/ · grounded-review · .cursor/skills/grounded-review/SKILL.md
body sha256 -> a318fef6bad6
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
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:
Controlled Evolve Loop Flow
When explicitly invoked, follow this controlled flow:
Step 1: Collect Feedback
Use
collect_feedback.pyto ingest raw user feedback: Raw feedback preserves user language and is saved to:{WORKSPACE}/.skill-evolve-data/feedback/raw/