Table of Contents

Skills

Last updated:

Skills give agents reusable capabilities and focused guidance. They are useful when a workflow is too detailed for one system instruction but should not be built into every agent.

Note

Skill means an imported package, usually a SKILL.md file and optional supporting folders, that an agent can load when it needs that capability.

Installed Skills showing the built-in Oscova Agents guide and import action.

Choose an execution mode

Shell commands and bundled skill scripts are controlled by Execution Mode:

  • Disabled prevents shell commands and bundled skill scripts from running.
  • Host runs them directly on the machine running Oscova.
  • Container Sandboxed runs them in a Docker sandbox image.

Host is the default for a new user. Commands use Oscova's operating-system account permissions, and approval follows the agent and run settings. Auto-approved commands run without a human prompt.

Click Save after changing the mode. The change applies to later agent runs.

In Host mode, foreground commands start each call in the run's workspace. Explicitly created shell variables can persist between foreground calls. Background jobs are separate processes that start in the workspace and remain tied to the run's existing cleanup lifetime.

Oscova removes inherited application environment variables from new host shell processes and supplies only standard shell, user-home, system-root, and temporary-directory variables. This reduces accidental secret inheritance, but host commands can still access files and network resources available to Oscova's operating-system account.

In Container Sandboxed mode, normal commands run in Docker. The separate Host Shell tool can be selected for foreground host-only work. Container-layer installations last for that container's lifetime, bind-mounted workspace changes can persist, and host-installed tools are not automatically available in Docker.

Caution

Host execution can change the machine running Oscova. Offline and agent-local-only runs reject it because it cannot guarantee no network access.

Saving Execution Mode refreshes the available tool catalogue and affects later agent runs. Start a new run after changing it. An existing run refuses a later shell launch rather than switching targets.

Supported skill contents

Oscova discovers a skill from a valid SKILL.md file. A packaged skill may also include:

  • scripts/ for executable scripts.
  • references/ for readable support documents.
  • assets/ for readable support files.

Readable skill resources are limited to .md, .json, .yaml, .yml, .csv, .xml, and .txt. Resource files are discovered only from references/ and assets/.

Bundled script discovery is limited to files under scripts/. Container Sandboxed invokes .py, .js, and .sh scripts directly instead of selecting an interpreter from the file extension. Give each script a shebang, a first line beginning with #!, for Python, Node, or the shell installed in the sandbox image. Host runs files through the configured host shell and requires the matching runtime on PATH.

Approving a skill script runs the whole script. Commands inside it are not approved separately.

Skill discovery searches two levels deep. Keep packages simple: one skill folder, one SKILL.md, and predictable support folders.

Import a skill

Click Import Skill and choose either a raw SKILL.md file or a .zip package up to 10 MB. The import dialog rejects other file types before upload.

Zip imports are also limited to 30 MB after expansion. A package may upload within 10 MB but still fail validation if its uncompressed content is too large or unsafe.

Zip packages may include:

  • scripts/ for script-backed tools.
  • references/ for supporting documents.
  • assets/ for supporting files.

Imported skills appear in Installed Skills and are stored in your user workspace. Assign a skill to an agent before expecting that agent to use it.

If an import succeeds with warnings, the dialog keeps those warnings visible before it closes. Duplicate skill names are rejected so an import cannot silently overwrite an installed skill.

Use the delete icon in Installed Skills to uninstall a skill. Uninstalling removes the skill directory and also removes that skill name from any agent allowed-skill lists.

oscova-agents-guide is a built-in product guide assigned to the main agent. Oscova restores its packaged files and main-agent assignment during startup, so local edits, deletion, or unassignment are replaced by the guide shipped with the installed release. Other skills and assignments are left unchanged.

Find skills online

Find skills online searches configured GitHub skill sources. Use Details to load a description, then Install to import the selected skill. Install progress shows catalog, download, validation, and import stages.

New installations start with the github/awesome-copilot repository on its main branch as a source.

If no sources are configured, ask an administrator to add one. Admins can use Skill sources to add owner, repository, and branch rows. Blank owner or repository rows are ignored when saved. Blank branches default to main.

Admins can also configure the system GitHub Skill Search credential. It is optional, but it raises GitHub API rate limits for skill discovery and installation from 60 requests per hour to 5,000 requests per hour for the host.

Agents can search the configured sources and request a skill install from chat. Agent-requested installs still require approval before the download happens. After approval, the installed skill is assigned to the requesting agent automatically.

Agent-authored skills

Agents can also be allowed to request skill creation or skill updates from chat. This turns a repeatable lesson, recovery step, or tool-use procedure into a reusable skill the agent can load later.

Agent-authored skills still require your approval. The approval prompt shows the operation, parsed skill name, and description before the write happens, and the raw arguments remain available for inspection.

Agent-authored skills are markdown-only. The agent must provide a complete SKILL.md document with valid name and description frontmatter. It cannot create bundled scripts, resources, zip packages, or registry entries through these tools.

Do not approve skills that contain secrets, tokens, private personal data, one-off task notes, or temporary troubleshooting logs. Skills should describe durable procedures that are useful beyond the current conversation.

When approval succeeds, Oscova stores trusted provenance in the skill frontmatter, saves the skill in the same installed-skills directory, and assigns it to the requesting agent. The current run is not rebuilt, so the new or updated skill is available on the next run.

Agents can update only skills that were previously authored through the agent-authoring path. User-imported, registry-installed, and manually edited skills are protected from agent updates.

Customize the sandbox image

Admins can edit the Dockerfile used by Container Sandboxed skill scripts.

  • Edit Dockerfile opens the Dockerfile in the file editor.
  • Build image builds the shared sandbox runner.
  • Rebuild image appears after an image exists.
  • No cache rebuilds layers instead of reusing cached layers.
  • Cancel appears while a build is running.
  • Use default restores the bundled Dockerfile and starts a rebuild after confirmation.
Note

Building the sandbox image requires Docker and may need network access for package downloads.

The page shows whether the sandbox is using the default Dockerfile or a custom Dockerfile, whether the image is built, and up to 500 recent build-output lines. Build image, Rebuild image, and Use default are disabled while Offline mode is on because those actions may need network access.

An air-gapped run can assemble the default image automatically when node:22-bookworm-slim and the required build layers are already cached locally. Docker disables build networking and image pulls for this path. Custom Dockerfiles must be built before Offline mode is enabled.

Troubleshooting

  • If Import is disabled, choose a .md or .zip file first.
  • If import fails, confirm the package contains one valid SKILL.md.
  • If import reports a conflict, uninstall the old skill or rename the incoming skill before retrying.
  • If a script does not run, check Execution Mode and whether the agent has the skill assigned.
  • If a local script fails immediately, confirm the matching host runtime for .py, .js, or .sh is installed and on PATH.
  • If a sandboxed script fails immediately, check its first line, then build or rebuild the sandbox image and review the build output.
  • If online search is empty, configure skill sources or check GitHub access.
  • If GitHub search is rate-limited, ask an admin to set the GitHub Skill Search credential.