swe-re-expert

Jetski/Cortex + Gemini: safe integration with 2,715+ skills

Custom-host integration: This guide documents a low-level, direct-manifest lazy loader for Jetski/Cortex and similar hosts. For Codex or Claude Code, the recommended path is AAS Core, which provides neutral, deterministic catalog retrieval and validates exact agent-selected IDs through a bounded, read-only MCP server.

This guide shows how to integrate the agentic-awesome-skills repository with an agent based on Jetski/Cortex + Gemini (or similar frameworks) without exceeding the model context window.

The common error seen in Jetski/Cortex is:

TrajectoryChatConverter: could not convert a single message before hitting truncation

The issue is not with the skills themselves, but with how they are loaded.

1. Anti-pattern to avoid

Never do:

With 2,715+ skills, this approach fills the context window before user messages are even added, causing truncation.

Core principles:

The recommended flow is:

  1. Bootstrap: on agent startup, read skills_index.json (and data/skills_index.json if your host expects compatibility reads) and build an id -> meta map.
  2. Message parsing: before calling the model, extract all @skill-id references from user/system messages.
  3. Resolution: map the found IDs into SkillMeta objects using the bootstrap map.
  4. Lazy load: read SKILL.md files only for these IDs (up to a configurable maximum).
  5. Prompt building: build model system messages including only the selected skill definitions.

3. Structure of skills_index.json

The file skills_index.json is an array of objects, for example:

data/skills_index.json is the compatibility mirror and should stay in sync with the canonical root manifest.

{
  "id": "brainstorming",
  "path": "skills/brainstorming",
  "category": "planning",
  "name": "brainstorming",
  "description": "Use before any creative or constructive work.",
  "risk": "safe",
  "source": "official",
  "date_added": "2026-02-27"
}

Key fields:

To resolve the path to a skill definition:

Note: SKILLS_ROOT is the root directory where you installed the repository (for example, ~/.agent/skills).

4. Integration pseudocode (TypeScript)

The parser should validate against:

Full example in: docs/integrations/jetski-gemini-loader/.

4.1. Core Types

type SkillMeta = {
  id: string;
  path: string;
  name: string;
  description?: string;
  category?: string;
  risk?: string;
};

4.2. Bootstrap: load the manifest

function loadSkillIndex(indexPath: string): Map<string, SkillMeta> {
  const raw = fs.readFileSync(indexPath, "utf8");
  const arr = JSON.parse(raw) as SkillMeta[];
  const map = new Map<string, SkillMeta>();
  for (const meta of arr) {
    map.set(meta.id, meta);
  }
  return map;
}

4.3. Parse messages to find @skill-id

const SKILL_ID_REGEX = /@([a-zA-Z0-9-_./]+)/g;

function resolveSkillsFromMessages(
  messages: { role: string; content: string }[],
  index: Map<string, SkillMeta>,
  maxSkills: number
): SkillMeta[] {
  const found = new Set<string>();

  for (const msg of messages) {
    let match: RegExpExecArray | null;
    while ((match = SKILL_ID_REGEX.exec(msg.content)) !== null) {
      const id = match[1];
      if (index.has(id)) {
        found.add(id);
      }
    }
  }

  const metas: SkillMeta[] = [];
  for (const id of found) {
    const meta = index.get(id);
    if (meta) metas.push(meta);
    if (metas.length >= maxSkills) break;
  }

  return metas;
}

4.4. Lazy loading SKILL.md files

async function loadSkillBodies(
  skillsRoot: string,
  metas: SkillMeta[]
): Promise<string[]> {
  const bodies: string[] = [];

  for (const meta of metas) {
    const fullPath = path.join(skillsRoot, meta.path, "SKILL.md");
    const text = await fs.promises.readFile(fullPath, "utf8");
    bodies.push(text);
  }

  return bodies;
}

4.5. Build the Jetski/Cortex prompt

Pseudocode for the pre-processing phase before TrajectoryChatConverter:

async function buildModelMessages(
  baseSystemMessages: { role: "system"; content: string }[],
  trajectory: { role: "user" | "assistant" | "system"; content: string }[],
  skillIndex: Map<string, SkillMeta>,
  skillsRoot: string,
  maxSkillsPerTurn: number,
  overflowBehavior: "truncate" | "error" = "truncate"
): Promise<{ role: string; content: string }[]> {
  const referencedSkills = resolveSkillsFromMessages(
    trajectory,
    skillIndex,
    Number.MAX_SAFE_INTEGER
  );
  if (
    overflowBehavior === "error" &&
    referencedSkills.length > maxSkillsPerTurn
  ) {
    throw new Error(
      `Too many skills requested in a single turn. Reduce @skill-id usage to ${maxSkillsPerTurn} or fewer.`
    );
  }

  const selectedMetas = resolveSkillsFromMessages(
    trajectory,
    skillIndex,
    maxSkillsPerTurn
  );

  const skillBodies = await loadSkillBodies(skillsRoot, selectedMetas);

  const skillMessages = skillBodies.map((body) => ({
    role: "system" as const,
    content: body,
  }));

  return [...baseSystemMessages, ...skillMessages, ...trajectory];
}

Tip: Add token estimation to trim or summarize SKILL.md files when the context window approaches its limit. This repository’s reference loader also supports an explicit fallback: overflowBehavior: "error".

5. Context overflow handling

To avoid unclear errors for the user, set:

Strategies when the threshold is exceeded:

“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.”

7. Skill subsets and bundles

For additional control:

8. Windows crash-loop recovery

If the host keeps reopening the same corrupted trajectory after a truncation error:

Complete guide:

To prevent recurrence:

9. Summary

Following this pattern, Jetski/Cortex + Gemini can use the full agentic-awesome-skills library safely, at scale, and within modern model context-window limits.

This site is open source. Improve this page.