Skip to main content
A skill is a guide (SKILL.md plus optional files under references/) that teaches an agent how to use one part of Ravi. At the end of this page you will know how to list and read the skills that ship with Ravi, copy reference files such as the Pages skeletons, why an agent’s first command in a group returns a skill instead of running, how to search, load, publish, propose and pin your organization’s Library skills, and how to install and grant skills of your own.

​
System skills

System skills ship inside the Ravi package, so they always match the CLI you have installed. They are the most detailed reference for each command group, often more current than these docs, and you can read them yourself. They are written in Portuguese.
ravi skills list pages at 50 items; pass --limit 500 to see everything, or --json and follow pagination.nextCommand.
This page describes ravi.bot@next. In @latest (3.260927.5) the bases and solucoes skills do not exist and ravi skills show has no --file or --raw. Install @next with bun add -g ravi.bot@next, or switch with ravi update --next.

​
Read and copy reference files

Longer material lives in each skill’s references/ folder. The end of ravi skills show <skill> lists the files; open one with --file:
Add --raw to print only the file’s bytes, with no header or file list, so you can copy it straight into your project. This is how you start a data page from the Pages skeletons:
The skeletons are esqueletos/board.html.txt (a table or board), esqueletos/formulario.html.txt (a form) and esqueletos/_client.js.txt (the client every data page uses). Interactive pages with Bases walks through using them. --file takes a relative path from the skill’s file list. Anything else fails with SKILL_FILE_NOT_FOUND (the error lists the valid files) or SKILL_FILE_INVALID (absolute path or ..). With --json, show returns { skill, files[] }, plus file { path, content } when you pass --file.

​
Skills you will use most

You can pass either column to ravi skills show. Others in the catalog: automation-recipes, crm, tasks, projects, observers, meetings, commands, apps, tag-rules, specs, prox-calls, plus developer skills from the ravi-dev plugin (app-creator, cli-creator, context-cli, prompt-builder, ravi-architecture, ravi-rules). architect, cross, matrix and tasks-manager are deprecated stubs that point to their replacements.

​
How agents load skills (skill gates)

Inside an agent session, Ravi makes sure the agent has read the right skill before it uses a command group. The first time the agent runs, for example, ravi pages ship ..., the call does not run. Instead the tool result is:
The agent reads it and runs the same command again, which now goes through. This happens once per skill per session. Running ravi skills show <skill> in the session also counts as loading it. For bases, pages, triggers and cron, the delivered skill ends with a pointer to solucoes until that one is loaded too. These command groups are gated by default: agents, apps, artifacts, audio, bases, commands, contacts, context, cron, daemon, events, heartbeat, image, instances (instances routes loads the routes skill), meetings, observers, pages, permissions, projects, prox calls, routes, sessions, settings, skill-gates, skills, slack, specs, stickers, tasks, triggers, video and whatsapp. Other groups, such as channels and media, are not. Gates only apply inside agent sessions. Commands you type in your own terminal run directly. If the agent is not allowed to see the skill, the call fails with RAVI_SKILL_GATE_CONFIG_ERROR and names the fix: grant the skill (ravi skills grant <agent> <skill>) or give the agent the use:skill:<skill> capability. To change the rules themselves, use ravi skill-gates list, show, set, disable, enable, rm and reset (rm and reset are dry-runs without --execute).

​
Who can see which skill

Each agent sees the union of a baseline, the skills its permissions imply, and explicit grants. An agent with no skill configuration at all sees everything.
ravi skills grant-batch and ravi skills revoke-batch do the same in bulk; preview with --dry-run. Skills that ship with Ravi need no install: grant them directly, or give the agent use:skill:<skill>. use:skill:* (which the full-access profile includes) and admin:system:* let an agent read any catalog or installed skill on demand. Run a grant as its own command: a shell line that also reads the denied skill is rejected as a whole, so the grant on that line never runs.

​
Library skills (organization and project)

The Library keeps skills in the Ravi Console so every agent of your organization can use them. A Library skill belongs either to the organization, so every project’s agents see it, or to one project, so only the agents of that project see it. It is the same folder format as any skill: SKILL.md plus optional references/. The Library needs a Ravi Cloud login (ravi login); without one, everything else on this page still works. Library skills have refs:
  • org/<slug> for an organization skill, such as org/weekly-agenda
  • <project>/<slug> for a project skill, such as clinic/triage

​
Search and load

source is system (ships with Ravi), installed or library, and next is the exact command that loads the result. A name without a slash resolves to your local skills first: Ravi’s own skills and installed skills always win. Only when nothing local matches does Ravi look in the Library, in the organization’s skills and the agent’s Console project. Inside an agent session, use the full ref that search returns. show keeps a copy of every Library skill it loads under ~/.ravi/library/. When the Console cannot be reached, show and search answer from that copy and add stale: true, so a skill an agent already used keeps working.

