self-upgrade
Skill0 starsChanged 7 months agoMITView on GitHub
Safe self-modification skill for upgrading Athena's own capabilities. Use when the user says 'upgrade yourself', 'add a new skill', 'improve yourself', 'you should be able to do X', 'can you learn to do X', 'change how you handle X', 'add this capability', 'make yourself better at X', or when Athena detects a system gap during a session. Also fires when the user wants to modify any file in .claude/rules/, .claude/skills/, or system files. Do NOT use for building user projects -- that is code-engineer. This skill is specifically for modifying Athena's own brain.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- vellum-ai/vellum-assistanttheir own version, first seen Jul 8, 2026
- sonichi/sutandotheir own version, first seen May 17, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- vellum-ai/vellum-assistant★ 1.5ksame name
- sonichi/sutando★ 396same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository57 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- knowledge/CLAUDE.mdCLAUDE.md
- agent-harness-constructionSkill
- agentic-engineeringSkill
- ai-first-engineeringSkill
- api-designSkill
- backend-patternsSkill
- blueprintSkill
- bookmarkSkill
- brain-dumpSkill
- building-explainerSkill
- calendar-managerSkill
- code-engineerSkill
- compileSkill
- continuous-agent-loopSkill
- continuous-learningSkill
- copywriterSkill
- cost-aware-llm-pipelineSkill
- councilSkill
- database-migrationsSkill
- day-plannerSkill
- debriefSkill
- deep-researchSkill
- deployment-patternsSkill
- docker-patternsSkill
- e2e-testingSkill
- claude-apiSkill
- coding-standardsSkill
- eng-inboxSkill
- updateSkill
- enterprise-agent-opsSkill
- eval-harnessSkill
- frontend-patternsSkill
- humanizerSkill
- iterative-retrievalSkill
- log-expenseSkill
- memory-auditSkill
- migrateSkill
- minimalist-uiSkill
- onboardSkill
- full-output-enforcementSkill
- postgres-patternsSkill
- redesign-existing-projectsSkill
- regex-vs-llm-structured-textSkill
- researchSkill
- search-firstSkill
- security-reviewSkill
- security-scanSkill
- high-end-visual-designSkill
- spending-summarySkill
- design-taste-frontendSkill
- tdd-workflowSkill
- transcribeSkill
- verification-loopSkill
- video-ideasSkill
- weekly-reviewSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 19 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈19
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 47
What exists today?: Read ALL affected files before planning any changes.
- Distinctive: line 53
Wait for approval before modifying anything.
- Distinctive: line 59
If building a new integration: search for existing libraries, MCP servers, or community solutions first.
- Very specific: line 60
If upgrading the bot: check bot.js for the current architecture before planning changes.
- Distinctive: line 76
Write the plan with:
- Distinctive: line 84
Follow the format standards in architecture.md META section
- Distinctive: line 87
Read the file before editing.
- Distinctive: line 91
Write tests for any logic that matters
- Distinctive: line 105
Read the file back and confirm it matches the plan.
- Distinctive: line 108
Do existing capabilities still work?
- Distinctive: line 109
If a rule was changed: does it contradict any other rule?
- Distinctive: line 110
If a skill was changed: does the trigger still work?
- Distinctive: line 111
If code was changed: run the tests.
- Distinctive: line 114
No secrets exposed in any file
- Distinctive: line 115
No auth logic weakened
- Distinctive: line 117
No sensitive data in skill triggers or rule text
- Distinctive: line 127
After any successful self-upgrade:
- Very specific: line 128
Update .claude/SYSTEM.md — add/modify the relevant entry in Skills, Features, or Tech Stack tables
- Very specific: line 129
Update personal/snapshot.md — log the system change under recent session outcomes
- Distinctive: line 130
If a new skill was created: add it to the Skills table in CLAUDE.md
- Very specific: line 170
After enough sessions, Athena may detect patterns that suggest a new skill or rule:
- Distinctive: line 174
Approval: Wait for "yes" or equivalent.
- Distinctive: line 175
Build: Run the full self-upgrade pipeline above.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill: Self-Upgrade
Dependencies (Load Before Running)
.claude/SYSTEM.md— current system manifest (skills, features, integrations, health).claude/rules/evolution.md— self-improvement protocol and safety constraints.claude/rules/architecture.md— how to structure new capabilities.claude/rules/security.md— self-modification safety checks
What This Skill Does
Handles all modifications to Athena's own systems — new skills, updated rules, new integrations, architecture changes, bot upgrades, script improvements. Applies the full engineering pipeline to Athena's own brain, because a self-modifying AI system that modifies itself carelessly is a system that breaks itself.
This skill treats Athena's own codebase with the same rigor as any user project. Research first. Plan first. Test after. Review everything.
How to Activate
Explicit triggers:
- "Upgrade yourself" / "Improve yourself" / "Make yourself better"
- "Add a skill for X" / "Learn to do X" / "You should be able to X"
- "Change how you handle X" / "Update your rules for X"
- "Fix that about yourself" (after Athena makes a mistake)
/self-upgrade
Auto-fire triggers:
- Evolution protocol detects a system gap (step 8 of post-session self-check)
- A task has been done manually 3+ times with the same pattern (skill candidate)
- User corrects Athena's behavior in a way that should persist across sessions
The Self-Upgrade Pipeline
Phase 1: Understand the Change
- What is being changed? Identify the specific capability, behavior, or system component.
- Why? User request, detected gap, repeated pattern, or mistake correction.
- What exists today? Read ALL affected files before planning any changes. This is non-negotiable.
- What is the blast radius? Which other rules, skills, or behaviors could be affected?
Present a one-paragraph summary to the user:
"Here is what I am going to change: [what]. This affects [files]. The reason is [why]. Should I proceed?"
Wait for approval before modifying anything. No exceptions.
Phase 2: Research
- Is there a proven pattern for this type of capability? Check architecture.md META section.
- Does a similar skill or rule already exist that could be extended instead of creating something new?
- If building a new integration: search for existing libraries, MCP servers, or community solutions first.
- If upgrading the bot: check bot.js for the current architecture before planning changes.
Phase 3: Plan the Change
Determine the change type:
| Type | When | Approach |
| New rule | New always-on behavior needed | Create new file in .claude/rules/ following META format |
| Rule update | Existing behavior needs adjustment | Edit existing rule file. Never delete, always evolve. |
| New skill | On-demand capability needed (3+ manual recurrences or user request) | Create new folder + SKILL.md in .claude/skills/ |
| Skill update | Existing skill needs improvement | Edit existing SKILL.md. Preserve working behavior. |
| Bot upgrade | New Telegram capability | Modify bot/bot.js with full engineering rigor |
| Script change | New or modified cron/automation | Modify or create in scripts/ |
| Integration | New MCP or external service | Update .mcp.json, add connection logic, update SYSTEM.md |
Write the plan with:
- Files to create or modify (list every one)
- What each change does
- What should NOT change (preservation list)
Phase 4: Implement
For rules and skills (markdown files):
- Follow the format standards in architecture.md META section
- Rules: imperative voice, NEVER/ALWAYS for clarity, tables for structured info, negative boundaries
- Skills: pushy descriptions, clear triggers, numbered steps, output format, anti-patterns
- Read the file before editing. Never overwrite blind.
For code (bot.js, scripts, new integrations):
- Apply the FULL engineering pipeline from engineering-guardian.md:
- Write tests for any logic that matters
- Security review (especially for bot changes — Telegram is a public interface)
- Error handling on every async path
- No hardcoded secrets
- Input validation on anything coming from users or external services
For all changes:
- One logical change per modification. Do not batch unrelated changes.
- Preserve existing working behavior unless explicitly changing it.
Phase 5: Verify
Functional check:
- Does the new/modified capability do what was intended?
- Read the file back and confirm it matches the plan.
Regression check:
- Do existing capabilities still work? Read adjacent rules/skills that might be affected.
- If a rule was changed: does it contradict any other rule? Scan for conflicts.
- If a skill was changed: does the trigger still work? Does the output format still make sense?
- If code was changed: run the tests. Run the bot in test mode if possible.
Security check (mandatory for all self-modifications):
- No secrets exposed in any file
- No auth logic weakened
- No permission escalation
- No sensitive data in skill triggers or rule text
- Bot changes: no way for external users to trigger admin-level operations
Architecture check:
- Is the change in the right file? (Not bolted onto an unrelated file)
- Is the file under 150 lines? (Split if it exceeds)
- Does the naming follow conventions?
Phase 6: Update Manifest
After any successful self-upgrade:
- Update
.claude/SYSTEM.md— add/modify the relevant entry in Skills, Features, or Tech Stack tables - Update
personal/snapshot.md— log the system change under recent session outcomes - If a new skill was created: add it to the Skills table in
CLAUDE.md
Phase 7: Explain the Change
Tell the user:
- What changed and where (file paths)
- Why it was done this way
- How it will affect their experience going forward
- Any technical concepts involved (use Building Explainer protocol)
Guardrails
Never Do These Without Explicit User Approval
| Action | Why |
| Delete any rule or skill file | May contain context needed later. Archive instead. |
| Modify personality.md | Core identity changes need explicit consent. |
| Modify coaching.md challenge protocol | User may not want accountability reduced. |
| Change proactive-rules.md tiers (green/yellow/red) | Affects what Athena does without asking. |
| Modify bot.js message handling | Telegram is a live public interface. |
| Add or remove MCP integrations | Connects to external services. User must approve. |
| Modify session hooks | Affects every future session start/stop. |
Always Safe (No Approval Needed)
| Action | Why |
| Add a new skill file | Extends capability, does not change existing behavior. |
| Add examples to an existing rule | Clarifies, does not change behavior. |
| Fix a typo or formatting error | No behavior change. |
| Update SYSTEM.md manifest | Reflects reality, does not change behavior. |
| Add an entry to decisions/log.md | Documentation only. |
When Athena Proposes Her Own Upgrades
After enough sessions, Athena may detect patterns that suggest a new skill or rule:
- Detection: "I have done [task] manually in 3 sessions now. This should be a skill."
- Proposal: Present the idea to the user. One paragraph. What it does, why, what triggers it.
- Approval: Wait for "yes" or equivalent. Never self-modify based on assumption.
- Build: Run the full self-upgrade pipeline above.
- Announce: "New skill installed: [name]. It will activate when [trigger]. Try it."
Anti-Patterns
| Anti-Pattern | What To Do Instead |
| Modify a rule mid-conversation to fix a one-time issue | Note it. Apply at session end. Mid-session changes risk inconsistency. |
| Create a new file for every small behavior change | Check if an existing file covers the domain. Extend first, create second. |
| Write vague skill descriptions | Pushy, specific descriptions. Claude under-triggers vague skills. |
| Skip the verification step because "it is just a markdown file" | Markdown files ARE the brain. A bad rule affects every future conversation. |
| Batch multiple unrelated changes | One change per modification. Easier to debug, easier to revert. |
| Overwrite a file without reading it first | ALWAYS read first. You might destroy working behavior you forgot about. |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

