skill-format

skill-format 문서는 OpenClaw 공식 문서(clawhub/skill-format)를 한국어로 정리한 가이드입니다. Skill folder format, required files, supporting artifacts, limits. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Skill folder format, required files, supporting artifacts, limits.

한국어 가이드 범위: clawhub/skill-format 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Skill format
On disk
GitHub import
SKILL.md
Frontmatter metadata
Basic frontmatter
Runtime metadata (metadata.openclaw)
Full field reference
Install specs
Optional environment variables
Why this matters
Example: complete frontmatter
Skill files
Slugs
Versioning + tags
License
Paid skills

상세 내용

Skill format

이 섹션의 세부 항목은 공식 문서 Skill format를 참고하세요.

On disk

주요 항목:

SKILL.md (or skill.md; legacy skills.md is also accepted)
any supporting regular files (see “Skill files”)
.clawhubignore (ignore patterns for publishing, legacy .clawdhubignore)
.gitignore (also honored)

GitHub import

The web GitHub importer is stricter than local publish/sync. It only discovers SKILL.md or legacy skills.md files in public, non-fork repositories owned by the signed-in GitHub account. It does not import private repos, forks, archived/disabled repos, or third-party public repos.

주요 항목:

<skill>/.clawhub/origin.json (legacy .clawdhub)
<workdir>/.clawhub/lock.json (legacy .clawdhub)

SKILL.md

For portable Agent Skills, name should match the parent directory and use 1–64 lowercase letters, numbers, or hyphens. ClawHub keeps the routable slug and catalog display name separate, so existing names from other clients remain publishable and are not silently rewritten. Catalog lists may shorten long names visually without changing the stored name.

주요 항목:

Markdown with optional YAML frontmatter.
The server extracts metadata from frontmatter during publish.
description is used as the skill summary in the UI/search.

Frontmatter metadata

Skill metadata is declared in the YAML frontmatter at the top of your SKILL.md. This tells the registry (and security analysis) what your skill needs to run.

Basic frontmatter

---
name: my-skill
description: Short summary of what this skill does.
version: 1.0.0
---

Runtime metadata (metadata.openclaw)

Declare your skill's runtime requirements under metadata.openclaw (aliases: metadata.clawdbot, metadata.clawdis).

주요 항목:

TODOIST_API_KEY
curl

---
name: my-skill
description: Manage tasks via the Todoist API.
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
---

Full field reference

Field	Type	Description
`requires.env`	`string[]`	Required environment variables your skill expects.
`requires.bins`	`string[]`	CLI binaries that must all be installed.
`requires.anyBins`	`string[]`	CLI binaries where at least one must exist.
`requires.config`	`string[]`	Config file paths your skill reads.
`primaryEnv`	`string`	The main credential env var for your skill.
`envVars`	`array`	Environment variable declarations with `name`, optional `required`, and optional `description`. Set `required: false` for optional env vars.
`always`	`boolean`	If `true`, skill is always active (no explicit install needed).
`skillKey`	`string`	Override the skill's invocation key.
`emoji`	`string`	Display emoji for the skill.
`homepage`	`string`	URL to the skill's homepage or docs.
`os`	`string[]`	OS restrictions (e.g. `["macos"]`, `["linux"]`).
`install`	`array`	Install specs for dependencies (see below).
`nix`	`object`	Nix plugin spec (see README).
`config`	`object`	Clawdbot config spec (see README).

Install specs

If your skill needs dependencies installed, declare them in the install array:

주요 항목:

kind: brew
kind: node

metadata:
  openclaw:
    install:
      - kind: brew
        formula: jq
        bins: [jq]
      - kind: node
        package: typescript
        bins: [tsc]

Optional environment variables

Declare optional environment variables under metadata.openclaw.envVars and set required: false. Do not add optional entries to requires.env, because requires.env means the skill cannot run without them.

주요 항목:

name: TODOIST_API_KEY
name: TODOIST_PROJECT_ID

metadata:
  openclaw:
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token used for authenticated requests.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID when the user does not specify one.

Why this matters

ClawHub's security analysis checks that what your skill declares matches what it actually does. If your code references TODOIST_API_KEY but your frontmatter doesn't declare it under requires.env, primaryEnv, or envVars, the analysis will flag a metadata mismatch. Keeping declarations accurate helps your skill pass review and helps users understand what they're installing.

Example: complete frontmatter

주요 항목:

TODOIST_API_KEY
curl
name: TODOIST_API_KEY
name: TODOIST_PROJECT_ID

