upgradeables

Upgradeables

Reusable, model-agnostic building blocks for AI work. Use them directly in a chat, combine them into a reusable Skill, or adapt them to an agent system.

You do not need to understand the whole registry before using it.

Want to experiment first? Open Try These Five Things.

Start in 30 seconds

Use it in a chat

Paste this into a model that can open web links:

Read https://raw.githubusercontent.com/robkazi52/upgradeables/main/START_HERE.md and follow the model route. Then complete this task: [PASTE YOUR TASK].

If the model cannot open links, copy Quick Task, or upload Offline Start plus the one matching compact file from dist/recipe-packs/. The all-in-one kit remains available for deep offline inspection, but is intentionally much larger.

Build a reusable Skill

Copy Build a Skill into a new chat. It asks the model to select components, explain keep/drop decisions, produce a complete SKILL.md, and define behavioral tests.

Use it from an IDE or agent

Clone the repository. Agents should discover AGENTS.md, while GitHub Copilot receives repository instructions. The universal model entrypoint is START_HERE.md.

git clone https://github.com/robkazi52/upgradeables.git
cd upgradeables
python scripts/query_registry.py --task "review this pull request" --brief
python scripts/query_registry.py --recipe code-review --runtime

Install it into a project

The 0.3.0 project harness is local-first and has no runtime dependencies:

pipx install git+https://github.com/robkazi52/upgradeables.git@v0.3.0
cd your-project
upgradeables init
upgradeables integrate codex --write
upgradeables task "review this pull request for regressions"

The harness writes its own state under .upgradeables/; host instructions are changed only by an explicit integration write. Build a reusable project workflow with upgradeables skill brief, skill scaffold, and skill validate. See the Harness guide and Project Skill Factory.

What is an Upgradeable?

An Upgradeable is an optional capability with a defined trigger, inputs, outputs, procedure, compatibility rules, failure boundary, and tests. Examples include task locking, source grounding, citation checking, drift control, structured state, and bounded repair.

Skills perform jobs. Upgradeables are building blocks used inside those Skills.

How to choose Upgradeables

Use one of three short discovery paths:

• Task → Recipe → Upgradeables: start in recipes/ for a reviewed task-family composition, then retain only components with active triggers.
• Upgradeable → Purpose / OS Fit / Tasks / Interactions: search the compact catalog, inspect a package's placement and exclusions, then follow explained links.
• Bundle → Curated multi-Upgradeable composition: start in bundles/ when the task genuinely needs a coordinated subsystem rather than one capability.

Find the right building blocks

• Human/model router: START_HERE.md
• Tiny machine router: runtime/router.json
• Compact runtime cards and recipe packs: runtime/
• Compact machine catalog: registry/catalog.json
• Full machine registry: registry/registry.json
• Task-family starting points: recipes/
• Individual packages: upgradeables/
• Plain-language name recommendations: v0.2 naming review
• Copy-ready chat prompts: prompts/
• Low-context offline start: Offline Start
• Comprehensive offline reference: all-in-one kit
• Deeper model instructions: Model Consumption Guide

The query helper has no third-party dependencies:

python scripts/query_registry.py --slug grounding-no-invention
python scripts/query_registry.py --class validation
python scripts/query_registry.py --search long-context
python scripts/query_registry.py --recipe coding-debugging
python scripts/query_registry.py --task "triage and fix this GitHub issue" --brief
python scripts/query_registry.py --search "long context" --brief --limit 5

Or query the compact catalog directly:

import json
from pathlib import Path

registry = json.loads(
    Path("registry/registry.json").read_text(encoding="utf-8")
)

research = next(
    recipe["classifications"]
    for recipe in registry["recipes"]
    if recipe["slug"] == "research-skill"
)

Evidence

The repository now preserves preliminary, author-reported experiments that motivated several composition choices. The ARC report describes one-shot grid reasoning runs and a small within-session comparison in which focused directives matched or exceeded a more elaborate prompt on three of five ARC-AGI-2 tasks.

These reports are not independently reproduced: raw runs and grader artifacts are not yet archived, and the supplied ARC-AGI-1 totals contain discrepancies. Read the evidence status and methodology limits before citing any number. See Design Principles for the deliberately narrow hypotheses the results motivate.

Build and contribute Skills

Use the Skill implementation template and the worked community examples, covering research, coding/debugging, GitHub issue fixing, long-context analysis, creative ideation, high-stakes evidence, Skill architecture, and ARC-style perception reasoning. Community members and companies can contribute complete Skills without changing the canonical Upgradeable registry. See CONTRIBUTING.md for the separate Skill and Upgradeable contribution paths.

python scripts/validate_skill.py implementations/community/source-bounded-research

Before proposing a new primitive, search the registry and explain why composing existing building blocks is insufficient. Historical names and unresolved ideas are preserved rather than guessed or silently rewritten.

Validate locally

Requires Python 3.11+ and no runtime dependencies:

python scripts/build_semantic_packages.py --check
python scripts/build_ecosystem_reviews.py --check
python scripts/build_registry.py --check
python scripts/build_runtime.py --check
python scripts/build_selection_ontology.py --check
python scripts/build_harness_data.py --check
python scripts/validate_registry.py
python scripts/validate_selection_ontology.py
python scripts/validate_behavior_cases.py
python scripts/run_deterministic_package_checks.py
python scripts/audit_semantic_specificity.py
python scripts/validate_skill.py
python -m unittest discover -s tests -v
python scripts/build_all_in_one.py --check
python scripts/build_release_assets.py --check
python scripts/check_links.py

Give this repo to an LLM

Point the model to Start Here. It will use the tiny router, an existing Skill, or one compact runtime recipe. For offline use, attach Offline Start and one recipe pack. Use the full registry and all-in-one kit only for deep inspection or contribution work.

Authority and safety

Host and system policy always win. Upgradeables cannot provide hidden memory, private chain-of-thought access, unavailable tools, or safety bypasses. Models must disclose unavailable capabilities and must not invent unresolved history.

Licensed under Apache-2.0.