npm - opencode-skills-collection - Versions diffs - 4.0.52 → 4.0.54 - Mend

opencode-skills-collection 4.0.52 → 4.0.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1176) hide show

package/bundled-skills/docs/integrations/jetski-cortex.md DELETED Viewed

@@ -1,282 +0,0 @@
----
-title: Jetski/Cortex + Gemini Integration Guide
-description: "Use agentic-awesome-skills with Jetski/Cortex without hitting context-window overflow with 2,108+ skills."
----
-# Jetski/Cortex + Gemini: safe integration with 2,108+ 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](../users/aas-core.md), 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:
-- read **all** `skills/*/SKILL.md` directories at startup;
-- concatenate all `SKILL.md` content into a single system prompt;
-- re-inject the entire library for **every** request.
-With 2,108+ skills, this approach fills the context window before user messages are even added, causing truncation.
----
-## 2. Recommended pattern
-Core principles:
-- **Stable manifest**: use the canonical root `skills_index.json` to know *which* skills exist without loading full text.
-- **Compatibility mirror**: treat `data/skills_index.json` as an exact mirror of the canonical manifest.
-- **Lazy loading**: read `SKILL.md` **only** for skills actually invoked in a conversation (for example, when `@skill-id` appears).
-- **Explicit limits**: enforce a maximum number of skills/tokens loaded per turn, with clear fallbacks.
-- **Path safety**: verify manifest paths remain inside `SKILLS_ROOT` before reading `SKILL.md`.
-- **Schema contract**: validate manifest entries against [`schemas/skills-index.v1.schema.json`](../../schemas/skills-index.v1.schema.json).
-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.
-```json
-{
-  "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:
-- **`id`**: identifier used in `@id` mentions (for example, `@brainstorming`).
-- **`path`**: directory containing `SKILL.md` (for example, `skills/brainstorming/`).
-To resolve the path to a skill definition:
-- `fullPath = path.join(SKILLS_ROOT, meta.path, "SKILL.md")`.
-> 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:
-- [`schemas/skills-index.v1.schema.json`](../../schemas/skills-index.v1.schema.json)
-> Full example in: [`docs/integrations/jetski-gemini-loader/`](../../docs/integrations/jetski-gemini-loader/).
-### 4.1. Core Types
-```ts
-type SkillMeta = {
-  id: string;
-  path: string;
-  name: string;
-  description?: string;
-  category?: string;
-  risk?: string;
-};
-```
-### 4.2. Bootstrap: load the manifest
-```ts
-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`
-```ts
-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
-```ts
-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`:
-```ts
-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:
-- a **safety threshold** (for example, 70–80% of the context window);
-- a **maximum number of skills per turn** (for example, 5–10).
-Strategies when the threshold is exceeded:
-- reduce the number of included skills (for example, by recency or priority); or
-- return a clear error to the user, for example:
-> "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. Recommended test scenarios
-- **Scenario 1 – Simple message ("hi")**
-  - No `@skill-id` → no `SKILL.md` loaded → prompt remains small → no error.
-- **Scenario 2 – Few skills**
-  - Message with 1–2 `@skill-id` references → only related `SKILL.md` files are loaded → no overflow.
-- **Scenario 3 – Many skills**
-  - Message with many `@skill-id` references → `maxSkillsPerTurn` or token guardrails trigger → no silent overflow.
----
-## 7. Skill subsets and bundles
-For additional control:
-- move unnecessary skills into `skills/.disabled/` to exclude them in certain environments;
-- use the **bundles** described in [`docs/users/bundles.md`](../users/bundles.md) to load only focused groups.
-## 8. Windows crash-loop recovery
-If the host keeps reopening the same corrupted trajectory after a truncation error:
-- remove the problematic skill or package;
-- clear Antigravity Local Storage / Session Storage / IndexedDB;
-- clear `%TEMP%`;
-- restart with lazy loading and explicit limits.
-Complete guide:
-- [`docs/users/windows-truncation-recovery.md`](../users/windows-truncation-recovery.md)
-To prevent recurrence:
-- keep `overflowBehavior: "error"` when you prefer explicit failure;
-- continue validating that resolved paths remain inside `skillsRoot`.
----
-## 9. Summary
-- Do not concatenate all `SKILL.md` files into a single prompt.
-- Use `skills_index.json` as the canonical lightweight manifest.
-- Load skills **on demand** based on `@skill-id`.
-- Set clear limits (max skills per turn, token threshold).
-Following this pattern, Jetski/Cortex + Gemini can use the full `agentic-awesome-skills` library safely, at scale, and within modern model context-window limits.

package/bundled-skills/docs/integrations/jetski-gemini-loader/README.md DELETED Viewed

@@ -1,103 +0,0 @@
-# Jetski + Gemini Lazy Skill Loader (Example)
-> **Custom-host example:** This is a low-level, direct-manifest integration for Jetski/Cortex-style hosts. Codex and Claude Code users should start with [AAS Core](../../users/aas-core.md), which exposes neutral, deterministic catalog retrieval and validates exact agent-selected IDs through a bounded, read-only MCP server.
-This example shows one way to integrate **agentic-awesome-skills** with a Jetski/Cortex‑style agent using **lazy loading** based on `@skill-id` mentions, instead of concatenating every `SKILL.md` into the prompt.
-> This is **not** a production‑ready library – it is a minimal reference you can adapt to your own host/agent implementation.
----
-## What this example demonstrates
-- How to:
-  - load the canonical manifest `skills_index.json` once at startup;
-  - optionally support `data/skills_index.json` for compatibility-only hosts.
-  - scan conversation messages for `@skill-id` patterns;
-  - resolve those ids to entries in the manifest;
-  - read only the corresponding `SKILL.md` files from disk (lazy loading);
-  - build a prompt array with:
-    - your base system messages;
-    - one system message per selected skill;
-    - the rest of the trajectory.
-- How to enforce a **maximum number of skills per turn** via `maxSkillsPerTurn`.
-- How to choose whether to **truncate or error** when too many skills are requested via `overflowBehavior`.
-This pattern avoids context overflow when you have 2,108+ skills installed.
-Manifest contract references:
-- [`../../../schemas/skills-index.v1.schema.json`](../../../schemas/skills-index.v1.schema.json)
-- [`../../users/discovery-manifest.md`](../../users/discovery-manifest.md)
----
-## Files
-- `loader.mjs`
-  - Implements:
-    - `loadSkillIndex(indexPath)`;
-    - `resolveSkillsFromMessages(messages, index, maxSkills)`;
-    - `loadSkillBodies(skillsRoot, metas)`;
-    - `buildModelMessages({...})`.
-- See also the integration guide:
-  - [`docs/integrations/jetski-cortex.md`](../jetski-cortex.md)
----
-## Basic usage (pseudo‑code)
-```ts
-import path from "path";
-import {
-  loadSkillIndex,
-  buildModelMessages,
-  Message,
-} from "./loader.mjs";
-const REPO_ROOT = "/path/to/agentic-awesome-skills";
-const SKILLS_ROOT = REPO_ROOT;
-const INDEX_PATH = path.join(REPO_ROOT, "skills_index.json");
-// 1. Bootstrap once at agent startup (optionally validate `data/skills_index.json` for compatibility hosts).
-const skillIndex = loadSkillIndex(INDEX_PATH);
-// 2. Before calling the model, build messages with lazy‑loaded skills
-async function runTurn(trajectory: Message[]) {
-  const baseSystemMessages: Message[] = [
-    {
-      role: "system",
-      content: "You are a helpful coding agent.",
-    },
-  ];
-  const modelMessages = await buildModelMessages({
-    baseSystemMessages,
-    trajectory,
-    skillIndex,
-    skillsRoot: SKILLS_ROOT,
-    maxSkillsPerTurn: 8,
-    overflowBehavior: "error",
-  });
-  // 3. Pass `modelMessages` to your Jetski/Cortex + Gemini client
-  // e.g. trajectoryChatConverter.convert(modelMessages)
-}
-```
-Adapt the paths and model call to your environment.
----
-## Important notes
-- **Do not** iterate through `skills/*/SKILL.md` and load everything at once.
-- This example:
-  - assumes skills live under the same repo root as `skills_index.json`;
-  - keeps `data/skills_index.json` for compatibility readers only;
-  - uses a plain Node.js ESM module so it can be imported directly without a TypeScript runtime.
-- In a real host:
-  - wire `buildModelMessages` into the point where you currently assemble the prompt before `TrajectoryChatConverter`;
-  - consider `overflowBehavior: "error"` if you want a clear user-facing failure instead of silently dropping extra skills;
-  - keep path validation so manifest entries cannot escape your configured skills root;
-  - add token‑counting / truncation logic if you want a stricter safety budget.

package/bundled-skills/docs/integrations/jetski-gemini-loader/loader.mjs DELETED Viewed

@@ -1,154 +0,0 @@
-import fs from "fs";
-import path from "path";
-/**
- * @typedef {{
- *   id: string,
- *   path: string,
- *   name: string,
- *   description?: string,
- *   category?: string,
- *   risk?: string,
- * }} SkillMeta
- */
-/**
- * @typedef {{
- *   role: "system" | "user" | "assistant",
- *   content: string,
- * }} Message
- */
-const SKILL_ID_REGEX = /@([a-zA-Z0-9-_./]+)/g;
-function collectReferencedSkillIds(messages, index) {
-  const referencedSkillIds = new Set();
-  for (const msg of messages) {
-    for (const match of msg.content.matchAll(SKILL_ID_REGEX)) {
-      const id = match[1];
-      if (index.has(id)) {
-        referencedSkillIds.add(id);
-      }
-    }
-  }
-  return [...referencedSkillIds];
-}
-function assertValidMaxSkills(maxSkills) {
-  if (!Number.isInteger(maxSkills) || maxSkills < 1) {
-    throw new Error("maxSkills must be a positive integer.");
-  }
-  return maxSkills;
-}
-export function loadSkillIndex(indexPath) {
-  const raw = fs.readFileSync(indexPath, "utf8");
-  const arr = JSON.parse(raw);
-  const map = new Map();
-  for (const meta of arr) {
-    map.set(meta.id, meta);
-  }
-  return map;
-}
-export function resolveSkillsFromMessages(messages, index, maxSkills) {
-  const skillLimit = assertValidMaxSkills(maxSkills);
-  const referencedSkillIds = collectReferencedSkillIds(messages, index);
-  const metas = [];
-  for (const id of referencedSkillIds) {
-    const meta = index.get(id);
-    if (meta) {
-      metas.push(meta);
-    }
-    if (metas.length >= skillLimit) {
-      break;
-    }
-  }
-  return metas;
-}
-export async function loadSkillBodies(skillsRoot, metas) {
-  const bodies = [];
-  const rootPath = path.resolve(skillsRoot);
-  const rootRealPath = await fs.promises.realpath(rootPath);
-  for (const meta of metas) {
-    const skillDirPath = path.resolve(rootPath, meta.path);
-    const relativePath = path.relative(rootPath, skillDirPath);
-    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
-      throw new Error(`Skill path escapes skills root: ${meta.id}`);
-    }
-    const skillDirStat = await fs.promises.lstat(skillDirPath);
-    if (!skillDirStat.isDirectory() || skillDirStat.isSymbolicLink()) {
-      throw new Error(
-        `Skill directory must be a regular directory inside the skills root: ${meta.id}`,
-      );
-    }
-    const fullPath = path.join(skillDirPath, "SKILL.md");
-    const skillFileStat = await fs.promises.lstat(fullPath);
-    if (!skillFileStat.isFile() || skillFileStat.isSymbolicLink()) {
-      throw new Error(
-        `SKILL.md must be a regular file inside the skills root: ${meta.id}`,
-      );
-    }
-    const realPath = await fs.promises.realpath(fullPath);
-    const realRelativePath = path.relative(rootRealPath, realPath);
-    if (realRelativePath.startsWith("..") || path.isAbsolute(realRelativePath)) {
-      throw new Error(`SKILL.md resolves outside the skills root: ${meta.id}`);
-    }
-    const text = await fs.promises.readFile(realPath, "utf8");
-    bodies.push(text);
-  }
-  return bodies;
-}
-export async function buildModelMessages(options) {
-  const {
-    baseSystemMessages,
-    trajectory,
-    skillIndex,
-    skillsRoot,
-    maxSkillsPerTurn = 8,
-    overflowBehavior = "truncate",
-  } = options;
-  const skillLimit = assertValidMaxSkills(maxSkillsPerTurn);
-  const referencedSkillIds = collectReferencedSkillIds(trajectory, skillIndex);
-  if (overflowBehavior === "error" && referencedSkillIds.length > skillLimit) {
-    throw new Error(
-      `Too many skills requested in a single turn. Reduce @skill-id usage to ${skillLimit} or fewer.`,
-    );
-  }
-  const selectedMetas = resolveSkillsFromMessages(
-    trajectory,
-    skillIndex,
-    skillLimit,
-  );
-  if (selectedMetas.length === 0) {
-    return [...baseSystemMessages, ...trajectory];
-  }
-  const skillBodies = await loadSkillBodies(skillsRoot, selectedMetas);
-  const skillMessages = skillBodies.map((body) => ({
-    role: "system",
-    content: body,
-  }));
-  return [...baseSystemMessages, ...skillMessages, ...trajectory];
-}

