> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fliiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills Overview

> How Fliiq's skill system works

Skills are self-contained tools the agent can call. Each skill does one thing — search the web, write a file, send an email, create a Spotify playlist. The agent picks the right skills based on your request.

## Skill Anatomy

Every skill is a directory with 3 required files (plus an optional test file):

```
skills/core/web_search/
  SKILL.md      # Metadata and usage instructions
  fliiq.yaml    # Input/output schema + credentials
  main.py       # Async handler function
  test_main.py  # Pytest tests (optional for manual skills, auto-generated for self-built skills)
```

### SKILL.md

YAML frontmatter with the skill name and description, plus markdown body with usage instructions for the LLM:

```markdown theme={null}
---
name: web_search
description: "Search the web using Brave Search API and return structured results."
---

Use this tool to search the web. Returns titles, URLs, and snippets.
Requires BRAVE_API_KEY environment variable.
```

### fliiq.yaml

JSON Schema defining inputs, outputs, and required credentials:

```yaml theme={null}
input_schema:
  type: object
  properties:
    query:
      type: string
      description: "The search query."
    count:
      type: integer
      description: "Number of results to return. Defaults to 5, max 20."
  required:
    - query

output_schema:
  type: object
  properties:
    results:
      type: string
      description: "JSON array of [{title, url, snippet}]."

credentials:
  - BRAVE_API_KEY
```

### main.py

An async Python function that receives parameters and returns a result:

```python theme={null}
async def handler(params: dict) -> dict:
    query = params["query"]
    # ... do the work ...
    return {"results": json.dumps(results)}
```

## Skill Discovery

Fliiq discovers skills from three locations, in priority order:

1. **Project skills** — `.fliiq/skills/` (project-specific, highest priority)
2. **User skills** — `~/.fliiq/skills/` (available globally)
3. **Core skills** — Bundled with the package (57 skills)

On startup, Fliiq scans all three locations. If the same skill name exists in multiple locations, the highest-priority version wins.

## Skill Types

<CardGroup cols={2}>
  <Card title="Core Skills" icon="cube">
    Ship with Fliiq. File I/O, search, shell, web, memory, communications.
    See the [full reference](/skills/core-skills).
  </Card>

  <Card title="User-Generated Skills" icon="wand-magic-sparkles">
    Created by the agent or by you. Stored in `.fliiq/skills/`.
    See [self-generating skills](/skills/self-generating).
  </Card>
</CardGroup>

## How the Agent Uses Skills

1. Your prompt is sent to the LLM along with all available skill definitions
2. The LLM picks the right skill(s) and generates the input parameters
3. Fliiq validates the parameters against `fliiq.yaml` input schema
4. Credentials from `fliiq.yaml` are loaded from `.env` into the environment
5. `main.py` handler is called with the parameters
6. The result is returned to the LLM for evaluation
7. The loop continues until the task is complete

## Next Steps

* [Core Skills Reference](/skills/core-skills) — Browse all 57 built-in skills
* [Authoring Skills](/skills/authoring) — Write your own skill
* [Self-Generating Skills](/skills/self-generating) — How the agent builds new skills autonomously