​
Who can load a Library skill

Library skills are authorized like local ones. An agent on the full-access profile can load any of them. Other agents need a grant or a capability:
The capability form uses the same ids: use:skill:org:weekly-agenda, use:skill:org:* for every organization skill, use:skill:project:clinic:* for every skill of one project. A project skill of another project than the agent’s own is refused (LIBRARY_SKILL_OUT_OF_VIEW) unless an operator grants that exact ref. Only skills published with --external load in conversations with people outside your organization. Your own turns are your terminal, your linked direct chat and your routines; in any other turn the rest fail with LIBRARY_SKILL_EXTERNAL_DENIED (exit 3), and search leaves them out.

​
Publish

Publishing changes what every agent of the organization or project loads, so it is a dry run until you confirm it. Without --execute, Ravi checks the folder, reads the version published now and prints the plan (exit 3). With --execute, it publishes the next version.
Before sending anything, Ravi checks that SKILL.md is at the root with a description in its frontmatter, that there are at most 100 UTF-8 text files of at most 256 KiB each and 1 MiB in total, and that file paths use only A-Z a-z 0-9 . _ - /. Dot files and node_modules are left out. The slug is --slug, else the name in SKILL.md, else the folder name. The names of Ravi’s own skills, the ravi- prefix and proposals are reserved. Publishing content identical to the current version creates nothing (unchanged: true). If someone published in the meantime, --execute fails with CONFLICT and conflict: stale_base; run it again without --execute to see the new plan. Agents never publish. Inside an agent session, ravi skills publish stops before sending anything with LIBRARY_AGENT_CANNOT_PUBLISH (exit 3); the agent proposes the change instead, and a person publishes it.

​
Propose a change for review

A proposal is a new version that is not published yet. The people who review the organization’s or the project’s skills comment on it, file by file and line by line, then publish or reject it in the Console. This is how an agent changes a Library skill, and it works the same from your terminal. The folder rules are the ones for publishing, and proposing is a dry run until you confirm it.
  • A new proposal is written against the version published now (baseVersion, 0 for a new skill). The plan lists your open proposals on the same skill in openProposals; update one with --update <number> instead of opening another.
  • --update <number> sends the whole folder and flags again. A draft then waits for review, unless you pass --draft again. Updating a proposal under review starts a new round, and earlier comments show as outdated.
  • A proposal is stale when someone published a newer version after its base. Read that version with ravi skills show <ref>, bring its changes into your folder, then run --update <number> --rebase.
  • Inside an agent session, the proposal shows as “agent X for Y”, the agent can update only proposals it wrote (LIBRARY_PROPOSAL_NOT_YOURS, exit 3), and --mine lists only its own.
  • ravi skills proposal prints each comment as file:line, marked [outdated] or [resolved] when it is. ravi skills proposals lists one skill’s proposals when you pass its ref, and takes --state open|closed|all and --project <project>.
  • A CONFLICT carries its reason in conflict: stale_base (read the newer version and plan again), unchanged (nothing differs from the published version), slug_taken_in_org, slug_taken_in_project or slug_reserved (pick another --slug), proposal_closed (the proposal was decided; propose again without --update).

​
Pin a skill to an agent

A pin makes an agent always load a Library skill: it arrives natively in every new session, like Ravi’s own skills, always at the latest published version, and the agent may load it without a grant. A person pins a skill to an agent of one installation, in the Console or from your terminal; the Console decides who may (an admin of the skill’s organization or project). Pinning is a dry run until you confirm it; unpinning only takes something away, so it runs right away.
  • The daemon reports its listed agents to the Console and reads the pins every 5 minutes (RAVI_LIBRARY_PIN_INTERVAL_MS). pin --execute and unpin update this installation at once, so you do not wait for that.
  • A pinned skill is named org-<slug> or <project>-<slug> inside a generated ravi-library plugin: ravi-library:<name> for Claude, ravi-library-<name> for Codex. ravi skills pins --json shows it in skill.
  • Only the agent it is pinned to sees it. A skill published without --external loads only in sessions that serve your own turns.
  • A session picks its pinned skills when it starts: open a new session after pinning.
  • The Console pins only agents this machine reports: list the agent first (ravi agents listing <agent> on --execute), or the pin stops with LIBRARY_AGENT_NOT_LISTED.
  • A project skill can only be pinned to an agent of that project (CONFLICT, conflict: agent_out_of_scope). Set the agent’s project with ravi cloud scope set --agent <agent> --project <project> and pin again. not_published means publish a version first; no_installation means run ravi login on this daemon.
  • Offline, the pins of the last sync keep loading and ravi skills pins answers with stale: true. A pinned skill this login cannot read shows in unavailable (LIBRARY_PIN_UNAVAILABLE) and does not load.
  • Agents never pin or unpin: inside an agent session both commands stop with LIBRARY_AGENT_CANNOT_PIN (exit 3).