package/bundled-skills/docs/integrations/jetski-gemini-loader/package.json DELETED Viewed

	@@ -1 +0,0 @@
1	- {"type": "module"}

package/bundled-skills/docs/maintainers/aas-agent-first-control-plane-preview-profile.md DELETED Viewed

@@ -1,63 +0,0 @@
-# AAS Agent-Owned Selection Profile
-Status: active product profile
-Updated: 2026-07-19
-## Purpose
-This profile defines the supported boundary for AAS Core after semantic skill selection moved to the coding agent.
-> Codex or Claude inspects the project, searches and reads the complete local catalog, and chooses exact skill IDs. AAS Core validates, pins, compares, and plans that agent-owned selection; it does not recommend skills.
-The earlier deterministic recommendation design and goal documents are retained as historical architecture records. They are not current product policy or release gates.
-## Supported surfaces
-- A complete, integrity-verified local catalog in which every canonical skill is searchable, readable, and available for agent selection.
-- Local stdio MCP tools `search_skills`, `get_skill`, `compose_stack`, `inspect_stack`, and `diff_stack`, plus `aas://skills/{id}`.
-- Minimal, schema-validated `aas-stack.json` with pinned catalog identity, targets, goals, and exact agent-selected skill IDs.
-- CLI manifest validation, immutable plan preview, and read-only diagnosis.
-- Workbench import and review of the agent-owned stack and immutable plan.
-## Selection contract
-1. The coding agent owns semantic selection. It may inspect the project with its normal local capabilities, search broadly, read full skill content when useful, compare alternatives, and choose exact IDs.
-2. AAS Core does not rank, recommend, promote, demote, exclude, or abstain on skills.
-3. Catalog metadata is informational only. Missing, incomplete, cautionary, or manually reviewed metadata must never make a canonical skill unsearchable or unavailable for agent selection.
-4. `compose_stack` validates catalog identity, target shape, goals, exact IDs, and structural limits, then returns the pinned stack shape. It does not substitute a different selection.
-5. `aas-stack.json` has no Core selection policy. User constraints can guide the agent's reasoning, but they are not an MCP eligibility filter or manifest gate.
-## Functional gate
-The packed-product smoke path must prove:
-1. **Catalog completeness** — packaged catalog count and IDs equal the canonical registry; exact-ID search, `get_skill`, and content reads work for every canonical skill.
-2. **MCP contract** — the five supported read-only tools and resource template work over real stdio framing without repository scanning or state writes.
-3. **Agent-owned composition** — `compose_stack` preserves the exact ordered ID selection supplied by the agent and returns a structurally valid manifest without a policy field.
-4. **No metadata gating** — skills with unknown, critical, manual, blocked, incomplete, or absent informational metadata remain searchable, selectable, composable, and plannable.
-5. **Stack lifecycle** — compose, inspect, validate, plan, and doctor succeed in isolated roots without materializing target skills or managed state.
-6. **Workbench** — bounded text-only import/review tests and production build pass without ambient filesystem access.
-## Experimental writes
-`stack apply` and `stack recover` remain experimental opt-ins. The supported public path stops after manifest validation and immutable plan review. Planning may write only the explicitly requested plan artifact.
-## Trust and privacy boundaries
-- MCP is local, offline-capable, read-only, bounded, and non-mutating.
-- AAS does not receive repository files unless the agent explicitly reads them through its own host capabilities; AAS MCP does not scan the repository.
-- Full skill prose is untrusted content and gains no instruction authority through MCP.
-- Catalog and runtime integrity remain deterministic even though semantic selection belongs to the agent.
-- Real host configuration writes, publication, Pages deployment, npm release, and announcements require their separate approvals.
-## Product-learning gate
-Evaluate the quality of the agent workflow, not a Core recommender:
-- task completion from project inspection to a reviewable stack;
-- human accept, replace, and remove rates for agent-selected skills;
-- whether the agent searched enough of the catalog and read relevant skill content;
-- time and interaction count from request to approved manifest;
-- successful replay of the exact approved IDs against the pinned catalog identity.
-No repository profile, source file, secret, or raw path is uploaded by default. Publishing or sharing any collected result requires a separate privacy decision.