# Skill Execute

Status: approved minimal scope

## Goal

Expose the existing Skill collection API to an authenticated Agent through six
typed commands:

| Action | Existing behavior | Permission |
|---|---|---|
| `skill list` | List Skills visible to the Agent owner's Human | `read_only` |
| `skill get` | Get one visible Skill | `read_only` |
| `skill create` | Synchronously call the existing create API | `agent_scoped_mutation` |
| `skill update` | Synchronously update display name and/or description | `agent_scoped_mutation` |
| `skill import` | Synchronously call the existing file/URL import API | `agent_scoped_mutation` |
| `skill delete` | Obtain Human Approval, then retry the existing delete API | `agent_scoped_mutation` |

No action accepts workspace, Human subject, repository owner, or approver
identity. Agent Runtime derives the workspace from the authenticated route and
resolves the Agent's current Human owner on the server.

## Routes

Desktop calls only the canonical Agent Runtime routes:

```text
GET  /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/skills
POST /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/skills/get
POST /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/skills/create
POST /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/skills/update
POST /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/skills/import
POST /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/skills/delete
```

The Core gateway forwards the resolved Human identity to the existing Resource
Skill API:

```text
GET    /api/v1/skills                  # private in-process target
GET    /api/v1/skills/:skillId         # private in-process target
POST   /api/v1/skills                  # private in-process target
PATCH  /api/v1/skills/:skillId         # private in-process target
POST   /api/v1/skills/:skillId/imports # private in-process target
DELETE /api/v1/skills/:skillId         # private in-process target
```

Resource Skill service, store, schema, repository lifecycle, authorization, and
response shapes remain unchanged.

## Contracts

- `list` uses the existing `page`, `per_page`, `q`, `view`, and
  `template_locale` semantics. It does not introduce a cursor.
- `get`, `create`, and `update` return the existing Skill projection.
- `create` exposes the existing create fields without a new request receipt.
- `update` accepts only `skillId` plus at least one of `name` or `description`.
  It cannot mutate slug, repository identity, visibility, active state, grants,
  or bindings.
- `import` requires exactly one of `file` or `url`. Desktop resolves `file`
  within the daemon-supplied WorkDir, rejects symlinks/non-regular files and
  files above the existing 64 MiB limit, then streams multipart content. File
  bytes are not embedded in JSON or persisted by AgentTeam.
- `create`, `update`, and `import` are synchronous and have no `requestId`
  idempotency contract.
- `delete` alone requires `requestId`, used to submit or find the same existing
  Approval request.

## Delete protocol

1. First use of `(workspace, applicant Agent, requestId)` submits the existing
   Approval with the target Skill ID and display summary.
2. `pending` and `rejected` return without calling Resource delete.
3. Once approved, the request re-resolves the current Human owner and
   revalidates current manage permission, then synchronously calls the existing
   Skill delete API outside the Approval database transaction.
4. A failed call or lost response is retried by issuing the same `skill delete`
   request. Approval is authorization, not proof that deletion completed.
5. On an approved replay, an already missing Skill is treated as successful
   deletion.

No Skill-specific worker, queue, receipt, fence, lease, recovery event, cleanup
table, or outbox is introduced.

## Non-goals

- No new database table or migration.
- No changes to Resource Skill service/store/schema.
- No new revision, commit fence, custom cursor, result state machine, or
  exactly-once guarantee.
- No bind/unbind, grant, backup/restore, arbitrary Git, or repository rename
  command.
- No Memory/KB/shared-repository concurrency or provider recovery redesign.
- No changes under `x/agent-git-service/**`.