# Skill Authoring Guide

Skills are reusable AI workflows that extend the LLMTune CLI. Each skill is defined by a `SKILL.md` file inside a named directory.

## Quick Start

Create a skill in `~/.llmtune/skills/` or `.llmtune/skills/` in your project:

```
~/.llmtune/skills/
  my-skill/
    SKILL.md
```

## SKILL.md Format

A skill file has two parts: **YAML frontmatter** (optional) and **Markdown body** (the prompt template).

```markdown
---
description: "Fix ESLint errors in a file"
user-invocable: true
allowed-tools: [read, edit, glob, grep]
arguments: file_path
trust: local
---

You are a linting expert. Fix all ESLint errors in the file at `{{file_path}}`.

1. Read the file
2. Identify lint errors
3. Fix each error while preserving the original intent
4. Report what you changed
```

## Frontmatter Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `description` | string | (required) | Short description shown in `/skills` list |
| `user-invocable` | boolean | `true` | Whether users can invoke with `/<skill-name>` |
| `allowed-tools` | string[] | all tools | Restrict which tools the skill can use |
| `arguments` | string or string[] | none | Argument names for substitution |
| `trust` | string | `local` | Trust level: `local`, `community`, `verified`, `signed` |
| `when-to-use` | string | none | Hint for when the agent should auto-invoke this skill |

## Argument Substitution

Arguments are referenced in the body using `{{arg_name}}` syntax:

```markdown
---
arguments: file_path, style
---

Refactor the file at `{{file_path}}` to use `{{style}}` coding style.
```

When invoked: `/my-skill src/auth.ts functional`

- `{{file_path}}` becomes `src/auth.ts`
- `{{style}}` becomes `functional`

## Trust Levels

Skills have four trust levels that determine what tools they can access:

| Level | Tools Allowed | Use Case |
|-------|--------------|----------|
| **local** | All | Skills you create yourself in `~/.llmtune/skills/` |
| **community** | read, glob, grep only | Skills installed from marketplace |
| **verified** | All | Skills reviewed by the LLMTune team |
| **signed** | All | Cryptographically signed skills with verified authors |

## Invoking Skills

### From the CLI REPL

```
> /explain-code src/auth.ts
> /fix-lint src/utils/helpers.ts
> /generate-test src/services/user.ts
```

### From Commander (non-interactive)

```bash
llmtune skills run explain-code --args "src/auth.ts"
```

## Built-in Skills

The LLMTune CLI includes these built-in skills:

| Skill | Description | Arguments |
|-------|-------------|-----------|
| `explain-code` | Explain code with a clear breakdown | `file_path` |
| `fix-lint` | Auto-fix linting errors | `file_path` |
| `generate-test` | Generate unit tests for a file | `file_path` |
| `security-review` | Review code for security issues | `file_path` |

## Publishing to the Marketplace

```bash
# Sign your skill
llmtune skills sign my-skill

# Publish to marketplace
llmtune skills publish my-skill

# Install from marketplace
llmtune skills install security-review
```

## Examples

### Code Review Skill

```markdown
---
description: "Review code for best practices and potential issues"
allowed-tools: [read, glob, grep]
arguments: file_path
---

Review the code at `{{file_path}}` for:

1. **Security vulnerabilities** - XSS, injection, auth issues
2. **Performance problems** - N+1 queries, unnecessary re-renders, memory leaks
3. **Code quality** - Naming, structure, DRY violations
4. **Error handling** - Missing error cases, swallowed errors
5. **Type safety** - Any `any` types, missing null checks

Provide specific, actionable feedback with line numbers.
```

### Database Migration Skill

```markdown
---
description: "Generate a Prisma migration for schema changes"
allowed-tools: [read, write, edit, bash]
arguments: description
---

The user wants to make this database change: {{description}}

1. Read the current prisma/schema.prisma
2. Make the necessary schema changes
3. Generate the migration using `npx prisma migrate dev --name <descriptive-name>`
4. Report what changed
```

### API Endpoint Skill

```markdown
---
description: "Scaffold a new REST API endpoint"
allowed-tools: [read, write, edit, glob, grep]
arguments: method, path
---

Create a new API endpoint:

- Method: `{{method}}`
- Path: `{{path}}`

1. Find existing route files to understand the pattern
2. Create the route handler
3. Add input validation
4. Add error handling
5. Register the route

Follow the existing code patterns in the project.
```