6.2 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 declared during import. The display title can use Chinese characters.

Import and verify

Open Market → Import → Import Skill and select the directory containing SKILL.md. Enter the ID research-brief, display name “Research brief,” and version 1.0.0. Save the skill, then review its description and content on the resource page.

Open the imported resource and complete installation or activation as indicated by its status. Pause the research colleague before changing its configuration, link the skill, then resume the colleague. 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 colleague 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 pin the old version. If import is rejected, check the frontmatter, identity match, directory boundaries, and encoding first.

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. Relationship declarations in the package do not automatically grant tool permissions.