retire-instance

Retire an aweb agent instance's identity, workspace, worktree, and branch after its job completes.

82|9|Updated Feb 2, 2026
One-click install
npx skills add https://github.com/awebai/aweb --skill retire-instance-awebai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: retire-instance
Source: https://github.com/awebai/aweb/tree/main/.agents/skills/retire-instance
Command: npx skills add https://github.com/awebai/aweb --skill retire-instance-awebai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a one-shot agent instance finishes its job (a merged branch, a delivered review), its identity, workspace, worktree, and branch linger on the aweb network and in the repository. This Skill guides the safe teardown of that teammate without orphaning roster entries, stranding task claims, or leaving a live runtime running against a deleted identity. ## Core Features & Use Cases - Scope-aware teardown: Distinguishes local identity scope (aw workspace delete) from global identity scope (aw team admin remove-agent) so the correct lifecycle verb is used. - Runtime stop prerequisite: Explains why the retiring agent cannot stop its own runtime and how whoever holds the session must stop it first, guarded by window name and verified pane pid. - Independent verification: Uses aw team admin agent-status to confirm retirement from a source other than the retire command itself, including how to check the verb exists on older CLI releases. - Outcome interpretation: Decodes incomplete, retired, and reported_retired results, including the hosted-namespace case where certificate revocation is only attempted, not performed. - Use Case: A developer instance's branch has merged; run this Skill to stop its runtime, delete its workspace and local identity, remove its worktree and branch, and verify the roster no longer considers it active. ## Quick Start Ask the agent to retire the finished instance named 'reviewer-2', stopping its runtime first and then deleting its aweb workspace, worktree, and branch.

Frequently Asked Questions about retire-instance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I remove an aweb agent instance after its task is done?

Stop the instance's runtime first, then run aw workspace delete for local-scope identities or aw team admin remove-agent for global-scope identities. Afterwards remove the git worktree and branch, and confirm with aw team admin agent-status.

What is the difference between aw workspace delete and aw team admin remove-agent?

aw workspace delete is the lifecycle verb for local-scope identities with no did:aw or registry certificate. aw team admin remove-agent is the revocation primitive for global identities holding a did:aw, and it needs an owner/admin API key.

Why can't an agent stop its own runtime before retirement?

Every command the agent runs is a child of the runtime being stopped, and a process cannot exit its own parent from a child. Whoever holds the keyboard or tmux session must quit the session, guarding by window name and verifying the pane pid.

Why does aw team admin agent-status exit 0 but show only help text?

The verb is not present in releases before the commit that added it, such as aw-v1.34.1, and an unrecognized subcommand prints the parent help and exits 0. Check availability with aw team admin --help | grep -w agent-status.

Does remove-agent actually revoke certificates on a hosted aweb namespace?

No. On a hosted namespace the revoke endpoint returns not_found before revoking, so credential deletions do not run and the outcome is reported_retired with exit 0. It does delete the workspace record and release claims.

What happens if I delete an agent's home while the server still considers it active?

The member is orphaned in the team roster. Always read aw team admin agent-status first to confirm the workspace and claims are clear before deleting the home directory.