# Skill Authoring Guide

## Skill Structure

A skill is a directory with the following layout:

```
{skill-name}/SKILL.md          # Required — skill description and usage
{skill-name}/scripts/         # Optional — executable scripts
{skill-name}/workflows/        # Optional — process guides
{skill-name}/docs/            # Optional — supplementary documentation
```

## Writing Requirements

**SKILL.md must start with a YAML frontmatter block:**

```yaml
---
name: {skill-name}
description: {when-to-use}
---
```

**SKILL.md body should be concise.** It serves as a table of contents for workflows — list each workflow file path with the scenario that triggers it. For supplementary documentation, use `docs/`.

> **All skill-related documentation must be written in English.**

## When to Use Scripts vs Workflows

- **Scripts** — handle logic/flow that is completely fixed. When the steps are predictable and always the same, encode them in a script.
- **Workflows** — handle flexible situations semantically. When context matters, decisions are needed, or the process is nuanced, describe it in a workflow document.

## Script Hint

When a script needs to behave differently based on the calling agent, use these environment variables:

- `AGENT_ID` — the agent ID executing the script
- `AGENT_WORKSPACE` — the workspace of the agent executing the script

For more agent info, call `ego-mgr get <column>` inside the script.