OpenSkillIndex← back to search
claude-codeautomation

Claude-skill-registry julien-ref-ahk-v1

Best practices AutoHotkey v1. Use when writing AHK v1 scripts to avoid critical errors like auto-execute section issues, includes order, and COM object handling.

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/julien-ref-ahk-v1" ~/.claude/skills/majiayu000-claude-skill-registry-julien-ref-ahk-v1 && rm -rf "$T"
manifest: skills/data/julien-ref-ahk-v1/SKILL.md
tags
#autohotkey#scripting#automation#windows#best-practices#ahk
source content

AutoHotkey v1 - Guide de Référence Optimisé LLM

Guide structuré des bonnes pratiques AutoHotkey v1 pour développeurs et assistants IA

Structure du Guide

Observability

First: At the start of execution, display:

🔧 Skill "julien-ref-ahk-v1" activated

PARTIE I - RÈGLES CRITIQUES : Erreurs fatales à éviter absolument PARTIE II - STANDARDS FONDAMENTAUX : Encodage, nommage, architecture PARTIE III - DÉVELOPPEMENT : Patterns, GUI, performance PARTIE IV - VALIDATION : Tests et déploiement

PARTIE I - RÈGLES CRITIQUES

Erreur #0 : Section Auto-Execute - LA RÈGLE LA PLUS CRITIQUE

QU'EST-CE QUE L'AUTO-EXECUTE?

La section auto-execute est le code qui s'exécute automatiquement au démarrage du script. C'est la source #1 des bugs incompréhensibles en AutoHotkey!

CE QUI TERMINE L'AUTO-EXECUTE

L'auto-execute se termine dès qu'AutoHotkey rencontre:

  1. Un 
    return
    explicite
  2. Un 
    Exit
  3. UNE FONCTION (ligne commençant par 
    NomFonction() {
    )
  4. UN HOTKEY/HOTSTRING (ligne contenant 
    ::
    )
  5. UN LABEL (ligne se terminant par 
    :
    )
  6. La fin physique du fichier

ERREUR FATALE - Code après une fonction

#SingleInstance Force
global myVar := "value"

MyFunction() {  ; CETTE FONCTION TERMINE L'AUTO-EXECUTE!
    MsgBox, Function
}

; CE CODE NE S'EXÉCUTERA JAMAIS AU DÉMARRAGE!
MsgBox, Script started  ; Jamais affiché!
Menu, Tray, Icon, icon.ico  ; Jamais chargé!
return

STRUCTURE CORRECTE

#SingleInstance Force
global myVar := "value"

; Code d'initialisation (s'exécute au démarrage)
MsgBox, Script started
Menu, Tray, Icon, icon.ico

; FIN EXPLICITE de l'auto-execute
return

; Fonctions (après le return)
MyFunction() {
    MsgBox, Function
}

; Hotkeys (après les fonctions)
^a::
    MyFunction()
return

STRUCTURE DE FICHIER OBLIGATOIRE

