Skills

A skill is a directory bundle — a SKILL.md primary plus any declared companion files — containing domain-specific instructions, guidelines, or best practices. Skills follow the Agent Skills specification. They are the passive knowledge layer of a facet — text that shapes how an AI assistant approaches a domain without defining a persona or a user-invokable action. Each skill lives in its own directory at skills/<name>/SKILL.md and is declared in facet.json under the skills map. The normative rules — placement, descriptor shape, and the no-front-matter contract — live at Text assets in the manifest specification.

Example

A “code-review” skill (skills/code-review/SKILL.md):

skills/code-review/SKILL.md

# Code Review

## Structure
- Check that new files are placed in the correct directory.
- Verify imports are sorted and unused imports are removed.
- Confirm naming conventions match the project style.

## Logic
- Look for off-by-one errors in loops and array access.
- Verify error handling covers all failure paths.
- Check that async operations are awaited.
- Confirm discriminated unions are exhaustively matched.

## Testing
- Every new public function should have a corresponding test.
- Edge cases (empty input, null, boundary values) should be covered.
- Tests should not depend on execution order.

## Style
- Prefer `const` over `let` when the binding is never reassigned.
- Use early returns to reduce nesting.
- Do not comment obvious code.

Companion files

A skill can ship more than its SKILL.md. Declare companion files — references, scripts, templates — in the skill descriptor’s files array, as exact paths relative to the skill directory:

{
  "skills": {
    "code-review": {
      "description": "Code review guidelines",
      "files": ["references/style-guide.md", "scripts/lint.ts"]
    }
  }
}

Companions ship inside the archive and install and remove atomically with their skill; files you add to a skill directory yourself are left untouched on removal. They ship as opaque bytes (binary and empty files are fine), the skill name is still a single segment (the / in a companion path is directory depth, not part of the name), and a companion can’t be SKILL.md itself. See Supplementary files for the full rules.

When to use skills

Skills are passive knowledge — they inform how the assistant thinks and works but do not define who it is or what the user can invoke. Use skills for:

Coding standards and conventions
Review checklists
Domain-specific guidelines (API design, security practices, accessibility)
Framework best practices

Use agents when you need to define a persona with a specific role and behavior. Use commands when you need a user-invokable workflow that performs a specific task.

Agent Facets

Guides

Asset Types

Example

Companion files

When to use skills

Further reading

​Example

​Companion files

​When to use skills

​Further reading

Example

Companion files

When to use skills

Further reading