# Skills

Skills are reusable markdown documents that add domain-specific instructions or workflows for agents. Metadata is stored in `skills.yaml`; content is stored under `~/.agentteam/skills/`.

## Metadata

Skill markdown can include YAML front matter:

```markdown
---
id: code-review
name: Code Review
description: Review code changes for correctness and maintainability
version: "1.0"
author: team
tags: [review, quality]
---

# Code Review

Instructions for the agent...
```

The required metadata fields are `id` and `name`. If they are missing, the dashboard and CLI infer them from the Markdown heading and source filename or skill directory. A short description is inferred from the first body paragraph when no front matter description is present.

## Supported Imports

| Source | Supported |
|--------|-----------|
| Markdown | `.md`, `.markdown` |
| Archive | `.zip`, `.tar`, `.tar.gz`, `.tgz` |
| URL | `http://` or `https://` markdown/archive URLs |
| Repository URL | GitHub or GitLab URLs that can be resolved to an archive |

Archives are scanned for one or more `SKILL.md` files. A single discovered skill imports as one skill; multiple discovered skills import as a batch. Managed repository imports require each `SKILL.md` to start with YAML front matter containing `name` and `description`. The `name` is a display name and may contain uppercase letters, spaces, and non-ASCII text, but it must not contain `/`, `\`, `..`, or control characters; AgentTeam derives an internal path-safe directory name for the imported copy.

## Dashboard Workflow

The Skills page lets you:

- Sort skills by name, labels, or creation time
- Import from URL
- Import one or more local Markdown files, or import a local archive
- Infer missing `id`, `name`, and description metadata during import
- Edit name, description, and tags
- Delete a skill and its content file

The dashboard import endpoint accepts multipart form data with one or more `file` fields, or one `url`, plus optional metadata fields and `force=true` for overwrites. Metadata form fields are only needed when the caller wants to override the inferred values for a single source.

## CLI

```bash
agentteam skill list
agentteam skill list -f json
agentteam skill get <id>
agentteam skill import ./code-review.md
agentteam skill import ./skills.zip
agentteam skill import https://github.com/openai/superpowers
agentteam skill import ./custom.md --id custom --name "Custom Skill"
agentteam skill import ./custom.md --force
agentteam skill delete <id>
agentteam skill rm <id>
```

Import flags:

| Flag | Meaning |
|------|---------|
| `--id` | Skill ID when not provided by front matter |
| `--name` | Display name when not provided by front matter |
| `--description` | Description override |
| `--version` | Version |
| `--author` | Author |
| `--tags` | Comma-separated tags |
| `--force` / `-f` | Overwrite an existing skill without confirmation |

`skill list` and `skill get` support `--format/-f table|json|jsonc|yaml|toml`.

## Storage

Deleting a skill removes its metadata and its stored markdown content. Imported archives are unpacked into managed skill content paths; the original upload or temporary download is not retained.