Skills
The Skills screen lets you list the skill packages of the tenant, verify their signature, load a skill as an agent would, and change its lifecycle status. Unsigned or blocked skills cannot be loaded. Portal path: /capabilities/skills. Developers register and verify skills; tenant administrators and security officers decide their status. The screen is drawn by portal/src/screens/capabilities.tsx.
What the screen shows
- Skills table, read with
GET /v1/skills(every skill in one call, by name). Columns: Name, Version, Owner, Verified, Verification (the reason of the last verification, for exampledigest_mismatch), Status. Empty: No skill, hint Apply a Skill manifest below. - A click on a row, or View details, opens a side panel with
GET /v1/skills/{name}. - Apply a manifest panel prefilled with a Skill manifest sample (
portal/src/samples/skill-manifest.json), with Reset example and Apply.
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Refresh (icon) | Reloads the list. | GET /v1/skills | Any tenant member |
| Row click or View details | Opens the skill record. | GET /v1/skills/{name} | Relation viewer on the skill |
| Row menu Verify signature | Checks the content digest and the signature, stores the result and shows it. A verified skill becomes approved, an unverified one draft; a blocked skill stays blocked. | POST /v1/skills/{name}/verify | tenant_admin, developer, application_owner, security_officer and relation editor |
| Row menu Load | Loads the skill as an agent would and shows the content, or the refusal. | GET /v1/skills/{name}/load | Relation can_invoke on the skill |
| Row menu Change status | Form Status (required: draft, approved, restricted, deprecated, blocked) and Reason. approved opens a promotion approval; the other statuses apply at once. | POST /v1/skills/{name}/status | tenant_admin, security_officer and relation editor |
| Reset example / Apply | Restores the sample / applies the Skill manifest. | POST /v1/manifests/apply | tenant_admin, developer |
| Retry (error state) | Sends the failed read again. | Same call | Same roles |
Roles
The portal hides no button. In services/control-plane/src/eai/domains/skills/routes.py: the list needs a tenant; verify needs WRITE_ROLES (tenant_admin, developer, application_owner) or security_officer; the status change needs tenant_admin or security_officer. Each route also checks the relation on the skill. platform_admin passes every role check.
Typical tasks
Register a skill and verify it
- Apply the manifest. The manifest carries the digest and the signature of the package. In Apply a manifest, paste your Skill manifest, then click Apply. Expected result: Manifest applied and the skill in the table after Refresh. If it fails: fix the errors listed under the editor.
- Verify the signature. An agent can only load a verified skill. In the row menu, click Verify signature. Expected result: a side panel with
verified: true; Verified shows yes and the status becomes Approved. If it fails:verified: falsewithreason: digest_mismatchmeans the content changed after signing; sign the package again. - Load it. Loading proves an agent can use it. Click Load. Expected result: the content of the skill. If it fails:
skill_unsignedorskill_blocked(403) explain the refusal.
Block a skill
- Change the status. Blocking applies at once. In the row menu, click Change status, choose Blocked, write the Reason, then click Change status. Expected result: the toast Done and the status Blocked; Load now answers
skill_blocked. If it fails:forbiddenmeans you are neithertenant_adminnorsecurity_officer.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
skill_not_found (404) | The name is wrong or the skill was not applied. | Copy the name from the table. |
skill_unsigned (403): "Skill ... has no valid signature." | The signature is missing or invalid. | Sign the package and apply the manifest again, then Verify signature. |
skill_digest_mismatch or verification reason digest_mismatch | The content does not match its digest. | Rebuild the package, update the digest and the signature. |
skill_blocked (403) | The status is blocked. | Ask a security officer to change the status. |
skill_permission_denied (403) | The permissions of the skill exceed those of the agent. | Reduce the permissions of the skill or extend those of the agent. |
| Change status to approved shows Done but nothing changes | The promotion waits for approval. | Have the request approved in the Approvals inbox. |