Skill studio

The Skill studio screen lets you write a Skill manifest and its SKILL.md, check them live and on the server against the skill-manifest contract, save them as a new version and verify the digest and the signature of the stored version. Portal path: /studio/skills. It is used by developers and tenant administrators who build skills for agents.

What the screen shows

• On the left, the list of the skills (GET /v1/skills), paginated, with New on top. An empty list shows No skill yet.
• Editor tab:
  • Manifest (JSON): a JSON editor checked live against the skill-manifest JSON Schema of contracts/v1 (schemas read with GET /v1/contracts/{name}), with the editor problems and Invalid JSON: ... when the text does not parse.
  • SKILL.md: the instructions loaded by the Skill Loader, stored inline in spec.instructions.
  • The buttons Validate on the server and Create (new skill) or Save as a new version (opened skill), then the result Valid against contracts/v1 or Invalid against contracts/v1 with the errors, and the answer of the save.
• Test tab, once a saved skill is open: Signature with the Verify button and its JSON answer.
• Opening a skill reads its stored manifest with GET /v1/manifests/{kind}/{name} (kind Skill).

Actions

Button or action	What it does	API call	Roles
New	Loads the starter manifest new-skill and its SKILL.md.	None	Everyone
Click a skill in the list	Loads its manifest and its SKILL.md.	GET /v1/manifests/{kind}/{name}	Every signed in user
Validate on the server	Validates the manifest (with SKILL.md inline) against skill-manifest.	POST /v1/contracts/{name}/validate	Every signed in user
Create	Applies the new manifest.	POST /v1/manifests/apply	tenant_admin, developer
Save as a new version	Applies the manifest with the patch number of metadata.version raised by one (0.1.0 becomes 0.1.1).	POST /v1/manifests/apply	tenant_admin, developer
Verify (tab Test)	Verifies the digest and the signature of the stored version.	POST /v1/skills/{name}/verify	tenant_admin, developer, application_owner, security_officer (and the editor relation on the skill)
Retry (error state)	Reads the list or the schemas again.	GET /v1/skills or GET /v1/contracts/{name}	Every signed in user

Roles

The portal enables Create and Save as a new version for STUDIO_WRITERS (tenant_admin, developer) and shows Saving requires the tenant_admin or developer role. otherwise. POST /v1/manifests/apply requires the same two roles (services/control-plane/src/eai/domains/contracts/__init__.py). POST /v1/skills/{name}/verify requires tenant_admin, developer, application_owner or security_officer plus the editor relation on the skill (services/control-plane/src/eai/domains/skills/routes.py).

Typical tasks

Create a skill

1. Start from the template. It carries every required field. Click New. Expected result: the manifest new-skill version 0.1.0 and a SKILL.md. If it fails: reload the page.
2. Edit the manifest. Set metadata.name, metadata.owner, spec.description and spec.permissions. Expected result: No problem found by the editor. If it fails: fix each line named in the problem list.
3. Write SKILL.md. The agent reads these instructions. Describe when to use the skill, its steps and its tools. Expected result: the text in the editor. If it fails: nothing to do at this step.
4. Validate on the server. The server applies the full contract. Click Validate on the server. Expected result: Valid against contracts/v1. If it fails: read the error list and fix the manifest.
5. Create. Click Create. Expected result: the toast Saved as version 0.1.0 and the skill in the list. If it fails: see Troubleshooting.

Verify the signature of a stored skill

1. Open the skill. Click it in the list. Expected result: the tabs Editor and Test appear. If it fails: the skill is not saved yet.
2. Verify. Open Test and click Verify. Expected result: the JSON answer with the digest and signature check. If it fails: forbidden means a role or the editor relation is missing.

Troubleshooting

Symptom	Cause	Fix
Invalid JSON: ...	The manifest text does not parse.	Fix the JSON syntax.
Error invalid_manifest (422)	The manifest breaks the contract.	Read errors in the answer and fix the fields.
Error tenant_mismatch (403)	metadata.tenant names another tenant.	Remove the field or set your tenant.
Error forbidden (403)	A required role is missing.	Ask for the developer role.
Error skill_not_found (404) on Verify	The skill is not stored.	Create it first.
Error state above the editor	The schemas of contracts/v1 could not be read.	Click Retry.

Related pages

• Skill development
• Skills (capabilities)
• Contracts
• Navin library
• Plugin builder