agentleFS
eugenezhangco-speceugenezhangco-spec/athena/.claude/skills/self-upgrade/SKILL.md

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

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
  1. Distinctive:

    What exists today?: Read ALL affected files before planning any changes.

    line 47
  2. Distinctive:

    Wait for approval before modifying anything.

    line 53
  3. Distinctive:

    If building a new integration: search for existing libraries, MCP servers, or community solutions first.

    line 59
  4. Very specific:

    If upgrading the bot: check bot.js for the current architecture before planning changes.

    line 60
  5. Distinctive:

    Write the plan with:

    line 76
  6. Distinctive:

    Follow the format standards in architecture.md META section

    line 84
  7. Distinctive:

    Read the file before editing.

    line 87
  8. Distinctive:

    Write tests for any logic that matters

    line 91
  9. Distinctive:

    Read the file back and confirm it matches the plan.

    line 105
  10. Distinctive:

    Do existing capabilities still work?

    line 108
  11. Distinctive:

    If a rule was changed: does it contradict any other rule?

    line 109
  12. Distinctive:

    If a skill was changed: does the trigger still work?

    line 110
  13. Distinctive:

    If code was changed: run the tests.

    line 111
  14. Distinctive:

    No secrets exposed in any file

    line 114
  15. Distinctive:

    No auth logic weakened

    line 115
  16. Distinctive:

    No sensitive data in skill triggers or rule text

    line 117
  17. Distinctive:

    After any successful self-upgrade:

    line 127
  18. Very specific:

    Update .claude/SYSTEM.md — add/modify the relevant entry in Skills, Features, or Tech Stack tables

    line 128
  19. Very specific:

    Update personal/snapshot.md — log the system change under recent session outcomes

    line 129
  20. Distinctive:

    If a new skill was created: add it to the Skills table in CLAUDE.md

    line 130
  21. Very specific:

    After enough sessions, Athena may detect patterns that suggest a new skill or rule:

    line 170
  22. Distinctive:

    Approval: Wait for "yes" or equivalent.

    line 174
  23. Distinctive:

    Build: Run the full self-upgrade pipeline above.

    line 175

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. What is being changed? Identify the specific capability, behavior, or system component.
  2. Why? User request, detected gap, repeated pattern, or mistake correction.
  3. What exists today? Read ALL affected files before planning any changes. This is non-negotiable.
  4. 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:

TypeWhenApproach
New ruleNew always-on behavior neededCreate new file in .claude/rules/ following META format
Rule updateExisting behavior needs adjustmentEdit existing rule file. Never delete, always evolve.
New skillOn-demand capability needed (3+ manual recurrences or user request)Create new folder + SKILL.md in .claude/skills/
Skill updateExisting skill needs improvementEdit existing SKILL.md. Preserve working behavior.
Bot upgradeNew Telegram capabilityModify bot/bot.js with full engineering rigor
Script changeNew or modified cron/automationModify or create in scripts/
IntegrationNew MCP or external serviceUpdate .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:

  1. Update .claude/SYSTEM.md — add/modify the relevant entry in Skills, Features, or Tech Stack tables
  2. Update personal/snapshot.md — log the system change under recent session outcomes
  3. 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

ActionWhy
Delete any rule or skill fileMay contain context needed later. Archive instead.
Modify personality.mdCore identity changes need explicit consent.
Modify coaching.md challenge protocolUser may not want accountability reduced.
Change proactive-rules.md tiers (green/yellow/red)Affects what Athena does without asking.
Modify bot.js message handlingTelegram is a live public interface.
Add or remove MCP integrationsConnects to external services. User must approve.
Modify session hooksAffects every future session start/stop.

Always Safe (No Approval Needed)

ActionWhy
Add a new skill fileExtends capability, does not change existing behavior.
Add examples to an existing ruleClarifies, does not change behavior.
Fix a typo or formatting errorNo behavior change.
Update SYSTEM.md manifestReflects reality, does not change behavior.
Add an entry to decisions/log.mdDocumentation only.

When Athena Proposes Her Own Upgrades

After enough sessions, Athena may detect patterns that suggest a new skill or rule:

  1. Detection: "I have done [task] manually in 3 sessions now. This should be a skill."
  2. Proposal: Present the idea to the user. One paragraph. What it does, why, what triggers it.
  3. Approval: Wait for "yes" or equivalent. Never self-modify based on assumption.
  4. Build: Run the full self-upgrade pipeline above.
  5. Announce: "New skill installed: [name]. It will activate when [trigger]. Try it."

Anti-Patterns

Anti-PatternWhat To Do Instead
Modify a rule mid-conversation to fix a one-time issueNote it. Apply at session end. Mid-session changes risk inconsistency.
Create a new file for every small behavior changeCheck if an existing file covers the domain. Extend first, create second.
Write vague skill descriptionsPushy, 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 changesOne change per modification. Easier to debug, easier to revert.
Overwrite a file without reading it firstALWAYS read first. You might destroy working behavior you forgot about.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.