---
name: todoist-cli
description: Manage Todoist tasks, projects, and labels from the command line.
version: 1.2.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID.
    emoji: "\u2705"
    homepage: https://github.com/example/todoist-cli
---

Skill files

Publish accepts all regular files in the skill folder, regardless of extension. Ignore files, hidden paths, symlinks, macOS metadata, and server-side size limits still apply.

주요 항목:

Bounded files that contain valid UTF-8 can be previewed as escaped plain text and are included
Other files keep their exact bytes and are available to download.
Security scanners receive the complete stored artifact; text detection is a rendering and
Total bundle size: 50MB.
Embedding text includes SKILL.md + up to ~40 bounded UTF-8 files (best-effort cap).

Slugs

주요 항목:

Derived from folder name by default.
Package scopes must match the ClawHub publisher handle exactly. Publisher handles can use lowercase letters, numbers, hyphens, dots, and underscores; they must start and end with a lowercase letter or number.
Package slugs must be lowercase and npm-safe, for example @example.tools/demo-plugin or demo-plugin.

Versioning + tags

주요 항목:

Each publish creates a new version (semver).
Tags are string pointers to a version; latest is commonly used.

License

주요 항목:

All skills published on ClawHub are licensed under MIT-0.
Anyone may use, modify, and redistribute published skills, including commercially.
Attribution is not required.
Do not add conflicting license terms in SKILL.md; ClawHub does not support per-skill license overrides.

Paid skills

주요 항목:

ClawHub does not support paid skills, per-skill pricing, paywalls, or revenue sharing.
Do not add pricing metadata to SKILL.md; it is not part of the skill format and will not make a published skill paid.
If your skill integrates with a paid third-party service, document the external cost and required account clearly in the skill instructions and env declarations (requires.env for required variables, or envVars with required: false for optional variables).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/clawhub/skill-format
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

---
name: my-skill
description: Short summary of what this skill does.
version: 1.0.0
---

---
name: my-skill
description: Manage tasks via the Todoist API.
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
---

metadata:
  openclaw:
    install:
      - kind: brew
        formula: jq
        bins: [jq]
      - kind: node
        package: typescript
        bins: [tsc]

metadata:
  openclaw:
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token used for authenticated requests.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID when the user does not specify one.

---
name: todoist-cli
description: Manage Todoist tasks, projects, and labels from the command line.
version: 1.2.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID.
    emoji: "\u2705"
    homepage: https://github.com/example/todoist-cli
---

skill-format

핵심 요약

Skill folder format, required files, supporting artifacts, limits.

한국어 가이드 범위: clawhub/skill-format 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Skill format
On disk
GitHub import
SKILL.md
Frontmatter metadata
Basic frontmatter
Runtime metadata (metadata.openclaw)
Full field reference
Install specs
Optional environment variables
Why this matters
Example: complete frontmatter
Skill files
Slugs
Versioning + tags
License
Paid skills

상세 내용

Skill format

이 섹션의 세부 항목은 공식 문서 Skill format를 참고하세요.

On disk

주요 항목:

SKILL.md (or skill.md; legacy skills.md is also accepted)
any supporting regular files (see “Skill files”)
.clawhubignore (ignore patterns for publishing, legacy .clawdhubignore)
.gitignore (also honored)

GitHub import

주요 항목:

<skill>/.clawhub/origin.json (legacy .clawdhub)
<workdir>/.clawhub/lock.json (legacy .clawdhub)

SKILL.md

주요 항목:

Markdown with optional YAML frontmatter.
The server extracts metadata from frontmatter during publish.
description is used as the skill summary in the UI/search.

Frontmatter metadata

Skill metadata is declared in the YAML frontmatter at the top of your SKILL.md. This tells the registry (and security analysis) what your skill needs to run.

Basic frontmatter

---
name: my-skill
description: Short summary of what this skill does.
version: 1.0.0
---

Runtime metadata (metadata.openclaw)

Declare your skill's runtime requirements under metadata.openclaw (aliases: metadata.clawdbot, metadata.clawdis).

주요 항목:

TODOIST_API_KEY
curl

---
name: my-skill
description: Manage tasks via the Todoist API.
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
---

Full field reference

