Apply plugin knowledge base updates to an existing generated system. Consults the Ars Contexta research graph for methodology improvements, proposes skill upgrades with research justification. Never auto-implements. Triggers on "/upgrade", "upgrade skills", "check for
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/upgrade
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Apply plugin knowledge base updates to an existing generated system. Consults the Ars Contexta research graph for methodology improvements, proposes skill upgrades with research justification. Never auto-implements. Triggers on "/upgrade", "upgrade skills", "check for
📊 Stats
Stars3,451
Forks218
LanguageShell
LicenseMIT
📦 Ships with arscontexta
</> SKILL.md
upgrade.SKILL.md
---name: upgrade
description: Apply plugin knowledge base updates to an existing generated system. Consults the Ars Contexta research graph for methodology improvements, proposes skill upgrades with research justification. Never auto-implements. Triggers on "/upgrade", "upgrade skills", "check for improvements", "update methodology".
version: "1.0"
generated_from: "arscontexta-v1.6"
user-invocable: true
context: fork
model: opus
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
---## Runtime Configuration (Step 0 — before any processing)
Read these files to configure domain-specific behavior:
1. **`ops/derivation-manifest.md`** — vocabulary mapping, platform hints
- Use `vocabulary.notes` for the notes folder name
- Use `vocabulary.note` / `vocabulary.note_plural` for note type references
- Use `vocabulary.reduce` for the extraction verb
- Use `vocabulary.reflect` for the connection-finding verb
- Use `vocabulary.reweave` for the backward-pass verb
- Use `vocabulary.verify` for the verification verb
- Use `vocabulary.rethink` for the meta-cognitive verb
- Use `vocabulary.topic_map` for MOC references
2. **`ops/config.yaml`** — processing depth, domain context
3. **`ops/derivation.md`** — derivation state and engine version
If these files don't exist, use universal defaults.
## EXECUTE NOW
**Target: $ARGUMENTS**
Parse immediately:
- If target contains a specific skill name (e.g., "upgrade reduce"): check only that skill
- If target contains "--all": check all generated skills
- If target is empty: check all generated skills (same as --all)
**START NOW.** Reference below defines the upgrade process.
---
## Why Consultation, Not Hashing
Skills do not upgrade through hash comparison against a generation manifest. Hash comparison answers a narrow question: "Has this file changed?" Meta-skill consultation answers the right question: "Is this skill's approach still the best approach given what we know?"
A skill could be unchanged but outdated because the knowledge base has grown. Or a skill could be heavily edited by the user but already incorporate the latest thinking through a different path. Reasoning about methodology is more valuable than diffing bytes.
---
## Two Upgrade Paths
Generated skills and meta-skills follow fundamentally different upgrade mechanisms:
For each generated skill (or the specific skill if targeted), consult the plugin's bundled knowledge base to evaluate whether the skill's current approach reflects current best practices.
### Knowledge Base Tiers
Read from the plugin's four content tiers:
| Tier | Path | What It Contains |
|------|------|------------------|
| Methodology graph | `${CLAUDE_PLUGIN_ROOT}/methodology/` | All content — filter by `kind:` field (research/guidance/example) |
| Reference docs | `${CLAUDE_PLUGIN_ROOT}/reference/` | WHAT — structured reference documents and dimension maps |
Notes in `methodology/` are differentiated by their `kind:` frontmatter field:
# Should return nothing — all markers should be resolved
```
4. **Pipeline compatibility** — if pipeline skills were upgraded (/{vocabulary.reduce}, /{vocabulary.reflect}, /{vocabulary.reweave}, /{vocabulary.verify}), verify handoff format compatibility with /ralph
---
## Final Report
```
--=={ upgrade complete }==--
Applied: {N} upgrades
Archived: {N} previous versions to ops/skills-archive/
Skipped: {N} (user-modified, kept as-is)
Changes:
- /{skill}: {what changed} (Research: "{claim}")
- /{skill}: {what changed} (Research: "{claim}")
Validation: {PASS | FAIL with details}
{If any validation failed:}
WARNING: Validation issue detected.
Previous versions available in ops/skills-archive/
for manual rollback.
Note: Run /{vocabulary.verify} on a recent {vocabulary.note}
to confirm upgraded skills work correctly in practice.
```
---
## INVARIANT
**/upgrade never auto-implements.** The upgrade plan is always presented to the user first. The user decides which upgrades to apply. This prevents the cognitive outsourcing failure mode where the system changes itself without human understanding.
All upgrades are advisory. The user owns the files.
---
## Edge Cases
**No improvements available:** Report "All skills reflect current best practices. No upgrades needed." with the count of skills checked.
**No generation manifest:** Treat all skills as version 0 (unknown generation state). Compare methodology against current knowledge base. This is fine — consultation reasons about approach, not version numbers.
**Skill has been user-modified:** Present the side-by-side comparison. Offer three options: keep user version, merge upgrade with customizations, or replace (with archive). Never silently overwrite.
**No ops/derivation-manifest.md:** Use universal vocabulary for all output.
**Plugin knowledge base unavailable:** Report that knowledge base consultation requires the Ars Contexta plugin. Without the plugin's bundled methodology/ and reference/ directories, /upgrade cannot evaluate skills.
**User rejects upgrades consistently:** This is a signal, not an error. Note the pattern — it may indicate the knowledge base recommendations don't match this user's domain. Log to ops/observations/ if it persists across multiple /upgrade runs.
**Correction conflicts with user modification:** When the knowledge base identifies a correction (not just enhancement) but the user has modified the skill, explain the conflict clearly. The user may have modified the skill precisely because the original approach was wrong — their fix may already address the correction. Show both and let the user decide.
**Multiple skills share a change:** If the same knowledge base improvement applies to several skills (e.g., a new search pattern), present it as a single conceptual change affecting multiple skills rather than listing it redundantly per skill.
