|
| 1 | +--- |
| 2 | +name: learn |
| 3 | +description: Must be used near the end of any non-trivial turn that produced potentially reusable tools, guidance, errors, workarounds, or workflows, so those lessons are saved for future turns. |
| 4 | +--- |
| 5 | + |
| 6 | +# Entity Generator |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +This skill analyzes the current Codex conversation to extract actionable instructions that would help on similar tasks in the future. It **identifies errors encountered during the conversation** - tool failures, exceptions, wrong approaches, retry loops - and provides recommendations to prevent those errors from recurring. This skill should take note of the concrete solution which solved a concrete problem, not an abstract idea. When the successful resolution involves a non-trivial workaround, parser, command sequence, or fallback pipeline that could be used to avoid wasted effort, capture that solution as a reusable artifact first, then save entities that point future agents to use it. |
| 11 | + |
| 12 | +## When To Use |
| 13 | + |
| 14 | +Use this skill after completing meaningful work in the turn, especially when encountering: |
| 15 | +- tool failures |
| 16 | +- permission issues |
| 17 | +- missing dependencies |
| 18 | +- retries or abandoned approaches |
| 19 | +- reusable command sequences or scripts |
| 20 | + |
| 21 | +Examples of artifacts that must be immediately created once proven as the successful solution include: |
| 22 | +- an inline Python, shell, or other heredoc script |
| 23 | +- a command assembled interactively over multiple retries |
| 24 | +- a parser or extractor implemented ad hoc during the turn |
| 25 | +- a fallback path triggered by missing dependencies or restricted tooling |
| 26 | + |
| 27 | +Unless that artifact happens to be: |
| 28 | +- code which is a trivial one-liner that future agents would not benefit from reusing |
| 29 | +- code which embeds secrets, tokens, or user-specific sensitive data |
| 30 | +- the guideline would instruct the agent to invoke a skill, tool, or external command by name (e.g. "run evolve-lite:learn", "call save_trajectory") - such guidelines trigger prompt-injection detection when retrieved by the recall skill in a future session |
| 31 | +- the user explicitly asked for a one-off result and not to persist helper code |
| 32 | +- redundant because an equivalent local artifact on disk would be just as effective |
| 33 | + |
| 34 | +## Workflow |
| 35 | + |
| 36 | +### Step 1: Analyze the Conversation |
| 37 | + |
| 38 | +Identify from your current conversation: |
| 39 | + |
| 40 | +- **Task/Request**: What was the user asking for? |
| 41 | +- **Steps Taken**: What reasoning, actions, and observations occurred? |
| 42 | +- **What Worked**: Which approaches succeeded? |
| 43 | +- **What Failed**: Which approaches did not work and why? |
| 44 | +- **Errors Encountered**: Tool failures, exceptions, permission errors, retry loops, dead ends, and wrong initial approaches |
| 45 | +- **Reusable Outcome**: Did the final working solution produce a reusable script, parser, command template, or workflow that would save time on a similar task? |
| 46 | + |
| 47 | +### Step 2: Identify Errors and Root Causes |
| 48 | + |
| 49 | +Scan the conversation for these error signals: |
| 50 | + |
| 51 | +1. **Tool or command failures**: Non-zero exit codes, error messages, exceptions, stack traces |
| 52 | +2. **Permission or access errors**: "Permission denied", "not found", sandbox restrictions |
| 53 | +3. **Wrong initial approach**: First attempt abandoned in favor of a different strategy |
| 54 | +4. **Retry loops**: Same action attempted multiple times with variations before succeeding |
| 55 | +5. **Missing prerequisites**: Missing dependencies, packages, or configs discovered mid-task |
| 56 | +6. **Silent failures**: Actions that appeared to succeed but produced wrong results |
| 57 | + |
| 58 | +For each error found, document: |
| 59 | + |
| 60 | +| | Error Example | Root Cause | Resolution | Prevention Guideline | |
| 61 | +|---|---|---|---|---| |
| 62 | +| 1 | `jq: command not found` | System tool unavailable in environment | created a python script to resolve the problem | Save the python script and use it in similar scenarios | |
| 63 | +| 2 | `git push` rejected (no upstream) | Branch not tracked to remote | Added `-u origin branch` | Always set upstream when pushing a new branch | |
| 64 | +| 3 | Tried regex parsing of HTML, got wrong results | Regex cannot handle nested tags | Switched to BeautifulSoup | Use a proper HTML parser, never regex | |
| 65 | + |
| 66 | +### Step 3: Decide Whether To Save The Pipeline |
| 67 | + |
| 68 | +Before writing entities, determine whether the successful approach should be saved as a reusable artifact. |
| 69 | + |
| 70 | +Create or update a local reusable artifact when any of these are true: |
| 71 | +- the final solution required more than a trivial one-liner |
| 72 | +- the final solution worked around missing tools, libraries, or permissions |
| 73 | +- the solution is likely to recur on similar tasks |
| 74 | + |
| 75 | +Prefer one of these artifact forms: |
| 76 | +- a small script, saved to a stable path in the workspace or plugin, such as `scripts/`, `tools/`, or another obvious helper location. |
| 77 | +- a documented local workflow if code is not appropriate |
| 78 | + |
| 79 | +If you create an artifact, record: |
| 80 | +- its path |
| 81 | +- what it does |
| 82 | +- when future agents should use it first |
| 83 | + |
| 84 | +### Step 4: Extract Entities |
| 85 | + |
| 86 | +If Step 3 produced an artifact, at least one entity must explicitly point to that artifact, which is likely the only entity that needs to be produced. |
| 87 | +Otherwise, extract 3-5 proactive entities. Prioritize entities derived from errors identified in Step 2. |
| 88 | + |
| 89 | +Follow these principles: |
| 90 | + |
| 91 | +1. **Reframe failures as proactive recommendations** |
| 92 | + - If an approach failed due to permissions, recommend the working permission-aware approach first |
| 93 | + - If a system tool was unavailable, recommend the saved artifact or fallback workflow first |
| 94 | + - If an approach hit environment constraints, recommend the constraint-aware approach |
| 95 | + |
| 96 | +2. **Prioritize known working local artifacts over general advice** |
| 97 | + - If the successful solution produced or reused a concrete local artifact, at least one saved entity must: |
| 98 | + - Bad: "Use Python to parse EXIF if exiftool is missing" |
| 99 | + - Better: "Use `/abs/path/json_get.py` for JSON field extraction when `jq` is unavailable in minimal environments." |
| 100 | + - name the artifact by path |
| 101 | + - state exactly when to use it |
| 102 | + - state that it should be tried before generic tool discovery or fallback exploration |
| 103 | + - describe the artifact by capability, not just by the original incident |
| 104 | + |
| 105 | +3. **Triggers should describe the broad task context that the artifact solves, not the narrow details of the original request.** |
| 106 | + - Bad trigger: "When jq fails" |
| 107 | + - Good trigger: "When extracting fields from JSON in constrained shells or stripped-down environments" |
| 108 | + The trigger should generalize the working solution without becoming vague. |
| 109 | + |
| 110 | +4. **For retry loops, recommend the final working approach as the starting point** |
| 111 | + - Eliminate trial and error by creating a concrete local artifact out of the successful workflow or script |
| 112 | + |
| 113 | +5. **Prefer entities that save future time** |
| 114 | + - A pointer to a saved working script is more valuable than a generic reminder if both are available |
| 115 | + |
| 116 | +### Step 5: Output Entities JSON |
| 117 | + |
| 118 | +Output entities in this JSON format: |
| 119 | + |
| 120 | +```json |
| 121 | +{ |
| 122 | + "entities": [ |
| 123 | + { |
| 124 | + "content": "Proactive entity stating what TO DO", |
| 125 | + "rationale": "Why this approach works better", |
| 126 | + "type": "guideline", |
| 127 | + "trigger": "Situational context when this applies" |
| 128 | + } |
| 129 | + ] |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +Allowed type values: |
| 134 | +- guideline |
| 135 | +- workflow |
| 136 | +- script |
| 137 | +- command-template |
| 138 | + |
| 139 | +### Step 6: Save Entities |
| 140 | + |
| 141 | +After generating the entities JSON, save them using the helper script: |
| 142 | + |
| 143 | + |
| 144 | +#### Method 1: Direct Pipe (Recommended) |
| 145 | + |
| 146 | +```bash |
| 147 | +echo '<your-json-output>' | python3 "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/plugins/evolve-lite/skills/learn/scripts/save_entities.py" |
| 148 | +``` |
| 149 | + |
| 150 | +#### Method 2: From File |
| 151 | + |
| 152 | +```bash |
| 153 | +cat entities.json | python3 "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/plugins/evolve-lite/skills/learn/scripts/save_entities.py" |
| 154 | +``` |
| 155 | + |
| 156 | +#### Method 3: Interactive |
| 157 | + |
| 158 | +```bash |
| 159 | +python3 "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/plugins/evolve-lite/skills/learn/scripts/save_entities.py" |
| 160 | +``` |
| 161 | + |
| 162 | +The script will: |
| 163 | +- Find or create the entities directory at `.evolve/entities/` |
| 164 | +- Write each entity as a markdown file in `{type}/` subdirectories |
| 165 | +- Deduplicate against existing entities |
| 166 | +- Display confirmation with the total count |
| 167 | + |
| 168 | +## Best Practices |
| 169 | +1. Prioritize error-derived entities first. |
| 170 | +2. One distinct error should normally produce one prevention entity. |
| 171 | +3. Keep entities specific and actionable. |
| 172 | +4. Include rationale so the future agent understands why the guidance matters. |
| 173 | +5. Use situational triggers instead of failure-based triggers. |
| 174 | +6. Limit output to the 3-5 most valuable entities. |
| 175 | +7. If more than five distinct errors appear, merge entities with the same root cause or fix, then rank the rest by severity, frequency, user impact, and recency before dropping the weakest ones. |
0 commit comments