# Motiframe Agent Skill

Connectez votre agent IA (Claude Code, GitHub Copilot CLI, Hermes Agent…) à
**Motiframe** pour générer des visuels à partir de vos templates, en langage
naturel — et laisser l'agent **inspecter le rendu** pour vérifier l'alignement,
exactement comme un humain.

Cette skill est volontairement minimale et sûre : un manifeste
[`SKILL.md`](./SKILL.md) qui décrit la marche à suivre, et un unique script
`curl` [`scripts/motiframe.sh`](./scripts/motiframe.sh). Pas de serveur à
héberger, pas de dépendance lourde.

## 1. Pré-requis

- `curl` (présent partout). `jq` ou `python3` sont utilisés s'ils existent pour
  un affichage JSON plus lisible, mais ne sont pas obligatoires.
- Un compte Motiframe et une **clé d'API**.

### Créer une clé d'API

1. Connectez-vous sur <https://motiframe.com> → ouvrez l'app.
2. Menu compte (en haut à droite) → **Clés d'API** → **Créer une clé**.
3. Copiez la clé `mf_live_…` : elle n'est affichée **qu'une seule fois**.
4. Vous pouvez révoquer une clé à tout moment depuis le même écran.

> Conseil de sécurité : créez une clé dédiée par agent/machine. Si elle fuite,
> révoquez-la sans impacter vos autres intégrations.

## 2. Configuration

Exportez votre clé dans l'environnement (ne la committez jamais) :

```bash
export MOTIFRAME_API_KEY="mf_live_votre_cle"
# Optionnel — par défaut https://api.motiframe.com :
# export MOTIFRAME_API_BASE="https://api.motiframe.com"
```

Vérifiez que tout fonctionne :

```bash
./scripts/motiframe.sh check
# → OK — clé valide, API joignable sur https://api.motiframe.com
```

Voir [`.env.example`](./.env.example) pour la liste des variables.

## 3. Installer la skill dans votre agent

> **Méthode rapide (hébergée).** La skill est servie publiquement sur
> <https://motiframe.com/agent-skill/> — aucun accès au dépôt n'est nécessaire.
> Le strict minimum pour piloter l'API depuis n'importe quel agent à terminal :
>
> ```bash
> curl -fsSL https://motiframe.com/agent-skill/scripts/motiframe.sh -o motiframe.sh
> chmod +x motiframe.sh
> export MOTIFRAME_API_KEY="mf_live_..."
> ./motiframe.sh check
> ```

### Claude Code

Les skills sont des dossiers chargés depuis un répertoire de skills. Récupérez
le `SKILL.md` et le script depuis le site (ou copiez ce dossier si vous avez le
dépôt), puis exportez votre clé :

```bash
mkdir -p ~/.claude/skills/motiframe/scripts
curl -fsSL https://motiframe.com/agent-skill/SKILL.md \
  -o ~/.claude/skills/motiframe/SKILL.md
curl -fsSL https://motiframe.com/agent-skill/scripts/motiframe.sh \
  -o ~/.claude/skills/motiframe/scripts/motiframe.sh
chmod +x ~/.claude/skills/motiframe/scripts/motiframe.sh
export MOTIFRAME_API_KEY="mf_live_..."
```

Claude Code découvre automatiquement la skill via son `SKILL.md` et l'active
quand vous demandez, par exemple : « génère une bannière Soldes -40 % à partir
de mon template `summer-sale` ».

### GitHub Copilot CLI

Téléchargez le script, rendez-le accessible et exportez la clé dans votre shell :

```bash
curl -fsSL https://motiframe.com/agent-skill/scripts/motiframe.sh -o motiframe.sh
chmod +x motiframe.sh
export MOTIFRAME_API_KEY="mf_live_..."
export PATH="$PATH:$(pwd)"
```

Donnez ensuite à Copilot le contenu de `SKILL.md` comme contexte (ou ajoutez-le
à vos instructions de dépôt), puis demandez-lui d'utiliser `motiframe.sh` pour
lister les templates et lancer un rendu.

### Hermes Agent (et autres agents à terminal)

Tout agent capable d'exécuter des commandes shell peut utiliser la skill :

1. Téléchargez `scripts/motiframe.sh` (URL ci-dessus) et exposez-le dans le
   `PATH` de l'agent (ou donnez son chemin absolu).
2. Fournissez `MOTIFRAME_API_KEY` via l'environnement.
3. Donnez `SKILL.md` à l'agent comme procédure de référence.

## 4. Exemple de bout en bout

```bash
# 1. Quels templates ai-je ?
./scripts/motiframe.sh templates

# 2. Quels calques puis-je modifier ?
./scripts/motiframe.sh layers summer-sale

# 3. Générer (téléchargé en motiframe-render.png)
./scripts/motiframe.sh render summer-sale \
  --overrides '{"title":{"text":"Soldes -40%"},"bg":{"fill":"#4f46e5"}}'

# 4. (l'agent ouvre motiframe-render.png et vérifie le rendu, puis itère)

# 5. Version hébergée pour publication
./scripts/motiframe.sh render summer-sale \
  --overrides '{"title":{"text":"Soldes -40%"}}' --url
```

## 5. Sécurité

- **Clé jamais en clair** : lue uniquement depuis `MOTIFRAME_API_KEY`, transmise
  via l'en-tête `x-api-key`, jamais dans une URL ni un log.
- **HTTPS imposé** : le script refuse une base non-HTTPS (sauf `localhost` pour
  le développement).
- **Périmètre minimal** : une clé d'API n'accède qu'aux ressources de **votre**
  compte ; les rendus sont décomptés de votre quota mensuel.
- **Révocable** : supprimez une clé compromise depuis l'app, effet immédiat.

## Référence des commandes

```text
check                       Vérifie la clé et la connectivité
templates                   Liste les templates du compte
template <id>               Affiche un template complet (JSON)
layers <id>                 Liste les calques (= clés de surcharge)
render <id> [options]       Génère une image
    --overrides '<json>'      Surcharges par calque
    --scale <n>               Échelle 1–4 (défaut 1)
    --out <fichier.png>       Chemin de sortie
    --url                     URL hébergée au lieu d'un fichier local
upload <fichier-image>      Téléverse une image, renvoie son URL
```