--- title: Write your first skill description: Define an actionable, reviewable method in SKILL.md. lastVerified: 2026-10-18 --- # 6.3 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: ```markdown --- 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/` 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`: `/@<40-character commit>:`, 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/@.json`: ```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](https://docs.teloa.ai/v/0.2.1/examples/general-research.zip). 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.