#Directives (#SingleInstance, #Persistent, etc.)
↓
Variables globales
↓
AUTO-EXECUTE (code qui s'exécute au démarrage)
↓
return  ← FIN EXPLICITE de l'auto-execute
↓
Fonctions
↓
Labels
↓
Hotkeys/Hotstrings
↓
#Include (À LA TOUTE FIN!)

PLACEMENT DES #INCLUDE - RÈGLE ABSOLUE

Les 

#Include
DOIVENT être À LA TOUTE FIN du fichier, après:

  • Toutes les fonctions
  • Tous les labels
  • Tous les hotkeys

POURQUOI? Les modules appellent souvent des fonctions du fichier principal (comme 

Logger_Info
). Si l'include est placé avant la définition de ces fonctions, le script plantera!

Erreur #1 : Includes Manquants ou Incorrects

SOLUTION OBLIGATOIRE

#Include %A_ScriptDir%\VA.ahk      ; Chemin absolu TOUJOURS

RÈGLE ABSOLUE

  • Tous les includes doivent utiliser 
    %A_ScriptDir%\
    pour les chemins absolus

Erreur #2 : Syntaxe Variables dans %var%

SYNTAXE INVALIDE

MsgBox, Device: %devices[1].name%     ; ERREUR FATALE

SOLUTION OBLIGATOIRE

deviceName := devices[1].name         ; Extraire la propriété
MsgBox, Device: %deviceName%          ; Utiliser la variable simple

Erreur #3 : Usage Incorrect de 
global

USAGE CORRECT

MyFunction() {
    global ; En DÉBUT de fonction seulement
    ; OU global var1, var2 pour variables spécifiques
}

MyLabel:
    ; Les variables sont globales par défaut dans les labels
    ; PAS de déclaration global nécessaire
return

Erreur #4 : Gestion Tableaux Vides

.MaxIndex
retourne 
""
(chaîne vide) pour un tableau vide, pas 
0
.

VÉRIFICATION CORRECTE

ArrayCount := Array.MaxIndex
if (ArrayCount = "") {
    ArrayCount := 0         ; Conversion explicite
}
Loop % ArrayCount {
    Element := Array[A_Index]
}

PARTIE II - STANDARDS FONDAMENTAUX

Encodage : UTF-8 avec BOM OBLIGATOIRE

Sans UTF-8 avec BOM, les caractères accentués deviennent illisibles.

SOLUTION UNIQUE

  1. Éditeur : Sauvegarder en UTF-8 AVEC BOM
  2. Lecture : 
    FileRead, var, *t *p65001 %file%
  3. Écriture : 
    FileAppend, content, %file%, UTF-8

Architecture de Projet

PROJET SIMPLE (≤ 200 lignes)

MonScript.ahk                      # Tout en un seul fichier

PROJET MODULAIRE (200-1000 lignes)

Projet/
├── Main.ahk                       # Point d'entrée
├── Config.ahk                     # Variables globales
├── Modules/
│   ├── Module1.ahk               # Fonctionnalités
│   └── Module2.ahk
└── logs/                         # Logs (auto-créé)

Standards de Nommage

; Fichiers et dossiers : PascalCase
MyModule.ahk, Utils/, Core/

; Variables globales : MAJUSCULES
global LOG_ENABLED := true
global EMAIL_ADDRESS := "user@domain.com"

; Fonctions : PascalCase
SendEmailGmail()
GetAudioDevicesList()

; Variables locales : camelCase
local deviceName := "Speakers"
currentTime := A_Now

PARTIE III - DÉVELOPPEMENT

Gestion des Objets COM (Audio/System)

PATTERN OBLIGATOIRE

FunctionWithCOM() {
    ; 1. Créer les objets
    if !(enumerator := VA_GetDeviceEnumerator()) {
        return "Erreur création enumerator"
    }

    VA_IMMDeviceEnumerator_EnumAudioEndpoints(enumerator, 0, 1, devices)

    ; 2. Traitement
    VA_IMMDeviceCollection_GetCount(devices, count)
    Loop, %count% {
        VA_IMMDeviceCollection_Item(devices, A_Index - 1, device)
        ; Traiter device...
        ObjRelease(device)    ; LIBÉRER CHAQUE OBJET
    }

    ; 3. Nettoyage OBLIGATOIRE
    ObjRelease(devices)
    ObjRelease(enumerator)
}

Chaque objet COM créé DOIT être libéré avec 

ObjRelease()
.

Interface Graphique

SOLUTIONS SIMPLES ET ROBUSTES

Edit Control avec Scroll Natif

Gui, Add, Edit, x10 y10 w500 h300 ReadOnly VScroll HScroll vContentArea
GuiControl,, ContentArea, %LongText%  ; Scroll automatique

RÈGLES GUI ESSENTIELLES

  • Simplicité : Privilégier les contrôles natifs (Edit, ListBox)
  • Séparation : GUI distinctes pour différentes fonctions
  • Scroll natif : Laisser AutoHotkey gérer le scroll
  • Boutons fixes : Placer les boutons hors des zones scrollables

PARTIE IV - VALIDATION

Checklist Pré-Déploiement

VALIDATION TECHNIQUE OBLIGATOIRE

  • Encodage : UTF-8 avec BOM sur tous les fichiers .ahk
  • Includes : Tous les chemins utilisent 
    %A_ScriptDir%\
  • Tableaux : Vérification 
    MaxIndex = ""
    pour tableaux vides
  • COM : Tous les objets libérés avec 
    ObjRelease()
  • Global : Utilisé uniquement en début de fonctions
  • Variables : Pas d'accès propriétés dans 
    %var%

Règles d'Or à Retenir

  1. UTF-8 avec BOM : Obligatoire pour les accents
  2. Includes absolus : Toujours avec 
    %A_ScriptDir%\
  3. Variables simples : Dans 
    %var%
    , pas de propriétés d'objets
  4. Global correct : Fonctions seulement, jamais dans labels
  5. Tableaux vides : Vérifier 
    MaxIndex = ""
  6. COM cleanup : 
    ObjRelease()
    obligatoire
  7. Log unique : Un seul fichier actif par session
  8. Hotkeys à la fin : Convention et bonne pratique
  9. Auto-execute : Toujours terminer par 
    return
    explicite
  10. Includes en dernier : À la fin du fichier principal