yanis/antigravity-awesome-skills
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: translate remaining Italian phrases to English

Browse Source
This commit is contained in:
sickn33
2026-03-31 18:21:35 +02:00
parent 2bb0d56316
commit 478c2a5b28
3 changed files with 77 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
docs/integrations/jetski-cortex.md
View File

@@ -1,54 +1,54 @@
--- ---
title: Jetski/Cortex + Gemini Integration Guide title: Jetski/Cortex + Gemini Integration Guide
description: "Come usare antigravity-awesome-skills con Jetski/Cortex evitando l’overflow di contesto con 1.340+ skill." description: "Use antigravity-awesome-skills with Jetski/Cortex without hitting context-window overflow with 1.340+ skills."
--- ---
# Jetski/Cortex + Gemini: integrazione sicura con 1.340+ skill # Jetski/Cortex + Gemini: safe integration with 1,340+ skills
Questa guida mostra come integrare il repository `antigravity-awesome-skills` con un agente basato su **Jetski/Cortex + Gemini** (o framework simili) **senza superare il context window** del modello. This guide shows how to integrate the `antigravity-awesome-skills` repository with an agent based on **Jetski/Cortex + Gemini** (or similar frameworks) **without exceeding the model context window**.
L’errore tipico visto in Jetski/Cortex è: The common error seen in Jetski/Cortex is:
> `TrajectoryChatConverter: could not convert a single message before hitting truncation` > `TrajectoryChatConverter: could not convert a single message before hitting truncation`
Il problema non è nelle skill, ma **nel modo in cui vengono caricate**. The issue is not with the skills themselves, but **with how they are loaded**.
--- ---
## 1. Antipattern da evitare ## 1. Anti-pattern to avoid
Non bisogna mai: Never do:
- leggere **tutte** le directory `skills/*/SKILL.md` all’avvio; - read **all** `skills/*/SKILL.md` directories at startup;
- concatenare il contenuto di tutte le `SKILL.md` in un singolo system prompt; - concatenate all `SKILL.md` content into a single system prompt;
- reiniettare l’intera libreria per **ogni** richiesta. - re-inject the entire library for **every** request.
Con oltre 1.340 skill, questo approccio riempie il context window prima ancora di aggiungere i messaggi dell’utente, causando l’errore di truncation. With over 1,340 skills, this approach fills the context window before user messages are even added, causing truncation.
--- ---
## 2. Pattern raccomandato ## 2. Recommended pattern
Principi chiave: Core principles:
- **Manifest leggero**: usare `data/skills_index.json` per sapere *quali* skill esistono, senza caricare i testi completi. - **Light manifest**: use `data/skills_index.json` to know *which* skills exist without loading full text.
- **Lazy loading**: leggere `SKILL.md` **solo** per le skill effettivamente invocate in una conversazione (es. quando compare `@skill-id`). - **Lazy loading**: read `SKILL.md` **only** for skills actually invoked in a conversation (for example, when `@skill-id` appears).
- **Limiti espliciti**: imporre un massimo di skill/tokens caricati per turno, con fallback chiari. - **Explicit limits**: enforce a maximum number of skills/tokens loaded per turn, with clear fallbacks.
- **Path safety**: verificare che i path del manifest restino dentro `SKILLS_ROOT` prima di leggere `SKILL.md`. - **Path safety**: verify manifest paths remain inside `SKILLS_ROOT` before reading `SKILL.md`.
Il flusso consigliato è: The recommended flow is:
1. **Bootstrap**: all’avvio dell’agente leggere `data/skills_index.json` e costruire una mappa `id -> meta`. 1. **Bootstrap**: on agent startup, read `data/skills_index.json` and build an `id -> meta` map.
2. **Parsing dei messaggi**: prima di chiamare il modello, estrarre tutti i riferimenti `@skill-id` dai messaggi utente/sistema. 2. **Message parsing**: before calling the model, extract all `@skill-id` references from user/system messages.
3. **Risoluzione**: mappare gli id trovati in oggetti `SkillMeta` usando la mappa di bootstrap. 3. **Resolution**: map the found IDs into `SkillMeta` objects using the bootstrap map.
4. **Lazy load**: leggere i file `SKILL.md` solo per questi id (fino a un massimo configurabile). 4. **Lazy load**: read `SKILL.md` files only for these IDs (up to a configurable maximum).
5. **Prompt building**: costruire i system messages del modello includendo solo le definizioni delle skill selezionate. 5. **Prompt building**: build model system messages including only the selected skill definitions.
--- ---
## 3. Struttura di `skills_index.json` ## 3. Structure of `skills_index.json`
Il file `data/skills_index.json` è un array di oggetti, ad esempio: The file `data/skills_index.json` is an array of objects, for example:
```json ```json
{ {
@@ -63,24 +63,24 @@ Il file `data/skills_index.json` è un array di oggetti, ad esempio:
} }
``` ```
Campi chiave: Key fields:
- **`id`**: identificatore usato nelle menzioni `@id` (es. `@brainstorming`). - **`id`**: identifier used in `@id` mentions (for example, `@brainstorming`).
- **`path`**: directory che contiene la `SKILL.md` (es. `skills/brainstorming/`). - **`path`**: directory containing `SKILL.md` (for example, `skills/brainstorming/`).
Per ottenere il percorso alla definizione della skill: To resolve the path to a skill definition:
- `fullPath = path.join(SKILLS_ROOT, meta.path, "SKILL.md")`. - `fullPath = path.join(SKILLS_ROOT, meta.path, "SKILL.md")`.
> Nota: `SKILLS_ROOT` è la directory radice dove avete installato il repository (es. `~/.agent/skills`). > Note: `SKILLS_ROOT` is the root directory where you installed the repository (for example, `~/.agent/skills`).
--- ---
## 4. Pseudo‑codice di integrazione (TypeScript) ## 4. Integration pseudocode (TypeScript)
> Esempio completo in: [`docs/integrations/jetski-gemini-loader/`](../../docs/integrations/jetski-gemini-loader/). > Full example in: [`docs/integrations/jetski-gemini-loader/`](../../docs/integrations/jetski-gemini-loader/).
### 4.1. Tipi di base ### 4.1. Core Types
```ts ```ts
type SkillMeta = { type SkillMeta = {
@@ -93,7 +93,7 @@ type SkillMeta = {
}; };
``` ```
### 4.2. Bootstrap: caricare il manifest ### 4.2. Bootstrap: load the manifest
```ts ```ts
function loadSkillIndex(indexPath: string): Map<string, SkillMeta> { function loadSkillIndex(indexPath: string): Map<string, SkillMeta> {
@@ -107,7 +107,7 @@ function loadSkillIndex(indexPath: string): Map<string, SkillMeta> {
} }
``` ```
### 4.3. Parsing dei messaggi per trovare `@skill-id` ### 4.3. Parse messages to find `@skill-id`
```ts ```ts
const SKILL_ID_REGEX = /@([a-zA-Z0-9-_./]+)/g; const SKILL_ID_REGEX = /@([a-zA-Z0-9-_./]+)/g;
@@ -140,7 +140,7 @@ function resolveSkillsFromMessages(
} }
``` ```
### 4.4. Lazy loading dei file `SKILL.md` ### 4.4. Lazy loading `SKILL.md` files
```ts ```ts
async function loadSkillBodies( async function loadSkillBodies(
@@ -159,9 +159,9 @@ async function loadSkillBodies(
} }
``` ```
### 4.5. Costruzione del prompt Jetski/Cortex ### 4.5. Build the Jetski/Cortex prompt
Pseudocodice per la fase di pre‑processing, prima del `TrajectoryChatConverter`: Pseudocode for the pre-processing phase before `TrajectoryChatConverter`:
```ts ```ts
async function buildModelMessages( async function buildModelMessages(
@@ -203,70 +203,70 @@ async function buildModelMessages(
} }
``` ```
> Suggerimento: aggiungete una stima dei token per troncare o riassumere i `SKILL.md` se il context window si avvicina al limite. > Tip: Add token estimation to trim or summarize `SKILL.md` files when the context window approaches its limit.
> Il reference loader di questo repo supporta anche un fallback esplicito: `overflowBehavior: "error"`. > This repository's reference loader also supports an explicit fallback: `overflowBehavior: "error"`.
--- ---
## 5. Gestione degli overflow di contesto ## 5. Context overflow handling
Per evitare errori difficili da capire per l’utente, impostate: To avoid unclear errors for the user, set:
- una **soglia di sicurezza** (es. 70–80% del context window); - a **safety threshold** (for example, 70–80% of the context window);
- un **limite massimo di skill per turno** (es. 5–10). - a **maximum number of skills per turn** (for example, 5–10).
Strategie quando si supera la soglia: Strategies when the threshold is exceeded:
- ridurre il numero di skill incluse (es. in base a recenza o priorità); oppure - reduce the number of included skills (for example, by recency or priority); or
- restituire un errore chiaro all’utente, ad esempio: - return a clear error to the user, for example:
> "Sono state richieste troppe skill in un singolo turno. Riduci il numero di `@skill-id` nel messaggio o dividili in più passaggi." > "Too many skills were requested in a single turn. Reduce the number of `@skill-id` references in your message or split them into multiple turns."
--- ---
## 6. Scenari di test raccomandati ## 6. Recommended test scenarios
- **Scenario 1 – Messaggio semplice ("hi")** - **Scenario 1 – Simple message ("hi")**
- Nessun `@skill-id` → nessuna `SKILL.md` caricata → il prompt rimane piccolo → nessun errore. - No `@skill-id` → no `SKILL.md` loaded → prompt remains small → no error.
- **Scenario 2 – Poche skill** - **Scenario 2 – Few skills**
- Messaggio con 1–2 `@skill-id` → solo le relative `SKILL.md` vengono caricate → nessun overflow. - Message with 1–2 `@skill-id` references → only related `SKILL.md` files are loaded → no overflow.
- **Scenario 3 – Molte skill** - **Scenario 3 – Many skills**
- Messaggio con molte `@skill-id` → si attiva il limite `maxSkillsPerTurn` o il controllo di token → nessun overflow silenzioso. - Message with many `@skill-id` references → `maxSkillsPerTurn` or token guardrails trigger → no silent overflow.
--- ---
## 7. Sottoinsiemi di skill e bundle ## 7. Skill subsets and bundles
Per ulteriore controllo: For additional control:
- spostate le skill non necessarie in `skills/.disabled/` per escluderle in certi ambienti; - move unnecessary skills into `skills/.disabled/` to exclude them in certain environments;
- usate i **bundle** descritti in [`docs/users/bundles.md`](../users/bundles.md) per caricare solo gruppi tematici. - use the **bundles** described in [`docs/users/bundles.md`](../users/bundles.md) to load only focused groups.
## 8. Recovery su Windows se siete gia in crash loop ## 8. Windows crash-loop recovery
Se l’host continua a riaprire la stessa trajectory corrotta dopo un errore di truncation: If the host keeps reopening the same corrupted trajectory after a truncation error:
- rimuovete la skill o il pacchetto problematico; - remove the problematic skill or package;
- cancellate Local Storage / Session Storage / IndexedDB usati da Antigravity; - clear Antigravity Local Storage / Session Storage / IndexedDB;
- svuotate `%TEMP%`; - clear `%TEMP%`;
- riavviate con un loader lazy e limiti espliciti. - restart with lazy loading and explicit limits.
Guida completa: Complete guide:
- [`docs/users/windows-truncation-recovery.md`](../users/windows-truncation-recovery.md) - [`docs/users/windows-truncation-recovery.md`](../users/windows-truncation-recovery.md)
Per evitare che il problema si ripresenti: To prevent recurrence:
- mantenete `overflowBehavior: "error"` quando preferite un fallimento esplicito; - keep `overflowBehavior: "error"` when you prefer explicit failure;
- continuate a validare che i path risolti restino dentro `skillsRoot`. - continue validating that resolved paths remain inside `skillsRoot`.
--- ---
## 9. Riepilogo ## 9. Summary
- Non concatenate mai tutte le `SKILL.md` in un singolo prompt. - Do not concatenate all `SKILL.md` files into a single prompt.
- Usate `data/skills_index.json` come manifest leggero. - Use `data/skills_index.json` as a lightweight manifest.
- Caricate le skill **on‑demand** in base a `@skill-id`. - Load skills **on demand** based on `@skill-id`.
- Impostate limiti chiari (max skill per turno, soglia di token). - Set clear limits (max skills per turn, token threshold).
Seguendo questo pattern, Jetski/Cortex + Gemini può usare l’intera libreria di `antigravity-awesome-skills` in modo sicuro, scalabile e compatibile con il context window dei modelli moderni. Following this pattern, Jetski/Cortex + Gemini can use the full `antigravity-awesome-skills` library safely, at scale, and within modern model context-window limits.

2
tools/scripts/tests/test_audit_consistency.py
View File

@@ -98,7 +98,7 @@ If you want a faster answer than "browse all {count_label} skills", start with a
encoding="utf-8", encoding="utf-8",
) )
(root / "docs" / "integrations" / "jetski-cortex.md").write_text( (root / "docs" / "integrations" / "jetski-cortex.md").write_text(
"1.304+ skill\nCon oltre 1.304 skill, questo approccio\n", "1.304+ skill\nOver 1.304 skills, this approach\n",
encoding="utf-8", encoding="utf-8",
) )
(root / "docs" / "integrations" / "jetski-gemini-loader" / "README.md").write_text( (root / "docs" / "integrations" / "jetski-gemini-loader" / "README.md").write_text(

2
tools/scripts/tests/test_sync_repo_metadata.py
View File

@@ -93,7 +93,7 @@ If you want a faster answer than "browse all 1,273+ skills", start with a tool-s
encoding="utf-8", encoding="utf-8",
) )
(root / "docs" / "integrations" / "jetski-cortex.md").write_text( (root / "docs" / "integrations" / "jetski-cortex.md").write_text(
"1.200+ skill\nCon oltre 1.200 skill, questo approccio\n", "1.200+ skill\nOver 1.200 skills, this approach\n",
encoding="utf-8", encoding="utf-8",
) )
(root / "docs" / "integrations" / "jetski-gemini-loader" / "README.md").write_text( (root / "docs" / "integrations" / "jetski-gemini-loader" / "README.md").write_text(