​
Library agents

The Library also holds agent definitions: an AGENTS.md with the instructions, an optional HEARTBEAT.md, and an optional agent.json that suggests a provider, a model, a permission profile and the skills the agent needs. Install one as a new agent on this machine, keep it up to date, or publish one of your agents for the organization or a project. A definition never carries routes, instances, contacts, local paths or credentials: after installing, route the agent yourself.
  • install writes the files into the agent’s folder (default ~/ravi/<id>), sets the suggested provider and model and records the version and a hash of each file. It runs at once unless the definition asks for a permission profile above the default (full-access) or for skills to be granted: then it is a dry run until you pass --execute. Grants are stored like ravi skills grant; a required skill this machine cannot find is skipped and listed. An existing agent id is refused (AGENT_ALREADY_EXISTS).
  • update replaces files you did not edit. A file you edited that also changed in the Library stops the update with LIBRARY_AGENT_EDITED_LOCALLY (exit 2) and the diff; choose --keep-local or --take-library. A new profile or new skills follow the same --execute rule as install. A profile you changed here is not reverted unless the Library changed its suggestion.
  • publish sends AGENTS.md, HEARTBEAT.md and an agent.json built from the agent’s provider, model and profile, plus the Library skills it is granted that the scope can see (others are listed under leftOut). It always needs --execute. The description is --description, else the one set with ravi agents set <id> description.
  • Agents never install, update or publish agents: inside an agent session these stop with LIBRARY_AGENT_CANNOT_INSTALL or LIBRARY_AGENT_CANNOT_PUBLISH (exit 3).

​
Ask agents on other machines

Every machine linked with ravi login reports to the Console only the agents its operator listed (ravi agents listing <agent> on --execute; none by default), and the directory lists the agents on the organization’s other machines (org-wide ones and those of projects you can read). You can ask one of them something; that machine runs one turn of its agent and sends the answer back. An agent only takes requests after its operator opens it, and it answers as you: in a session of its own, without the operator’s authority on that machine.
  • The machine is the installation name the directory shows; when two machines share a name, use the installation id (LIBRARY_TARGET_AMBIGUOUS, exit 2).
  • Asked from an agent session, the answer arrives in that session as a [System] Inform. Asked from the terminal, read it with ravi agents requests list --all.
  • On the asked machine, the daemon checks for requests every 30 seconds while one of its agents takes requests (every 15 seconds for 10 minutes after a request or answer came in), otherwise every 5 minutes (RAVI_LIBRARY_PIN_INTERVAL_MS), and gives each turn up to 10 minutes (RAVI_LIBRARY_REQUEST_TIMEOUT_MS). Requests expire after 24 hours, and a machine can have 20 waiting at once.
  • A CONFLICT carries its reason in conflict: not_accepting (the agent is not open to requests), same_installation (it runs on this machine: use ravi sessions send), too_many_open (wait or cancel one), no_installation (run ravi login on this daemon).
  • An agent you take out of the directory leaves the Console’s “Running agents” at the next sync. Its pins keep loading, but a new pin needs the agent listed (LIBRARY_AGENT_NOT_LISTED).
  • Listing or opening an agent is a dry run until you pass --execute; unlisting or closing it applies at once. Agents cannot list, open or close agents (LIBRARY_AGENT_CANNOT_LIST, LIBRARY_AGENT_CANNOT_OPEN_REQUESTS, exit 3), and an agent serving someone other than you cannot ask other machines (LIBRARY_REQUEST_EXTERNAL_DENIED, exit 3).

​
Install your own skills

ravi skills install copies a skill from the catalog, a local folder or a Git source into ~/ravi/plugins/ravi-user-skills/skills/<skill> (change the bucket with --plugin). Whether it runs at once depends on the risk:
A source with several skills needs a skill name or --all; otherwise the command fails with SKILL_SELECTION_REQUIRED and lists the candidates. Relative paths resolve against your current directory, and ~/... is your home directory, not a GitHub shorthand. Installing does not make a skill visible to an agent that has a skill allowlist. Grant it afterwards:
Install also refreshes the skills Ravi materializes for the Codex runtime, unless you pass --skip-codex-sync. Run ravi skills sync after editing skill files on disk. Install errors come back typed: SKILL_SOURCE_NOT_FOUND, SKILL_SOURCE_EMPTY, SKILL_SOURCE_INVALID, SKILL_SOURCE_UNAVAILABLE (a Git clone failure you can retry), SKILL_ALREADY_INSTALLED and, for grant, SKILL_NOT_FOUND.