Skill

Une skill orchestre des étapes. Elle peut appeler des function, des tool, d’autres skill, des strategy typées, des interactions utilisateur et des validations humaines supportées.

Une skill n’est pas un agent autonome. Elle décrit une composition bornée et réutilisable.

Skill exécutable et procédure contextuelle

Touba distingue deux notions proches par le nom, mais différentes par leur rôle.

Notion	Rôle
skill	capacité exécutable typée dans le programme Touba
procédure contextuelle	contexte déclaré dans un package avec touba.package.json

Un package peut contenir un SKILL.md, des références, des exemples, des modèles de document ou des scripts. Son contexte guide le modèle ; une skill exécutable suit le programme. Les deux se partagent dans le même format de package.

Une skill Touba a une signature, des uses et un bloc do. Elle peut être appelée seulement depuis une capacité autorisée par le programme, et ses effets passent par les tool et le manifest.

Forme

source.tb

skill Name
    takes input as InputType
    gives OutputType
    uses SomeStep
    do
        SomeStep
            with input as input
            into result
        give result

Les appels enrichis utilisent with pour passer les arguments et into pour nommer le résultat.

Cas simple

skill_simple.tb

module examples.skill_simple

type ReviewSignal
    risk is Float

function ClassifyRisk
    takes signal as ReviewSignal
    gives Text
    do
        if signal.risk >= 0.7
            give "review"
        else
            give "accept"

skill PrepareReview
    takes signal as ReviewSignal
    gives Text
    uses ClassifyRisk
    do
        ClassifyRisk
            with signal as signal
            into label

        give label

La skill ne refait pas le calcul. Elle orchestre l’appel et donne un point de composition réutilisable.

Cas avancé

skill_advanced.tb

module examples.skill_advanced

type ChangeRequest
    summary is Text

type AppliedChange
    summary is Text

tool ApplyChange
    takes request as ChangeRequest
    gives AppliedChange
    requires filesystem_write

skill ReviewAndApply
    takes request as ChangeRequest
    gives AppliedChange
    uses ApplyChange
    do
        human.approve
            with context as request
            into approved

        ApplyChange
            with request as request
            into applied

        show
            with message as "Change applied"

        give applied

Ce cas montre une orchestration plus riche :

• une validation humaine obligatoire ;
• un appel à un tool effectif ;
• une sortie utilisateur avec show ;
• un résultat final explicite.

Composition structurée

Une skill peut composer if / else if / else, for, while et des appels à des stratégies typées locales ou importées. Une cible est déclarée dans uses, ses paramètres passent par with et sa sortie par into. Elle peut distribuer une liste avec parallel, en déclarant les plafonds max_concurrency et max_items, puis attendre les résultats ordonnés.

Les portées restent isolées par appel et par branche ; budgets et annulation restent communs au run. Les validations humaines conservent les continuations imbriquées à la reprise. Une skill ne devient pas pour autant un caller callable_by autorisé d'agent : utilisez une stratégie ou un agent déclaré pour cette frontière. Voir Strategy et Validation humaine.

Ce que la skill absorbe

Dans une application classique, la séquence peut être dispersée entre un service, un contrôleur, un script de workflow et des callbacks.

Avec skill, l’enchaînement devient une structure visible dans le source Touba. La skill ne décide pas qui peut l’utiliser comme un agent ; elle décrit seulement comment composer les étapes.

Responsabilités

La séparation est volontaire :

• la skill porte une capacité exécutable typée ;
• l’agent porte la responsabilité et l’autorité d’invocation ;
• le manifest accorde les handlers, grants, secrets et limites ;
• le runtime vérifie le contrat avant effet externe ;
• le skill pack porte le contexte documentaire, les ressources et les scripts préparatoires.

Cette séparation permet de garder des skills réutilisables sans confondre capacité, autorité et contexte.