RFC: Skill Capability Manifests v0

Summary

This RFC proposes a small, skills-first capability manifest for OpenClaw.

The goal is to help users answer one simple question before using a skill:

What can this skill do?

OpenClaw skills can package useful behavior, but today a user may not have a simple way to inspect what a skill expects to access: tools, files, or shell execution.

This proposal starts with a deliberately small v0:

1. Add an optional capabilities block to skill metadata.
2. Add one inspect command to display those capabilities.
3. Do not change runtime behavior in v0.
4. Do not add approval flows, lockfiles, update diffs, or enforcement in v0.

The intent is to create a lightweight permission vocabulary first. If maintainers agree the model is useful, later versions can add approval, update diffing, and enforcement.

Framing question

The core product question is:

What can this skill do?

A good first version does not need to solve all security problems. It only needs to make skill capabilities visible and understandable.

For example, before enabling or using a skill, a user should be able to see:

This skill requests:
- tools: read, web_fetch
- file read: workspace:/docs/**
- file write: none
- exec: not allowed

That alone would make skills easier to review, debug, document, and eventually govern.

Why start with skills?

This proposal intentionally starts with skills only.

Agents, skills, and plugins all have different lifecycles:

• agents may be local, conversational, spawned, or long-running
• plugins may run in-process or integrate deeply with the runtime
• skills are more naturally packaged as reusable user-facing capabilities

Because of that, a single v0 that covers agents, skills, and plugins would likely be too broad.

Skills are the cleanest entry point because they are:

• user-visible
• reusable
• easier to inspect statically
• easier to document
• a natural place to declare expected access

If the manifest pattern works for skills, the same model can later be adapted to agents and plugins.

Example skill capability manifest

A skill could declare its requested capabilities in a small metadata block.

Example:

id: github-issue-summarizer
type: skill
description: Summarizes GitHub issues from a provided URL or issue number.

capabilities:
  tools:
    allow:
      - read
      - web_fetch

  files:
    read:
      - workspace:/docs/**
    write: []

  exec:
    allow: false

This is only an example. The exact field names can change. The important point is that the skill declares its expected access in a structured, inspectable way.

Proposed CLI behavior

Add one command:

openclaw skills inspect <skill-id>

Example output:

Skill: github-issue-summarizer

Description:
  Summarizes GitHub issues from a provided URL or issue number.

Declared capabilities:

Tools:
  allowed:
    - read
    - web_fetch

Files:
  read:
    - workspace:/docs/**
  write:
    - none

Exec:
  allowed: false

If a skill has no manifest:

Skill: example-skill

No capability manifest found.

This skill does not declare what tools, files, or exec access it expects.

v0 behavior:
  - no runtime behavior changed
  - this is an inspect-time warning only

Proposed v0 scope

v0 should be intentionally small.

In scope

1. Define a minimal skill capability manifest shape.
2. Support capability declarations for skills.
3. Add an inspect command.
4. Print declared capabilities in a human-readable format.
5. Warn when a skill has no capability manifest.
6. Do not change runtime behavior.

Capability groups for v0

v0 covers three groups only:

tools
files
exec

These are the smallest set that meaningfully answers:

What can this skill do?

Additional groups (network, channels, memory, config) are deliberately deferred to a "next pass" — they are described in Future work below.

Out of scope for v0

The following should be deferred:

• additional capability groups (network, channels, memory, config)
• runtime enforcement
• permission approval prompts
• capability lockfiles
• update-time permission diffs
• install-time UI changes
• agent capability profiles
• plugin capability profiles
• sub-agent permission propagation
• sandbox routing
• enterprise policy modes
• full security certification

This keeps v0 small enough to review and implement without forcing agreement on the entire security model.

Why this matters

OpenClaw users should not need to inspect source code or infer behavior from docs to understand what a skill expects to access.

A skill capability manifest would help several groups.

Users

Users get a simple way to inspect a skill before using it.

They can answer questions like:

• Does this skill run shell commands?
• Does it write files?
• Which paths does it read or write?
• Which tools does it expect to use?

Maintainers

Maintainers get a shared vocabulary for permission-related issues.

Instead of debugging from vague descriptions like "this skill did something unexpected," maintainers can ask:

• What did the skill declare?
• What did the user expect?
• Was the manifest missing, too broad, or inaccurate?

Skill authors

Skill authors get a standard place to document expected access.

This makes skill behavior easier to communicate and review.

Future security work

A manifest does not enforce anything by itself, but it creates a foundation for future work:

• approval prompts
• permission diffs on update
• runtime enforcement
• disabled-skill boundaries
• audit messages
• security profiles

Prior art

This proposal follows patterns used in other ecosystems.

Chrome extension permissions

Chrome extensions declare permissions such as tabs, storage, host access, and network domains. Users and the platform can reason about extension access before execution.

Android app manifests

Android apps declare permissions such as camera, location, contacts, and storage. The manifest creates a structured contract between the app, the platform, and the user.

VS Code extension contributions

VS Code extensions declare contributions such as commands, configuration, languages, debuggers, and activation events. This gives the platform a structured understanding of what the extension adds.

The OpenClaw version does not need to copy any of these systems exactly. The common pattern is:

packaged capability should come with a visible declaration of what it expects to access.

Relationship to existing OpenClaw work

This RFC is meant to connect several related OpenClaw discussions into a small first step.

There are already conversations around:

• per-agent tool restrictions
• skill permissions
• disabled skill behavior
• sandbox and exec safety
• tool allowlists and denylists
• security profiles
• permission propagation
• auditability

Those are larger topics.

This RFC proposes a smaller foundation:

Before enforcing permissions, make requested permissions visible.

A skills-first manifest can become the common vocabulary for those later efforts.

Example: read-only skill

A documentation summarizer might declare:

id: docs-summarizer
type: skill
description: Reads local documentation and creates summaries.

capabilities:
  tools:
    allow:
      - read

  files:
    read:
      - workspace:/docs/**
    write: []

  exec:
    allow: false

Inspect output:

Skill: docs-summarizer

Tools:
  allowed: read

Files:
  read: workspace:/docs/**
  write: none

Exec:
  allowed: false

This makes it clear that the skill is intended to work only on local workspace documentation and does not need write or shell access.

Example: read-and-write skill

A report generator that reads inputs and writes outputs to a separate folder might declare:

id: report-generator
type: skill
description: Reads workspace data and writes generated reports.

capabilities:
  tools:
    allow:
      - read
      - write

  files:
    read:
      - workspace:/data/**
    write:
      - workspace:/reports/**

  exec:
    allow: false

Inspect output:

Skill: report-generator

Tools:
  allowed: read, write

Files:
  read: workspace:/data/**
  write: workspace:/reports/**

Exec:
  allowed: false

This makes the read/write split explicit: the skill reads from data/** but only writes into reports/**, never back into the source data.

Example: skill with exec access

A local test runner skill might declare:

id: local-test-runner
type: skill
description: Runs project tests in the current workspace.

capabilities:
  tools:
    allow:
      - read
      - write
      - exec

  files:
    read:
      - workspace:/**
    write:
      - workspace:/**

  exec:
    allow: true
    reason: "Runs local project test commands."

Inspect output:

Skill: local-test-runner

Tools:
  allowed: read, write, exec

Files:
  read: workspace:/**
  write: workspace:/**

Exec:
  allowed: true
  reason: Runs local project test commands.

Warning:
  This skill declares exec access.
  v0 does not enforce permissions; this is an inspect-time warning only.

Even without enforcement, the user can immediately see that this skill is more powerful than a read-only summarizer.

Alternatives considered

Alternative 1: Start with runtime enforcement

OpenClaw could begin by enforcing tool/file/exec/network permissions immediately.

I do not recommend that for v0.

Runtime enforcement is valuable, but it requires deeper design decisions:

• where enforcement happens
• how tools are filtered
• how file paths are resolved
• how exec is intercepted
• how missing manifests behave
• how existing users are migrated
• how sub-agents inherit permissions

Starting with enforcement could make the proposal too large.

Alternative 2: Start with agents instead of skills

Agents are important, but agent lifecycle and delegation behavior are more complex.

A skill-first approach is easier to inspect statically and easier to adopt incrementally.

Alternative 3: Start with plugins instead of skills

Plugins are also important, but they may have deeper runtime and process-level implications.

A skills-first manifest avoids starting with the most privileged extension surface.

Alternative 4: Keep permissions only in documentation

Skill authors can document requirements in README files.

That is useful, but not enough. A structured manifest allows tooling to inspect, print, diff, validate, and eventually enforce capabilities.

Alternative 5: Wait for a full security profile design

A full security profile may be the right long-term direction, but users can benefit sooner from a small manifest and inspect command.

This RFC is intended as a stepping stone, not the final security architecture.

Test plan

Because v0 is inspect-only, the test plan can be simple.

Unit tests

1. Parse a skill with a valid capability manifest.
2. Parse a skill with no capability manifest.
3. Parse a skill with unknown capability fields.
4. Parse a skill with malformed capability values.
5. Render human-readable output for each capability group.

CLI tests

1. openclaw skills inspect docs-summarizer prints declared capabilities.
2. openclaw skills inspect skill-with-no-manifest prints a warning.
3. openclaw skills inspect unknown-skill returns a clear not-found error.
4. openclaw skills inspect skill-with-exec prints an exec warning.
5. openclaw skills inspect skill-with-broad-file-access prints broad file scope clearly.

Compatibility tests

1. Existing skills without manifests continue to work.
2. Existing runtime behavior does not change.
3. Missing manifests produce warnings only.
4. Unknown fields do not crash the CLI.
5. Existing skill loading remains unchanged.

Risks

Risk 1: Users may assume v0 enforces permissions

Because v0 is inspect-only, the CLI output should clearly say:

v0 is inspect-only. OpenClaw is not enforcing these capabilities yet.

This avoids giving users a false sense of security.

Risk 2: Manifest schema becomes too broad

The first version should avoid modeling every possible permission.

A small schema is better. v0 covers only:

tools
files
exec

More groups (network, channels, memory, config) are explicitly deferred to a next pass and can be added incrementally.

Risk 3: Skill authors may not add manifests

That is acceptable for v0.

The inspect command can show:

No capability manifest found.

Over time, manifests can become recommended for published or trusted skills.

Risk 4: Field names may not match future enforcement design

The schema should be treated as v0 and kept simple. Enforcement can refine it later.

Risk 5: Maintainers may not want another metadata surface

That is why this proposal starts with one artifact and one command. It should be useful even before deeper platform changes.

Open questions

1. Is skills the right first surface for capability manifests?
2. This RFC uses openclaw skills inspect <skill-id> throughout. Is that the right command name, or would openclaw capabilities inspect <skill-id> better signal the broader future scope?
3. Where should the capability manifest live?
   • inside existing skill metadata
   • as a separate capabilities.yaml
   • inside a shared manifest file
4. v0 proposes three groups (tools, files, exec). Are these the right starting set, or should any of the deferred groups (network, channels, memory, config) be in v0 from the start?
5. Should unknown fields be warnings or errors?
6. Should broad permissions trigger warnings?
   • workspace:/**
   • exec.allow: true
   • unrestricted network
7. Should missing manifests show a warning by default?
8. Should manifests be optional forever or eventually recommended for published skills?
9. Should the v0 schema include reason fields for sensitive capabilities such as exec?
10. If this direction is welcome, would maintainers prefer a small PR that only adds schema parsing and an inspect command?

Proposed first PR

If maintainers are open to the direction, I suggest starting with a small PR:

feat(skills): add capability manifest parsing and inspect command

Scope:

• define a minimal skill capability schema
• parse capability manifests from skill metadata
• add inspect command
• print declared capabilities
• warn when no manifest exists
• add tests
• no runtime behavior change
• no enforcement

This keeps the first contribution small and reviewable.

Future work

If v0 is accepted and useful, later versions could add:

Next pass: additional capability groups

Groups deliberately deferred from v0 so the first manifest stays small. Each can be added without breaking the v0 schema:

• network — list of allowed external domains (e.g. api.github.com)
• channels — declared message-channel reads and sends
• memory — declared memory reads and writes
• config — declared config reads

v1: Approval and update diffs

• store approved skill capability hashes
• warn when a skill update expands permissions
• show permission diffs

v2: Runtime enforcement

• filter tools based on skill capabilities
• block exec when not declared
• enforce file read/write scopes
• restrict network access where possible

v3: Agents and plugins

• extend the same manifest pattern to agents
• extend the same manifest pattern to plugins
• handle sub-agent permission propagation

v4: Security profiles

• define presets such as read-only, developer, sandboxed, and trusted
• allow users to run OpenClaw in stricter modes

These should be later phases, not part of v0.

Closing

The goal of this RFC is intentionally modest:

Before OpenClaw enforces what a skill can do, OpenClaw should be able to show what a skill says it can do.

A skills-first capability manifest gives users, maintainers, and skill authors a shared language for permissions without requiring a security rewrite.

The first version can be small:

• one manifest
• one inspect command
• no runtime behavior change

That seems like a practical foundation for the broader permission and safety work already being discussed.