Documentation

macOS / Linux — Homebrew

# Ajouter le tap STH (une seule fois)
brew tap skills-transfer-hub/sth

# Approuver le tap — requis pour un tap tiers depuis Homebrew 6.0 (une seule fois)
brew trust skills-transfer-hub/sth

# Installer
brew install skills-transfer-hub/sth/sth

# Vérifier
sth version

Les étapes tap et trust ne se font qu'une seule fois — trust est le gate de sécurité de Homebrew 6.0 sur les taps tiers. Ensuite, mettez STH à jour avec brew upgrade sth, pas sth update self.

Windows — winget ou Chocolatey

# winget
winget install STH.STH

# Scoop
scoop bucket add sth https://github.com/Skills-transfer-hub/scoop-sth
scoop install sth

# Chocolatey
choco install sth

Binaire depuis GitHub Releases

Si vous préférez une installation manuelle ou que vous êtes sur une plateforme non couverte, téléchargez l'archive correspondante depuis la page Releases (chaque archive est accompagnée d'un fichier SHA256SUMS pour vérifier l'intégrité), puis placez le binaire dans votre PATH.

# macOS / Linux
tar -xzf sth-darwin-arm64.tar.gz   # ou linux-amd64, darwin-amd64
chmod +x sth
sudo mv sth /usr/local/bin/

# Windows : extraire sth-windows-amd64.zip et déplacer sth.exe dans un dossier de %PATH%

Vérifier l'installation

sth version

Depuis la racine de votre projet (typiquement un dossier qui contient déjà .claude/) :

sth init
? Fournisseur          › github | gitlab | azure-devops | bitbucket
? Dépôt / org-projet   › acme-corp/skills
? Branche / ref        › main
? Catalogue            › SKILLS.md
? Dossier cible        › .claude/skills

La configuration est écrite dans .sth/project.json (schema v2). Aucun secret n'y est stocké — STH lit les tokens Git depuis votre environnement.

Lancer sth sans argument dans un terminal interactif ouvre le menu guidé qui propose la prochaine action utile (init, list, install, update, buddy…).

Lancer sth sans argument dans un terminal interactif joue une courte animation de réveil — 💤 puis 👀 — puis fige Buddy sur l'état réel du projet (à jour, mise à jour disponible, pas de configuration, etc.). Le tout dans un encadré de 78 caractères de large, parfait pour les terminaux modernes.

╭────────────────────────────────────────────────────────────────────────────╮
│                                                                            │
│      💧                                                                    │
│    ╭─────╮   STH dev                                                       │
│    │ >/< │   Skills Transfer Hub.                                          │
│    ╰─────╯                                                                 │
│                                                                            │
│  Astuce : tapez `sth help` pour voir la liste des commandes.               │
│  STH gère .claude/skills depuis un dépôt distant.                          │
│                                                                            │
╰────────────────────────────────────────────────────────────────────────────╯

Hors TTY (sortie redirigée, exécution en CI), seule la frame finale est imprimée — pas d'animation, pas de réécriture du buffer.

STH s'appuie sur les variables d'environnement de votre shell pour les providers Git. La variable générique STH_TOKEN est tentée en premier, suivie de la variable spécifique au provider. Aucun secret n'est persisté dans .sth/.

Pour la CI, exportez le PAT adéquat dans le contexte de la pipeline. Les installations self-hosted (GitHub Enterprise, GitLab self-managed) ne sont pas encore supportées — ouvrez une issue si le besoin est critique.

STH peut découvrir vos skills de trois manières — choisissez celle qui colle à votre dépôt.

1. SKILLS.md (manifeste explicite)

| Type  | Name           | Folder | Source                    | Description           |
| ----- | -------------- | ------ | ------------------------- | --------------------- |
| skill | analyse-risque | skills | skills/analyse-risque.md  | Check-list QSE        |
| agent | reviewer       | agents | agents/reviewer.md        | Revue de PR auto      |

2. Auto-détection (bundles)

Si votre dépôt suit la convention category/folder/SKILL.md, STH détecte les bundles automatiquement :

react/form-wizard/SKILL.md         → bundle "react/form-wizard"
react/form-wizard/templates/...    → tous les fichiers synchronisés
commands/release-helper/SKILL.md   → bundle "commands/release-helper"

3. Layouts enterprise / multi-stack

Pour les dépôts plus larges qui mêlent plusieurs types d'artefacts (skills, agents, commandes, instructions scopées par langage) dans une seule source de vérité, STH embarque un scanner multi-stack dédié. Layout typique :

