`SKILL.md` schema

A skill is a folder. SKILL.md is the manifest the agent reads.

For the conceptual story (and the security model) see Skills. This page is the field-by-field reference.

Folder shape

.agents/skills/competitor-brief/
├── SKILL.md             # required — frontmatter + body
├── scripts/             # optional — helper scripts (require allowed-tools: run_script)
│   └── pull-funding.py
├── templates/           # optional — reference files
│   └── brief.md
└── assets/              # optional — logos, schemas, etc.
    └── competitor-schema.json

Cabinet mounts the folder into the agent's run sandbox. Files outside the folder are inaccessible via the skill.

Frontmatter fields

Identity

Field	Type	Required	Default	What it does
`name`	string	yes	—	Slug used for `@` mentions and the picker. `[a-z0-9-]+`.
`displayName`	string	no	derived from `name`	Pretty name for the picker.
`description`	string	yes	—	Hover-card explanation. ≤140 chars is the convention.
`version`	semver	no	`"0.1.0"`	For registry publishing.
`author`	object	no	—	`{name, url}`.
`license`	SPDX id	no	`"MIT"`	Shown on skills.sh.

Permissions

Field	Type	Required	Default	What it does
`allowed-tools`	string[]	yes	`[]`	Allow-list. Only these tools fire while the skill is active.
`network`	object	no	—	Network egress allow-list.
`network.allow`	string[]	no	`[]`	Hostname patterns the skill may fetch from, e.g. `"*.crunchbase.com"`.
`filesystem`	object	no	—	Filesystem read/write scope.
`filesystem.read`	string[]	no	inherits agent	Glob patterns this skill may read.
`filesystem.write`	string[]	no	inherits agent	Glob patterns this skill may write.

IO contract

Field	Type	Required	Default	What it does
`input-schema`	JSON schema fragment	no	—	Lets users invoke the skill with structured args (e.g. `/competitor-brief company=acme`).
`output-schema`	JSON schema fragment	no	—	Hints which paths the skill writes. Used for link-checking and approvals.
`estimated-cost-usd`	number	no	—	Average cost. Surfaced in the approval queue.
`estimated-runtime-s`	integer	no	—	Average runtime in seconds. Surfaced in the run UI.

Discovery

Field	Type	Required	Default	What it does
`tags`	string[]	no	`[]`	Free-form tags for skills.sh filters.
`category`	string	no	—	`"research"`, `"writing"`, `"data"`, etc.
`requiresProvider`	string[]	no	—	If set, the skill won't load unless one of these providers is configured.

Common tool names

The exact list ships with the app and grows. Common ones:

Tool name	What it can do
`read_file`	Read a single file (subject to `filesystem.read`).
`write_file`	Write or create a file (subject to `filesystem.write`).
`list_dir`	List a directory's contents.
`web_fetch`	HTTP GET (subject to `network.allow`).
`web_search`	Search the web through the configured backend.
`run_script`	Execute a script under `scripts/` (per-run user confirm).
`shell`	Arbitrary shell command. Almost never grant this.
`llm_call`	Inner LLM call. Only needed for skills that call models themselves.

Body — what the agent reads

Everything after the closing --- is what the agent sees when it picks up the skill. Treat it like a runbook:

What this skill does in one sentence.
How to run it — step-by-step, including which scripts to call.
What inputs it expects.
What outputs it produces and where.
What to watch for — failure modes, edge cases, when not to use it.

Keep it concise. Long preambles get diluted.

Complete example

---
name: competitor-brief
displayName: Competitor Brief
description: One-page competitive brief for any company. Pulls funding, reads launches, summarizes positioning.
version: 1.2.0
license: MIT
author:
  name: cabinet-app
  url: https://github.com/cabinet-app/skills

allowed-tools:
  - read_file
  - write_file
  - run_script
  - web_fetch
network:
  allow:
    - "*.crunchbase.com"
    - "*.producthunt.com"
filesystem:
  read:
    - "research/**"
    - "templates/**"
  write:
    - "research/competitors/**"

input-schema:
  company:
    type: string
  depth:
    type: string
    enum: [quick, deep]
    default: quick
output-schema:
  path:
    type: string
estimated-cost-usd: 0.20
estimated-runtime-s: 90

tags: [research, competitive, gtm]
category: research
requiresProvider: [openai, anthropic, google]
---

You produce one-page competitor briefs.

## How to run

1. Read templates/brief.md for the output shape.
2. Run scripts/pull-funding.py {company} for fresh funding data.
3. Use web_fetch on the company's homepage and pricing page.
4. Compose the brief at /research/competitors/{company-slug}.md using the template.
5. Always include a "Last updated: {date}" line at the top.

## When NOT to use

- For private companies with no public footprint — output will be sparse. Recommend the manual research routine instead.
- For internal projects — this skill is built for external competitive intel.

Validation

Skills are validated:

At install time (security scan + schema check).
At every run (allow-list enforcement, network/filesystem scopes).
At update time (re-scan, re-confirm any new allowed-tools).

A skill that violates its own allow-list at runtime is killed mid-run with a clear error. Cabinet never escalates a skill's permissions silently.

Read on

Skills (concept) — the security model in plain English.
Persona schema — how to attach skills to an agent.
skills.sh ↗ — the public registry.

SKILL.md schema