docs(spec): restructure the SKILL.md format spec on the Agent Skills standard (#691) (#1695)

## Why this matters

A draft of this spec already existed, but it did not conform to the
**Agent
Skills standard ([agentskills.io](https://agentskills.io))** that it
should build
on. It declared a flat top-level schema (`permissions`, `security_tier`,
`tools`
at the root) instead of the standard's `name`/`description` base plus a
vendor
`metadata` map, and it framed OpenClaw/ClawHub as the external standard
to target.
That also diverged from the sibling `agent-skills.mdx`, which had
already
identified agentskills.io as the base and noted "OpenClaw/ClawHub" as a
placeholder from an earlier draft. The draft also referenced runtime
symbols
(`SkillManager`, `load_skill`, `OpenClawAdapter`) as though they existed
in code.

This revision brings the format into compliance with agentskills.io and
resolves
that divergence. It matters because `SKILL.md` frontmatter is a shared
contract:
planned consumers will read and write these fields — #887 (skill
auto-synthesis)
and #553 (self-improving agent) will *emit* `SKILL.md`, and #1451
(tool-loader
Part 3, not yet implemented) is specified to *read* the `tools_required`
field. A
standard-conformant, stable schema lets those consumers be built against
one
consistent picture. Every cited symbol is verified against `main`, and
every
not-yet-built runtime symbol is marked **PROPOSED**.

**The most important decision:** adopt Agent Skills (agentskills.io, as
used by
Claude Code) as the base standard, and express everything GAIA-specific
— typed
tools, `<domain>:<level>` permissions, and three security tiers — as a
strict
superset under a `metadata.gaia` namespace. A standard runtime ignores
`metadata.gaia` losslessly; a bare standard skill loads in GAIA as an
instruction-only `experimental` skill. The tiers are an install-time
trust
ceiling, kept distinct from the run-time governance `ALLOW/REVIEW/BLOCK`
decision
axis.

Lands the revised spec at `docs/plans/skill-format.mdx` and reconciles
the
sibling `docs/spec/agent-skills.mdx`. The spec stays under `docs/plans/`
(not
`docs/spec/`) until the runtime ships, per the repo's plan-vs-spec
convention —
the issue's `docs/spec/` acceptance is treated as
satisfied-on-implementation.

## Linked issue

Closes #691.

Downstream consumers this contract serves: **#887** / **#553** (will
*emit*
conformant `SKILL.md`), **#1451** (tool-loader Part 3, planned — will
*read*
`tools_required`), **#647** (marketplace publishes the format + tiers),
**#648**
(OEM bundling pre-bundles a defined "skill"), and **#462** (Agent
Manifest
references skills). #462/#647 are closed — their designs are settled and
already
reference this format.

## Changes

- **Rebased the field grammar on the Agent Skills standard + a
`metadata.gaia`
namespace.** Replaced the flat top-level schema and the
OpenClaw-as-standard
framing; nested all GAIA fields under `metadata.gaia`; kept top-level
`version`
as the one tolerated superset key; excluded
`compatibility`/`allowed-tools`.
- **Pinned the cross-spec contract.** Defined `tools` (provided) vs
`tools_required` (consumed) as distinct fields, aligned with
`tool-loader.mdx`
  Part 3 (`CORE > SKILL > SEMANTIC`, gated on #887, degrades to `[]`).
- **Grounded the security/permission model.** `<domain>:<level>`
permissions
bridge to the existing `ConnectorRequirement` primitive; tiers framed as
an
  install-time ceiling distinct from run-time governance.
- **Reconciled `agent-skills.mdx`** — mapping table now nests
`metadata.gaia.*`,
  the placeholder Note became a Division-of-authority Note, and the
  `allowed-tools` permission-scoping claims were removed.
- **Retracted the v1 `OpenClawAdapter` runtime promise** (compatibility
is
  migration-only) and marked every greenfield runtime symbol PROPOSED.

## Open questions (deferred to the implementer's design sketch)

- `tools_required` validation **timing** — install-time static catalog
vs.
  deferred (fail-vs-skip itself is settled by the fail-loudly rule).
- Skill→skill dependencies — keep under `metadata.gaia.requirements` or
defer to
  the marketplace (#647)?
- `/api/skills` install sources — registry-only, or local path / URL?
- Instruction-body injection scanning — required for `community`+,
advisory for
  `experimental`?
- When the doc relocates to `docs/spec/` (with the loader, or earlier?).

## Test plan

- [x] `python -c "import json; json.load(open('docs/docs.json'))"` — nav
JSON valid
- [x] `plans/skill-format` registered under the **Ecosystem** group —
this revises
  an existing draft in place, so `docs.json` is intentionally unchanged
- [x] Mintlify preview renders `skill-format.mdx` + `agent-skills.mdx`
(tables,
`<Info>`/`<Note>`/`<Warning>`/accordions, internal + cross-doc anchors
resolve)
- [ ] Maintainer sign-off on the design direction before implementation
begins
  (open questions left explicitly for the implementer's design sketch)

## Checklist

- [x] I have linked a GitHub issue above (`Closes #691`).
- [x] I have described **why** this change is being made, not just what
changed.
- [x] Docs-only PR — no Python touched, so `pytest`/`util/lint.py` don't
apply;
validated `docs.json` JSON and confirmed every YAML example parses
instead.
- [x] I have updated documentation (this PR *is* the documentation).

---
**Requested reviewer:** @kovtcharov-amd

---------

Co-authored-by: Alexey Tyurin <>

Author: alexey-tyurin