Field	Type	Description
`requires.env`	`string[]`	Required environment variables your skill expects.
`requires.bins`	`string[]`	CLI binaries that must all be installed.
`requires.anyBins`	`string[]`	CLI binaries where at least one must exist.
`requires.config`	`string[]`	Config file paths your skill reads.
`primaryEnv`	`string`	The main credential env var for your skill.
`envVars`	`array`	Environment variable declarations with `name`, optional `required`, and optional `description`. Set `required: false` for optional env vars.
`always`	`boolean`	If `true`, skill is always active (no explicit install needed).
`skillKey`	`string`	Override the skill's invocation key.
`emoji`	`string`	Display emoji for the skill.
`homepage`	`string`	URL to the skill's homepage or docs.
`os`	`string[]`	OS restrictions (e.g. `["macos"]`, `["linux"]`).
`install`	`array`	Install specs for dependencies (see below).
`nix`	`object`	Nix plugin spec (see README).
`config`	`object`	Clawdbot config spec (see README).

Install specs

If your skill needs dependencies installed, declare them in the install array:

주요 항목:

kind: brew
kind: node

metadata:
  openclaw:
    install:
      - kind: brew
        formula: jq
        bins: [jq]
      - kind: node
        package: typescript
        bins: [tsc]

Optional environment variables

주요 항목:

name: TODOIST_API_KEY
name: TODOIST_PROJECT_ID

metadata:
  openclaw:
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token used for authenticated requests.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID when the user does not specify one.

Why this matters

Example: complete frontmatter

주요 항목:

TODOIST_API_KEY
curl
name: TODOIST_API_KEY
name: TODOIST_PROJECT_ID

---
name: todoist-cli
description: Manage Todoist tasks, projects, and labels from the command line.
version: 1.2.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID.
    emoji: "\u2705"
    homepage: https://github.com/example/todoist-cli
---

Skill files

Publish accepts all regular files in the skill folder, regardless of extension. Ignore files, hidden paths, symlinks, macOS metadata, and server-side size limits still apply.

주요 항목:

Bounded files that contain valid UTF-8 can be previewed as escaped plain text and are included
Other files keep their exact bytes and are available to download.
Security scanners receive the complete stored artifact; text detection is a rendering and
Total bundle size: 50MB.
Embedding text includes SKILL.md + up to ~40 bounded UTF-8 files (best-effort cap).

Slugs

주요 항목:

Derived from folder name by default.
Package scopes must match the ClawHub publisher handle exactly. Publisher handles can use lowercase letters, numbers, hyphens, dots, and underscores; they must start and end with a lowercase letter or number.
Package slugs must be lowercase and npm-safe, for example @example.tools/demo-plugin or demo-plugin.

Versioning + tags

주요 항목:

Each publish creates a new version (semver).
Tags are string pointers to a version; latest is commonly used.

License

주요 항목:

All skills published on ClawHub are licensed under MIT-0.
Anyone may use, modify, and redistribute published skills, including commercially.
Attribution is not required.
Do not add conflicting license terms in SKILL.md; ClawHub does not support per-skill license overrides.

Paid skills

주요 항목:

ClawHub does not support paid skills, per-skill pricing, paywalls, or revenue sharing.
Do not add pricing metadata to SKILL.md; it is not part of the skill format and will not make a published skill paid.
If your skill integrates with a paid third-party service, document the external cost and required account clearly in the skill instructions and env declarations (requires.env for required variables, or envVars with required: false for optional variables).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/clawhub/skill-format
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

---
name: my-skill
description: Short summary of what this skill does.
version: 1.0.0
---

---
name: my-skill
description: Manage tasks via the Todoist API.
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
---

metadata:
  openclaw:
    install:
      - kind: brew
        formula: jq
        bins: [jq]
      - kind: node
        package: typescript
        bins: [tsc]

metadata:
  openclaw:
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token used for authenticated requests.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID when the user does not specify one.

---
name: todoist-cli
description: Manage Todoist tasks, projects, and labels from the command line.
version: 1.2.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token.
      - name: TODOIST_PROJECT_ID
        required: false
        description: Optional default project ID.
    emoji: "\u2705"
    homepage: https://github.com/example/todoist-cli
---

skill-format

핵심 요약

문서 구성

상세 내용

Skill format

On disk

GitHub import

SKILL.md

Frontmatter metadata

Basic frontmatter

Runtime metadata (metadata.openclaw)

Full field reference

Install specs

Optional environment variables

Why this matters

Example: complete frontmatter

Skill files

Slugs

Versioning + tags

License

Paid skills

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

skill-format

핵심 요약

문서 구성

상세 내용

Skill format

On disk

GitHub import

SKILL.md

Frontmatter metadata

Basic frontmatter

Runtime metadata (metadata.openclaw)

Full field reference

Install specs

Optional environment variables

Why this matters

Example: complete frontmatter

Skill files

Slugs

Versioning + tags

License

Paid skills

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드