6.4 Write your first skill

A skill describes a method. It is neither a tool permission nor a set of model weights. Start with a clearly scoped task whose result you can check.

Minimal format

Place a UTF-8 SKILL.md file in a directory:

---
name: research-brief
description: Produce a research brief with sources from authorized materials, separating facts, inferences, and items to verify.
---

# Research brief

1. State the question, audience, and deadline.
2. Attach a source to each fact; mark unsupported claims for verification.
3. List inferences, disagreements, and uncertainties separately.
4. Provide conclusions and a verification checklist. Do not send anything externally.

Use lowercase ASCII letters and digits in name, separated by single hyphens, for example research-brief. Do not use Chinese characters, spaces, underscores, or a filename as the skill ID. The name must match the skill identity entered during import. The display title can use Chinese characters.

Import and verify

Choose + at the upper right of Marketplace or Apps, then Import Skill (Import a skill in Apps), and select a single directory containing SKILL.md. The name and ID are read from it; to change them, expand Name and version and enter the resource ID research-brief, the name “Research brief,” and the locked version 1.0.0. Choose Save Skill content, then review the description and content on the resource page.

Open the imported skill’s details and complete installation or activation as indicated by its status. Pause the research employee before changing its configuration, link the skill, then resume the employee. Return to Capabilities to check its status. Importing the directory, installing it in the runtime, and linking it to a role are separate steps.

Give the employee some fictional source material and ask it to use the skill. Check that the result separates facts from inferences, preserves sources, and does not call external tools without permission.

Updates and failures

Increase the version when updating a skill, and check whether task templates that reference it still lock the old version. If import is rejected, check the frontmatter, identity match, directory boundaries, and encoding first.

License files for skills from external repositories

When cataloging a GitHub skill, marketplace maintainers must lock the repository commit and, for each file, its SHA-256 digest, Git blob digest and byte count. The generator computes SHA-256 from the locked bytes in the research cache; the Git blob digest is only used to locate the file in the GitHub tree. Adding and installing download each file and check it; any mismatch is rejected. Downloading only the skill directory must not omit a license stored at the repository root or in an ancestor directory.

The new catalog protocol uses repositoryPath in upstream.files for the original license path. The installed path must be licenses/upstream/<repositoryPath> and must also appear in license.files. For example, a root LICENSE is installed as licenses/upstream/LICENSE, preserving it separately from the skill's own LICENSE. Root or ancestor NOTICE files are locked the same way, without rewriting their contents.

This mapping supports only LICENSE, LICENCE, NOTICE, COPYING and their .txt, .md or .rst forms, plus THIRD_PARTY_NOTICES.md. It does not accept other skills, scripts, links or arbitrary URLs. File paths in the catalog must not contain C1 control characters, line or paragraph separators, or bidirectional text controls. Changing the original path, commit, digest or size changes the checksum on the confirmation card and requires another review. Generation fails when a locked license file is missing; existing resources are not upgraded automatically. This capability is included in alpha.7. Each resource still requires marketplace source review and a fixed version before catalog publication.

Derived resources

When the resource files differ from the original in any way (fixes, removals, adaptations, new files, improvements or localization), the resource is listed with files stored in the marketplace: the entry uses delivery: "install" with the locked source upstream and the change list derivation. Original entries with delivery: "upstream" are only for unchanged originals: the listed files are fetched from the original source one by one against their locked digests, and their modifications only explain which files were not included. A resource with any changed byte cannot be written as an original entry.

derivation has two fields. unchangedFiles lists files that match the original byte for byte; their digests in the resource files must equal the sha256 locked in upstream.files. changes holds 1–200 changes. Each change has:

• id: a number unique within the entry, for example CSB-M01.
• type: one of seven types. When a change fits several, use the earliest: security (security fix), fixed (fix), removed, adapted, added, improved, localized.
• path: the file path in the resource files; for a removed original file, the original path. Put a section or line number in the optional section.
• upstream: <owner>/<repo>@<40-character commit>:<path in repository>, pointing to an original file in the same repository and commit that the entry locks; null for new files that the original does not have.
• summary and reason: one Chinese and one English text each, at most 1000 characters per language, shown in the marketplace.

With derivation, modifications must be empty and every item in upstream.files needs sha256. Apart from unchangedFiles and the root MODIFICATIONS.md, every resource file must be referenced by the path of at least one change, and every original file that is not included needs a removed change. License files are no exception: a license shipped as is belongs in unchangedFiles. File paths that differ only in letter case are rejected, because they overwrite each other on case-insensitive file systems. A license file at the root of the original repository is identified with repositoryPath and placed at LICENSE or LICENSE.txt in the resource root.

Put MODIFICATIONS.md at the resource root with every change number and the full technical notes. Every changed or added file must mention MODIFICATIONS.md within its first 4 KiB, for example a line such as "Modified by Teloa; see MODIFICATIONS.md" at the start of the SKILL.md body. This meets the prominent change notice required by section 4(b) of Apache-2.0 and works the same for other licenses.

The verification record for our changes lives in the marketplace repository at reviews/derivatives/<id>@<version>.json:

{"format":"teloa.derivative-review/v1","entryId":"openai.security-best-practices","version":"1.0.0","reviewedAt":"2026-09-28","reviewer":"Teloa",
 "changeChecks":[{"changeId":"CSB-M01","method":"test","result":"pass","evidence":"..."}]}

Each change has exactly one check and result must be pass. method is test, reproduction, source-check or review; security and fixed changes cannot rely on review alone. evidence is at most 1000 characters. The record is review evidence: it is not part of the catalog entry and is not shown in the interface.

Entries that use derivation, sha256 or repositoryPath on original files of an install entry, or the install count source origin.installsSource of an original entry, need a compatibility.teloa lower bound of at least 0.2.0-alpha.7, and they only appear in the newer index. An original entry with an install count from a marketplace other than ClawHub must give its source (url is a public https address, scope is resource or plugin, and countedAt is the retrieval date); without an install count, leave the source out. The marketplace validator node tools/validate.mjs checks each of these rules and reports problems with rule identifiers such as derivative.*.

Download the complete general research example package. It includes a valid skill, role, reference document, and task template. The example content is in Chinese; the package format is language-independent. Relationships listed in the package do not automatically grant tool permissions.