acme-skills/
├── manifest.json                       ← marqueur multi-stack
├── skills/
│   └── form-wizard/SKILL.md
├── agents/
│   └── reviewer.md                     ← frontmatter
├── commands/
│   ├── release-helper.md               ← fichier unique
│   └── fix-pr/SKILL.md                 ← variante skill-style
└── go/
    └── instructions/
        └── error-handling.instructions.md

• skills/<name>/SKILL.md — skills complètes avec leur propre dossier (templates, assets, etc.).
• agents/<name>.md — agents single-file déclarés en frontmatter.
• commands/<name>.md ou commands/<name>/SKILL.md — commandes en single-file ou en mode skill.
• <lang>/instructions/<name>.instructions.md — instructions scopées par langage (façon Copilot).

STH bascule sur le scanner multi-stack dès qu'un manifest.json est présent à la racine du dépôt, ou qu'au moins deux des quatre containers conventionnels ci-dessus sont détectés.

STH peut écrire les ressources installées vers une ou plusieurs cibles. L'auto-détection cherche le fichier marqueur conventionnel de chaque outil — jamais un dossier parent ambigu — donc STH ne propose une cible que quand il a une preuve solide. Le wizard liste les cibles détectées et vous laisse le dernier mot.

Vous pouvez installer des ressources vers plusieurs cibles dans le même projet — STH écrit chaque fichier sous la racine correspondante. Si aucune cible n'est auto-détectée, STH retombe sur Claude par défaut.

Buddy traduit en un coup d'œil l'état de votre projet. Lancée avec --watch, elle réagit en direct aux changements de fichiers.

• 💧  >/< — Tout est à jour
• ⚠️  o.O — Mise à jour disponible
• 😶  ._. — Pas de configuration
• ❌  x x — Erreur
• ⏳  >_< — En cours
• ✅  ^.^ — Terminé

La configuration vit à la racine de votre projet, dans .sth/project.json. Vous pouvez la committer sans risque — elle ne contient aucun secret. Le schema v2 supporte plusieurs providers déclarés dans le tableau providers, chacun avec son propre target_dir.

{
  "schema_version": 2,
  "providers": [
    {
      "id": "team-skills",
      "provider": "github",
      "repository_id": "acme-corp/skills",
      "catalog_ref": "main",
      "catalog_path": "SKILLS.md",
      "target_dir": ".claude/skills"
    },
    {
      "id": "shared-prompts",
      "provider": "gitlab",
      "repository_id": "acme/shared-prompts",
      "catalog_ref": "main",
      "catalog_path": "manifest.json",
      "target_dir": ".github/instructions"
    }
  ],
  "resources": [
    {
      "catalog_id": "skill::react::form-wizard",
      "provider_id": "team-skills",
      "pinned_ref": "v1.4.0"
    },
    {
      "catalog_id": "command::release-helper",
      "provider_id": "shared-prompts"
    }
  ]
}

Le schema v2 supporte plusieurs providers et plusieurs dossiers cibles dans le même projet. Chaque ressource référence son provider source via provider_id, et chaque provider déclare son propre target_dir — vous pouvez tirer vos skills React depuis un repo GitHub privé vers .claude/skills et en parallèle vos prompts partagés depuis un projet GitLab vers .github/instructions.

L'état des installations est stocké dans <target_dir>/sth-state.json (par exemple .claude/skills/sth-state.json). Il liste pour chaque ressource installée : le provider d'origine, les fichiers gérés, leurs hashes SHA-256 et le statut. sth status compare le disque à ce manifeste pour détecter les modifications locales.

STH est en Alpha publique. Pour garder un périmètre clair et observable, on applique quelques règles temporaires :

• Un projet ne peut référencer qu<strong>un seul dépôt Git privé</strong> à la fois (<code>github</code>, <code>gitlab</code>, <code>azure-devops</code> ou <code>bitbucket</code>) — les dépôts publics sont illimités.
• Bypass d'urgence : exporter STH_ALPHA_GATE=0 désactive cette restriction côté CLI (à vos risques — non supporté pour les retours bugs).
• Envie de tester les options payantes pendant l'Alpha ? Lance sth alpha request (un compte est nécessaire — sth login). L'équipe STH examine chaque demande et l'approuve ou la refuse.
• La télémétrie est un choix utilisateur explicite posé à sth init avec trois modes — off, anonymous, connected. Voir la politique de télémétrie pour ce qui est envoyé dans chaque mode et comment changer d'avis plus tard via sth telemetry.

Ces règles sautent à la sortie de bêta. Si une est bloquante pour vous, ouvrez une issue — votre cas peut faire bouger l'agenda.