ActorSkill actor.skill@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

An older major, still in the catalog. The current one is actor.skill@2.
Version
1.1.0
Owner
actor
Visibility
public
Status
active
Compatibility
backward
Decision
ADR-058
Schema
https://openvibe.network/contracts/actor/skill.v1.json

actor.skill@1: a skill, the document an agent loads to do one kind of job well (ADR-058). It follows the open Markdown-skill shape (a name, a one-line description, Markdown instructions) with what OpenVibe adds: a slug, a version, up to ten TEXT resources, and REQUIRES, what the skill may ask an agent to do. A skill GRANTS NOTHING: requires only declares; the agent's level and approvals decide every step (actor approvals, HO1), and a step of a kind the skill did not declare is a scan finding (actor.skill-listing@1). A v1 skill RUNS AS A PROMPT and nothing else: no code, no binary, no install recipe (a skill that runs code waits for a sandbox and a new major). DESCRIPTION is the only part an agent reads before it loads the skill (progressive disclosure), so it says when to use it. The INTEGRITY block is a sha256 over the canonical JSON of the document: it shows the file was not edited after it was written and says nothing about who wrote it, so the AUTHOR is a claim; the registry's listing is the only place a publisher is vouched for. The canonical JSON is the document's own fields, in this order: skill, slug, name, description, version, instructions, resources, requires, runs, license, author; an optional field that is absent or empty is left out; resources are [{ path, media_type, text }] in the document's order; requires is { kinds, apps, hosts } with empty lists left out; author is { subject } or { subject, name }; the value is the compact JSON of that object (no spaces). CREATED_AT is not hashed.

Fields

FieldTypeRequiredDescriptionConstraints
skillconstyesThe document marker.
  • = "actor.skill@1"
slugstringyesIts name in the registry: lowercase letters, digits and hyphens.
  • pattern ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
namestringyesWhat a person reads on its card.
  • minLength 1
  • maxLength 80
descriptionstringyesWhen to use it, in one line: the only part an agent reads before it loads the skill.
  • minLength 1
  • maxLength 280
versionstringyesIts semantic version.
  • pattern ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$
instructionsstringyesWhat to do, in Markdown. The agent reads it as guidance; it never grants a permission.
  • minLength 1
  • maxLength 20000
resourcesarray of objectText the instructions refer to (a checklist, a template, a table). Never code to run.
  • maxItems 10
  • items: no other fields
resources[].pathstringyesA relative name, no "..", ending in .md, .txt, .json or .csv.
  • pattern ^[a-z0-9][a-z0-9_-]{0,59}(?:/[a-z0-9][a-z0-9_-]{0,59}){0,3}\.(md|txt|json|csv)$
resources[].media_typeenumyes
  • one of "text/markdown", "text/plain", "application/json", "text/csv"
resources[].textstringyes
  • maxLength 20000
requiresobjectWhat the skill may ask an agent to do. It grants nothing: each step still goes through the agent's level and approvals.
  • no other fields
requires.kindsarray of enumThe kinds of act (actor approvals, HO1) its steps may be.
  • maxItems 18
  • unique items
  • items: one of "codes.task", "actor.action", "computer.run", "computer.write", "computer.input", "computer.browser", "computer.desk", "robot.move", "space", "publish", "post", "send", "install", "routine", "money", "device.camera", "device.location", "device.notify"
requires.appsarray of stringConnected apps it uses (connect slugs). The person connects each one themselves.
  • maxItems 20
  • unique items
  • items: pattern ^[a-z][a-z0-9._-]{0,63}$
requires.hostsarray of stringWeb hosts it reads from or writes to.
  • maxItems 20
  • unique items
  • items: pattern ^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$
runsconstyesHow it runs. v1 skills are instructions and text only.
  • = "prompt"
licensestringAn SPDX licence id, such as MIT or CC-BY-4.0.
  • minLength 1
  • maxLength 64
authorobjectWho the document says wrote it: a claim, never checked here.
  • no other fields
author.subjectstringyes
  • pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$
author.namestring
  • minLength 1
  • maxLength 80
created_atstringWhen the document was written. Not hashed.
  • format date-time
integrityobjectyesA sha256 over the canonical JSON: the file was not edited after it was written. Not a signature.
  • no other fields
integrity.algconstyes
  • = "sha256"
integrity.hashstringyes
  • pattern ^[0-9a-f]{64}$

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

The fixtures that ship with the package are the current major's.

Validate

const contracts = require('openvibe-contracts');
contracts.validate('actor.skill@1', value);   // { valid, errors: [{ path, message }] }