> ## 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.

# Self-Generating Skills

> How Fliiq builds its own capabilities

When you ask Fliiq to do something it can't do, it doesn't say "I can't do that." It offers to build the capability.

## How It Works

<Steps>
  <Step title="Gap Detection">
    The agent scans its available skills and detects no existing skill matches the request.
  </Step>

  <Step title="Permission">
    The agent asks: "I don't have a Spotify integration. Want me to build one?"
  </Step>

  <Step title="Research">
    Using `web_search` and `web_fetch`, the agent reads the target API's documentation.
  </Step>

  <Step title="Template">
    The agent reads an existing skill (like `web_search`) as a reference for the 3-file format.
  </Step>

  <Step title="Generation">
    The agent generates `SKILL.md`, `fliiq.yaml` (with `test_example`), `main.py`, and `test_main.py` for the new skill.
  </Step>

  <Step title="Installation">
    The skill is validated and registered into the live session via the `install_skill` tool.
  </Step>

  <Step title="Verification">
    The agent runs `pytest` on `test_main.py` and calls the skill as a tool with the `test_example` params from `fliiq.yaml`. Both must pass before the skill is considered ready.
  </Step>

  <Step title="Usage">
    The agent uses the verified skill to complete your original request.
  </Step>
</Steps>

## Real Example: Spotify Integration

A user asked Fliiq to create a workout playlist on Spotify. Here's what happened:

### The conversation

```
User: Create a chill jazz playlist on my Spotify with 15 tracks

Agent: I don't have a Spotify integration skill. I can build one that
       connects to the Spotify Web API. Want me to create it?

User: Yes

Agent: I'll research the Spotify API and build a skill for creating
       playlists, searching tracks, and adding tracks to playlists.
```

### What the agent generated

**SKILL.md** — metadata and LLM instructions:

```markdown theme={null}
---
name: spotify
description: "Create and manage Spotify playlists using the Spotify Web API."
---

Use this tool to create playlists, add tracks, and search for music
on Spotify. Requires SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, and
SPOTIFY_ACCESS_TOKEN environment variables.

## Available Actions
- create_playlist: Create a new playlist
- search_tracks: Search for tracks to add to playlists
- add_tracks_to_playlist: Add tracks to an existing playlist
```

**fliiq.yaml** — schema with actions, parameters, and credentials:

```yaml theme={null}
input_schema:
  type: object
  properties:
    action:
      type: string
      enum: ["create_playlist", "search_tracks", "add_tracks_to_playlist"]
      description: "Action to perform"
    name:
      type: string
      description: "Playlist name (for create_playlist)"
    query:
      type: string
      description: "Search query for tracks (for search_tracks)"
    playlist_id:
      type: string
      description: "Spotify playlist ID (for add_tracks_to_playlist)"
    track_uris:
      type: array
      items:
        type: string
      description: "Array of Spotify track URIs (for add_tracks_to_playlist)"
  required:
    - action

credentials:
  - SPOTIFY_CLIENT_ID
  - SPOTIFY_CLIENT_SECRET
  - SPOTIFY_ACCESS_TOKEN

test_example:
  params:
    action: search_tracks
    query: "chill jazz"
  expected_keys:
    - success
    - tracks
```

**main.py** — async handler with httpx calls to Spotify Web API:

```python theme={null}
import os
import httpx


async def handler(params: dict) -> dict:
    """Handle Spotify API operations."""
    action = params["action"]

    client_id = os.environ.get("SPOTIFY_CLIENT_ID")
    client_secret = os.environ.get("SPOTIFY_CLIENT_SECRET")
    access_token = os.environ.get("SPOTIFY_ACCESS_TOKEN")

    if not all([client_id, client_secret, access_token]):
        return {
            "success": False,
            "message": "Missing Spotify credentials. Set SPOTIFY_CLIENT_ID, "
                       "SPOTIFY_CLIENT_SECRET, and SPOTIFY_ACCESS_TOKEN.",
            "data": {}
        }

    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }

    async with httpx.AsyncClient(timeout=30) as client:
        if action == "create_playlist":
            return await create_playlist(client, headers, params)
        elif action == "search_tracks":
            return await search_tracks(client, headers, params)
        elif action == "add_tracks_to_playlist":
            return await add_tracks_to_playlist(client, headers, params)
```

**test\_main.py** — pytest tests to verify the skill works:

```python theme={null}
import pytest
from main import handler


@pytest.mark.asyncio
async def test_search_tracks():
    result = await handler({"action": "search_tracks", "query": "chill jazz"})
    assert result["success"] is True
    assert "tracks" in result


@pytest.mark.asyncio
async def test_create_playlist():
    result = await handler({"action": "create_playlist", "name": "Test Playlist"})
    assert result["success"] is True
    assert "playlist_id" in result
```

### The result

After generating, installing, and verifying the skill, the agent:

1. Searched for "chill jazz" tracks
2. Created a playlist named "Chill Jazz"
3. Added 15 tracks to the playlist
4. Returned the playlist URL

The entire process — gap detection, API research, skill generation, installation, and playlist creation — happened in a single conversation.

## Skill Persistence

Generated skills are saved to `.fliiq/skills/<name>/`. They persist across sessions — the next time you ask anything Spotify-related, the skill is already there.

```bash theme={null}
fliiq skill-list
# Shows:
# spotify  (local)  Create and manage Spotify playlists
```

## What Can the Agent Build?

Any HTTP-based API integration:

* **SaaS APIs** — Slack, Notion, Linear, Jira, GitHub
* **Data services** — weather, stocks, news, currency conversion
* **Media** — Spotify, YouTube, podcast feeds
* **Communication** — WhatsApp, Discord, custom webhooks
* **Internal APIs** — Your company's REST endpoints

The constraint is that the skill must be an async Python function using `httpx`. If the API has an HTTP endpoint, Fliiq can build a skill for it.

## Promoting Generated Skills

Once you've validated a generated skill, promote it to core so it ships with your project:

```bash theme={null}
fliiq skill-promote spotify
```

This moves the skill from `.fliiq/skills/` to `skills/core/` — it's now a permanent part of your Fliiq installation. See [Promoting Skills](/skills/promoting).