diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92c7de5..fd26bb6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Keep changes small and traceable to one runtime invariant. +Keep changes small and traceable to one Skill lifecycle or support invariant. 1. Open an issue for a new capability or policy class. 2. Add a focused regression test before changing behavior. diff --git a/README.md b/README.md index 223c593..ad38e3a 100644 --- a/README.md +++ b/README.md @@ -1,179 +1,178 @@

- Agent Runtime — one control plane for Codex and Claude + Agent Skill Evolution — discover, test, evolve, and remove Agent Skills

-# Agent Runtime +# Agent Skill Evolution -One reversible control plane for engineers who use **Codex and Claude on the -same machine** and are tired of duplicated Hooks, drifting memory, Skill sprawl, -and global configuration that nobody can safely explain or roll back. +**Evolution, not accumulation.** A native-Skill lifecycle system for engineers +who use Codex and Claude and want capabilities to improve without turning their +context into an attic. -[![Tests](https://github.com/hanzw/agent-runtime/actions/workflows/test.yml/badge.svg)](https://github.com/hanzw/agent-runtime/actions/workflows/test.yml) -[![Release](https://img.shields.io/github/v/release/hanzw/agent-runtime)](https://github.com/hanzw/agent-runtime/releases) +[![Tests](https://github.com/hanzw/agent-skill-evolution/actions/workflows/test.yml/badge.svg)](https://github.com/hanzw/agent-skill-evolution/actions/workflows/test.yml) +[![Release](https://img.shields.io/github/v/release/hanzw/agent-skill-evolution)](https://github.com/hanzw/agent-skill-evolution/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +The public capability is the **Skill layer**: discover, update, evaluate, +deduplicate, and remove reusable procedures. Hooks, ReMe, receipts, and +`launchd` are an optional support implementation—not a new kind of capability. + +## Three concepts that should not be mixed + +| Concept | What it actually is | Relationship to this repository | +| --- | --- | --- | +| [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) | A code-first framework for building, orchestrating, evaluating, and deploying agent applications | Compatible, but neither required nor bundled | +| Agent Skill Evolution | Lifecycle governance for portable, natively discovered Agent Skills | The product and public abstraction in this repository | +| [Viktor's “Glorious Evolution”](https://www.leagueoflegends.com/en-gb/champions/viktor/) | A League of Legends fictional narrative about biomechanical transformation | A loose metaphor for deliberate capability improvement only | + +The artwork in this repository is original and depicts capability modules moving +through tests. It does not reproduce Viktor, Riot artwork, logos, costumes, game +UI, or other League of Legends assets. This project is not affiliated with or +endorsed by Riot Games or Google. + ## Who this is for -- Engineers running both Codex and Claude across several repositories. -- Small teams that want autonomous routine work with deterministic hard stops. -- Long-running agent users who need durable history without injecting an - unbounded transcript into every session. -- Skill-heavy setups that need evidence for keep/update/remove decisions. +- Engineers using Codex and Claude across several repositories. +- Skill-heavy setups that install more capabilities than they retire. +- Teams that need one canonical source per capability across project, global, + and plugin scopes. +- Long-running agent users who need bounded durable history without confusing + memory, task state, authorization, and Skills. -It is intentionally macOS-first because the managed ReMe service and health -heartbeat use `launchd`. It is not a model router, multi-agent orchestrator, -prompt collector, or replacement for repository rules. +It is not an ADK, model router, multi-agent orchestrator, prompt collector, or +replacement for repository rules. The optional support installer is macOS-first +because its ReMe service and heartbeat use `launchd`. ## The pain it removes -| Pain | Runtime answer | +| Pain | Skill-layer answer | | --- | --- | -| Codex and Claude execute different global rules | One Hook dispatcher and one policy implementation | -| Several memory systems contradict current code | ReMe stores only durable history; repository state remains current truth | -| More Skills are installed but nothing is removed | Promptfoo ablation supports explicit keep/update/remove decisions | -| Hooks accumulate raw prompts, commands, and secrets | Evidence contains allowlisted metadata and keyed fingerprints only | -| Global edits are risky and hard to reproduce | Versioned releases, atomic writes, receipts, backups, and exact rollback | -| Task state, memory, Skills, and permissions overlap | Each concern has one owner and a documented boundary | +| More Skills are installed but nothing is removed | Explicit discover/update/evaluate/remove lifecycle | +| Project, global, and plugin copies drift | One canonical source per capability | +| Similar Skills compete for attention | Native inventory plus targeted Promptfoo ablation | +| Memory, plans, permissions, and Skills overlap | Each concern has one owner | +| Codex and Claude apply different global controls | Optional shared Hook and policy implementation | +| Global changes are hard to reproduce | Versioned support releases, receipts, backups, and rollback | -## Architecture +## Layer model ```text -Native Skill discovery -> reusable capability truth -Repository files/tests -> current project truth -Buildomator/HANDOFF -> current long-task state +Agent application / ADK -> builds and runs agents +Native Agent Skills -> reusable capability truth +Repository files/tests -> current project truth +Buildomator / HANDOFF -> current long-task state ReMe -> bounded durable history Policy Hooks -> side-effect authorization Promptfoo -> controlled Skill ablation ``` -The runtime does not install a shadow capability registry. Project Skills stay -in their repositories. Upstream Skills stay owned by their upstream GitHub -sources. See [the architecture document](docs/architecture.md) for data flow, -policy classes, privacy guarantees, and failure behavior. - -## Included capabilities - -- Shared Codex and Claude lifecycle Hooks. -- Fail-closed blocking for destructive commands, verification bypasses, - protected-branch direct writes, and unversioned global runtime edits. -- Audit-only classification for production deploy and remote D1 operations; - repository evidence gates retain authority. -- Private, bounded event evidence without raw tool content. -- ReMe `0.4.1.3` on loopback with BM25, wikilinks, project namespaces, and no - embedding/vector database. -- Atomic installation, immutable releases, source provenance, automatic backup, - rollback, health heartbeat, and read-after-write verification. -- `agent-runtime` Skill for audit/install/update/rollback operations. -- `first-principles-checkpoint` Skill for stopping process and context drift. -- `skill-governance` Skill and a two-arm Promptfoo eval template. - -## Install the runtime +Native Codex/Claude discovery remains authoritative. There is no shadow +capability registry. See [the architecture document](docs/architecture.md) for +the ownership boundaries and optional support flow. -Requirements: macOS, Git, Python 3.11, an existing Codex or Claude setup, and -network access during installation so Python can pull pinned ReMe packages from -PyPI. +## Included Skills + +| Skill | Role | +| --- | --- | +| `evolve-skills` | Audit a Skill portfolio, update canonical sources, deduplicate, and remove obsolete capabilities | +| `skill-governance` | Decide keep/update/remove for one uncertain Skill using a minimal Promptfoo ablation | +| `first-principles-checkpoint` | Stop scope and context drift at major decision points | + +Install all three from their canonical GitHub source: ```bash -git clone https://github.com/hanzw/agent-runtime.git -cd agent-runtime -python3 -m unittest discover -s tests -v -python3.11 -m agent_runtime.installer install --source . +npx skills@latest add hanzw/agent-skill-evolution \ + --skill evolve-skills skill-governance first-principles-checkpoint \ + --global --agent codex claude-code --yes ``` -The installer directly pulls these runtime dependencies from their canonical -package source: +If upgrading from v2.0.0, remove the retired abstraction after installing the +replacement: -| Dependency | Role | Adjust when | -| --- | --- | --- | -| [`reme-ai==0.4.1.3`](https://pypi.org/project/reme-ai/) | Local durable-memory MCP and file workspace | ReMe behavior or protocol compatibility changes | -| [`agentscope==2.0.4`](https://pypi.org/project/agentscope/) | ReMe runtime dependency | The pinned ReMe release requires another version | -| Native Codex/Claude Hooks | Lifecycle delivery and Skill discovery | Either runtime changes its Hook schema | +```bash +npx skills@latest remove agent-runtime \ + --global --agent codex claude-code --yes +``` -No dependency source is vendored and the installer does not rewrite unrelated -MCP package versions. +`skill-governance` uses the upstream `promptfoo-evals` and +`promptfoo-provider-setup` Skills rather than copying them: -### What installation changes +```bash +npx skills@latest add promptfoo/promptfoo \ + --skill promptfoo-evals promptfoo-provider-setup \ + --global --agent codex claude-code --yes +``` -- `CODEX_HOME/hooks.json`: replaces the user-level Hook graph. -- `CLAUDE_HOME/settings.json`: replaces only the `hooks` field. -- `CODEX_HOME/config.toml`: enables Hooks, sets `workspace-write`, `on-request`, - `auto_review`, workspace network access, and the loopback ReMe MCP. -- Claude's user configuration: adds or updates only the `reme` MCP entry. -- Global Codex and Claude instructions: adds or replaces only `Memory Model`. -- `AGENT_RUNTIME_HOME`: writes private releases, backups, receipts, state, and - the pinned ReMe environment. -- The user LaunchAgents directory: installs runtime heartbeat and ReMe services. +Already-running agents normally discover Skill changes on their next turn or +session. Buildomator is the current name for GSD 4.x; use `/bm:` for new task +state commands. -The installer does **not** delete Skills, migrate personal logs, remove other -MCP servers, or edit project repositories. +## Optional support layer -## Install the Skills +The repository also contains a small shared implementation for Codex and Claude: -The native [`skills`](https://www.npmjs.com/package/skills) installer pulls each -Skill directly from its canonical GitHub repository: +- one lifecycle Hook dispatcher and deterministic side-effect policy; +- private bounded evidence without raw prompts, commands, or tool payloads; +- ReMe `0.4.1.3` with BM25, project namespaces, and bounded recall; +- atomic installation, immutable releases, provenance, backup, rollback, and + health verification. -| Skill | Role | Adjust when | -| --- | --- | --- | -| `agent-runtime` | Audit, install, update, diagnose, and roll back the runtime | Managed files, service model, or verification changes | -| `first-principles-checkpoint` | Stop scope/context drift and choose the next smallest proof | The subtraction decision rule changes | -| `skill-governance` | Decide keep/update/remove for one Skill | Lifecycle evidence requirements change | -| `promptfoo-evals` | Author and run controlled eval suites | Cases or assertions change | -| `promptfoo-provider-setup` | Connect Promptfoo to the evaluated runtime | Authentication or provider mapping changes | +Requirements: macOS, Git, Python 3.11, an existing Codex or Claude setup, and +network access to the canonical Python package sources. ```bash -npx skills@latest add hanzw/agent-runtime --skill agent-runtime \ - --global --agent codex claude-code --yes -npx skills@latest add hanzw/agent-runtime --skill skill-governance \ - --global --agent codex claude-code --yes -npx skills@latest add hanzw/agent-runtime --skill first-principles-checkpoint \ - --global --agent codex claude-code --yes -npx skills@latest add promptfoo/promptfoo --skill promptfoo-evals \ - --global --agent codex claude-code --yes -npx skills@latest add promptfoo/promptfoo --skill promptfoo-provider-setup \ - --global --agent codex claude-code --yes +git clone https://github.com/hanzw/agent-skill-evolution.git +cd agent-skill-evolution +python3 -m unittest discover -s tests -v +python3.11 -m agent_runtime.installer install --source . ``` -Already-running agents discover newly installed Skills on their next turn or -session. Buildomator is the current name for GSD 4.x; use `/bm:` for new task -state commands. +The internal package remains named `agent_runtime` because it implements Hook, +policy, memory, and service execution. It is deliberately not exposed as a +Skill capability. + +| Dependency | Support role | +| --- | --- | +| [`reme-ai==0.4.1.3`](https://pypi.org/project/reme-ai/) | Local durable-memory MCP and file workspace | +| [`agentscope==2.0.4`](https://pypi.org/project/agentscope/) | Pinned ReMe dependency | +| Native Codex/Claude Hooks | Lifecycle delivery and side-effect policy | + +No dependency is vendored. The installer does not delete Skills, migrate +personal logs, remove unrelated MCP servers, or edit project repositories. + +### Managed changes -## Update +- Codex and Claude user Hook configuration; +- the minimum Codex policy fields and loopback ReMe MCP entry; +- only the global `Memory Model` instruction section; +- private releases, backups, receipts, evidence, and ReMe environment; +- two user-level `launchd` services. + +## Update and roll back ```bash git pull --ff-only python3 -m unittest discover -s tests -v python3.11 -m agent_runtime.installer install --source . -npx skills@latest update agent-runtime skill-governance \ +npx skills@latest update evolve-skills skill-governance \ first-principles-checkpoint --global --yes ``` -## Roll back - -Every successful install prints and records its exact backup path in the -runtime receipt. +Every support-layer installation records an exact backup path: ```bash python3.11 -m agent_runtime.installer rollback \ --backup ``` -Rollback restores managed configuration bytes and prior service definitions. -It never deletes immutable runtime releases or evidence directories. - -## Adjust policy without growing another framework - -Policy behavior lives in `agent_runtime/policy.py`; every changed rule requires -a focused case in `tests/test_policy_runtime.py`. Memory limits live in -`agent_runtime/memory.py` and `agent_runtime/reme-minimal.yaml`. Installation -targets live in `agent_runtime/installer.py`. - -That is the entire configuration surface. Add a new abstraction only after a -second real use case proves it is needed. +## Small configuration surface -## Security +- Skill lifecycle rules: `skills/evolve-skills` and `skills/skill-governance`. +- Side-effect policy: `agent_runtime/policy.py` plus focused tests. +- Memory bounds: `agent_runtime/memory.py` and `reme-minimal.yaml`. +- Installation targets: `agent_runtime/installer.py`. -Read [SECURITY.md](SECURITY.md) before installation. The installer changes -user-level agent configuration and should be reviewed like any other execution -policy. Report vulnerabilities through GitHub private security advisories. +That is the full configuration surface. Add an abstraction only after a second +real use case proves it is needed. +Read [SECURITY.md](SECURITY.md) before installing the optional support layer. MIT licensed. Banner generated for this repository with OpenAI image generation. diff --git a/SECURITY.md b/SECURITY.md index d2bc36c..c9dec51 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -17,10 +17,10 @@ behavior, and the smallest redacted evidence that proves the issue. This project installs user-level Codex and Claude Hooks and therefore executes for every managed lifecycle event. Review source and tests before installation. -The runtime is not an operating-system sandbox and does not replace repository -authorization, branch protection, CI, account permissions, or provider-side -credential controls. +The optional support runtime is not an operating-system sandbox and does not +replace repository authorization, branch protection, CI, account permissions, +or provider-side credential controls. -The intended privacy guarantee is narrower: runtime evidence never stores raw +The intended privacy guarantee is narrower: support evidence never stores raw prompts, commands, tool payloads, tool outputs, secrets, cookies, or full paths. Treat any violation of that guarantee as a security issue. diff --git a/assets/agent-runtime-banner.png b/assets/agent-runtime-banner.png deleted file mode 100644 index 2ea5f3d..0000000 Binary files a/assets/agent-runtime-banner.png and /dev/null differ diff --git a/assets/agent-skill-evolution-banner.png b/assets/agent-skill-evolution-banner.png new file mode 100644 index 0000000..a29b453 Binary files /dev/null and b/assets/agent-skill-evolution-banner.png differ diff --git a/docs/architecture.md b/docs/architecture.md index 6d940da..20c298d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,9 +1,21 @@ -# Architecture +# Skill Evolution Architecture -Agent Runtime is a user-level control plane shared by Codex and Claude. It -coordinates lifecycle policy and bounded durable memory while deliberately -leaving project truth, task orchestration, and Skill discovery to their native -owners. +Agent Skill Evolution treats the native Skill as the reusable capability unit. +The repository also includes an optional user-level support runtime shared by +Codex and Claude, but that implementation does not become a capability registry. + +## Terminology boundary + +| Layer | Responsibility | Not responsible for | +| --- | --- | --- | +| ADK or agent application framework | Build, orchestrate, evaluate, and deploy agent applications | Governing every installed native Skill | +| Native Agent Skill | Package reusable instructions, workflows, tools, and resources | Long-task state, memory, or authorization | +| Skill evolution | Discover, update, evaluate, deduplicate, and remove Skills | Running an agent application | +| Support runtime | Deliver Hooks, enforce side-effect policy, recall bounded history | Defining a second capability type | + +“Glorious Evolution” is only a fictional visual metaphor. The architecture is a +practical Skill lifecycle and has no game mechanics, character model, or Riot +asset dependency. ## First principles @@ -19,13 +31,13 @@ owners. | Concern | Canonical owner | Explicit non-owner | | --- | --- | --- | | Current code and operational truth | Repository, tests, contracts, live reads | ReMe | -| Reusable procedure | Native Codex/Claude Skill discovery | Runtime registry | +| Reusable procedure | Native Codex/Claude Skill discovery | Support runtime registry | | Current long-task continuation | Buildomator STATE or HANDOFF | ReMe | | Durable cross-session history | ReMe | Task state files | | Side-effect authorization | Policy Hooks plus repository evidence gates | Skills | | Skill lifecycle evidence | Promptfoo ablation | Production telemetry | -## Runtime flow +## Support runtime flow ```mermaid flowchart LR @@ -48,7 +60,7 @@ policy classification and evidence. The default policy is intentionally small: -| Effect | Runtime behavior | +| Effect | Support behavior | | --- | --- | | Broad destructive filesystem or Git operation | Block | | Verification bypass | Block | @@ -60,7 +72,7 @@ The default policy is intentionally small: | Exact single `git stash drop stash@{N}` | Allow | | Unclassified routine work | Allow | -The runtime does not encode application names, database names, deployment +The support runtime does not encode application names, database names, deployment accounts, or business authorization. Those belong in each repository. ### Evidence schema @@ -82,7 +94,7 @@ atomic replacement. Event files rotate at a bounded size. ## Memory model -The runtime pins ReMe `0.4.1.3` and AgentScope `2.0.4` in a private Python 3.11 +The support runtime pins ReMe `0.4.1.3` and AgentScope `2.0.4` in a private Python 3.11 environment. ReMe runs as a loopback MCP service with a file-native workspace. The supplied profile intentionally enables only: @@ -100,9 +112,9 @@ to global memory plus the current repository's hashed namespace. Git worktrees resolve to the main repository namespace; submodules retain independent namespaces. -## Skill model +## Skill evolution model -The runtime does not copy, rank, or promote Skills. Native discovery remains +The support runtime does not copy, rank, or promote Skills. Native discovery remains authoritative: ```text @@ -111,6 +123,10 @@ user-global Skills -> reusable procedure across projects plugin Skills -> versioned upstream capabilities ``` +`evolve-skills` owns portfolio-level inventory, canonical-source selection, +updates, deduplication, and removal. It delegates uncertain value decisions to +`skill-governance` instead of duplicating the evaluation procedure. + `skill-governance` adds a controlled two-arm Promptfoo evaluation for one Skill at a time. It requires the same model and task in baseline and treatment arms, confirms actual Skill loading, and returns keep/update/remove evidence. It is @@ -168,6 +184,9 @@ The macOS installation creates: - `io.github.hanzw.agent-runtime`: six-hour health and permissions heartbeat; - `io.github.hanzw.agent-runtime.reme`: persistent loopback ReMe service. +These service labels remain stable during the v2 line for upgrade compatibility; +their names describe the internal implementation, not a public Skill capability. + Both run at user level. ReMe uses a restrictive umask, private workspace permissions, and local-only transport. `--no-launchd` exists for synthetic test homes and unsupported environments; it does not provide a production service @@ -186,7 +205,7 @@ This repository does not provide: - PageIndex, Buildomator, or Promptfoo as bundled dependencies. Those systems may integrate at their documented boundary without becoming part -of the runtime. +of the Skill layer. ## Where to adjust behavior @@ -197,6 +216,7 @@ of the runtime. | Change ReMe capabilities | `agent_runtime/reme-minimal.yaml` | Profile and live smoke test | | Change managed files or lifecycle graph | `agent_runtime/installer.py` | Install, idempotency, rollback tests | | Change Skill decision rules | `skills/skill-governance` | Promptfoo ablation | +| Change portfolio lifecycle rules | `skills/evolve-skills` | Native before/after discovery | Avoid adding a generic configuration layer for a one-off rule. The source plus focused tests is the intended five-minute explanation surface. diff --git a/skills/agent-runtime/SKILL.md b/skills/agent-runtime/SKILL.md deleted file mode 100644 index 4b7884a..0000000 --- a/skills/agent-runtime/SKILL.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -name: agent-runtime -description: > - Install, audit, update, diagnose, or roll back the shared Codex and Claude - global runtime in this repository. Use when managing lifecycle Hooks, - deterministic side-effect policy, ReMe memory, runtime receipts, launchd - services, or the boundary between native Skills, task state, and memory. ---- - -# Agent Runtime - -Manage one reversible global runtime without creating a second Skill registry -or copying project rules into global configuration. - -## Invariants - -- Treat repository code and tests as the runtime source of truth. -- Treat native Codex/Claude discovery as the Skill source of truth. -- Keep ReMe for durable history and Buildomator/HANDOFF for current task state. -- Preserve project-local Skills, user logs, unrelated MCP servers, and unrelated - instruction sections. -- Never store prompts, tool payloads, command text, secrets, or raw transcripts - in runtime evidence. -- Require an exact backup path for rollback. - -## Audit - -1. Inspect `~/.agent-runtime/install-receipt.json`. -2. Resolve the receipt's release, backup, source revision, and dirty flag. -3. Inspect native Hook files and ReMe MCP entries without changing them. -4. Read `~/.agent-runtime/state/heartbeat.json`; do not infer health from process - presence alone. -5. Run the repository tests before recommending an update: - - ```bash - python3 -m unittest discover -s tests -v - ``` - -6. Report verified state separately from intended changes. - -## Install or Update - -1. Confirm the repository and branch are the intended source. -2. Preserve a dirty worktree; do not install from it unless the user explicitly - accepts `source_dirty=true` provenance. -3. Run tests and inspect the pending diff. -4. Install from the checked-out source: - - ```bash - python3.11 -m agent_runtime.installer install --source . - ``` - -5. Read back the receipt, Hook files, ReMe health, and release path. -6. State that already-running agents discover new Skills on their next turn or - session; do not claim an in-flight tool call was reconfigured. - -Use `--no-launchd` only for synthetic validation or unsupported environments. - -## Roll Back - -1. Resolve the exact backup from the receipt or backup directory. -2. Verify its `manifest.json` exists. -3. Run: - - ```bash - python3.11 -m agent_runtime.installer rollback \ - --backup - ``` - -4. Read back every restored managed file and service state. - -## Scope - -Change policy behavior in `agent_runtime/policy.py` together with focused tests. -Change memory bounds in `agent_runtime/memory.py` or `reme-minimal.yaml`. Change -installation targets only in `agent_runtime/installer.py`. Do not add a generic -configuration framework for a single policy change. - -## Report - -Return runtime revision, receipt, ReMe status, tests run, files changed, policy -effects, installation or rollback result, and the exact recovery command. diff --git a/skills/agent-runtime/agents/openai.yaml b/skills/agent-runtime/agents/openai.yaml deleted file mode 100644 index bde230e..0000000 --- a/skills/agent-runtime/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Agent Runtime" - short_description: "Install, audit, update, or roll back the global runtime" - default_prompt: "Use $agent-runtime to inspect and safely manage the Codex and Claude global runtime." diff --git a/skills/evolve-skills/SKILL.md b/skills/evolve-skills/SKILL.md new file mode 100644 index 0000000..0eeba97 --- /dev/null +++ b/skills/evolve-skills/SKILL.md @@ -0,0 +1,88 @@ +--- +name: evolve-skills +description: > + Audit and evolve a native Codex or Claude Skill portfolio by locating + canonical sources, updating upstream-managed Skills, finding true duplicates, + evaluating uncertain value, and removing capabilities that no longer earn + their context or maintenance cost. Use for cross-project Skill cleanup, + consolidation, upgrade, deduplication, lifecycle review, or when a setup keeps + installing Skills without retiring obsolete ones. +--- + +# Evolve Skills + +Improve the native Skill layer without creating a registry, framework, or +second capability abstraction. + +## Invariants + +- Treat native Codex/Claude discovery as the only capability inventory. +- Keep one canonical source for each capability. +- Prefer upstream GitHub packages over copied Skill bodies. +- Preserve genuinely project-specific Skills in their repositories. +- Read a Skill before changing it; update or remove stale instructions instead + of appending contradictions. +- Separate reusable capability from task state, memory, and authorization. +- Never collect raw prompts, secrets, or production telemetry for lifecycle + decisions. + +## Workflow + +1. Inventory installed Skills and their sources: + + ```bash + npx skills@latest list --global + ``` + +2. Group only genuine overlaps by claimed outcome and trigger. Similar names do + not prove duplication. +3. For each overlap, identify the canonical source in this order: + project-specific customization, user-global reusable Skill, versioned + upstream plugin. +4. Update upstream-managed candidates before comparing them: + + ```bash + npx skills@latest update --global --yes + ``` + +5. Remove byte-identical copies, stale wrappers, broken references, and obsolete + aliases when one canonical source already covers the same trigger and + workflow. +6. When value remains uncertain, invoke `skill-governance` for a controlled + baseline-versus-Skill Promptfoo ablation. Do not recreate its evaluation + procedure here. +7. Apply the smallest supported lifecycle change through the native manager: + + ```bash + npx skills@latest remove \ + --global --agent codex claude-code --yes + ``` + +8. Re-run native discovery. Confirm the intended Skill is present exactly once, + removed aliases are absent, and project-local Skills were preserved. + +## Layer Boundary + +```text +ADK or application framework -> builds and runs agent applications +Native Agent Skills -> reusable procedures and domain capability +Buildomator or HANDOFF -> current long-task state +ReMe -> bounded durable history +Policy Hooks -> side-effect authorization +``` + +Do not represent the support runtime, memory service, or task orchestrator as a +Skill capability. They may support Skill use, but they do not replace the native +Skill layer. + +## Stop Conditions + +Stop after native discovery is unambiguous and every change has a source, +reason, verification, and rollback path. Do not add dashboards, shadow +registries, universal scoring, or another orchestration framework. + +## Report + +Return the before/after inventory, canonical sources, updated and removed +Skills, evidence for each decision, discovery validation, preserved +project-local capabilities, and exact reinstall commands. diff --git a/skills/evolve-skills/agents/openai.yaml b/skills/evolve-skills/agents/openai.yaml new file mode 100644 index 0000000..2ecd53b --- /dev/null +++ b/skills/evolve-skills/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Evolve Skills" + short_description: "Keep, update, deduplicate, or remove Agent Skills" + default_prompt: "Use $evolve-skills to audit my installed Skills and apply the smallest evidence-backed lifecycle changes."