opencode-skills-collection 2.0.38 → 2.0.39

package/README.md

@@ -184,9 +184,6 @@ The old `opencode-skills-antigravity` package on npm is deprecated and re-export
 Issues and pull requests are welcome
 at [github.com/FrancoStino/opencode-skills-collection](https://github.com/FrancoStino/opencode-skills-collection/issues).
 
-If you'd like to contribute new skills to the collection, open a PR adding a new folder inside `bundled-skills/` — it
-will be automatically picked up on next sync.
-
 ---
 
 ## Beta Releases

package/bundled-skills/.antigravity-install-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-04-11T18:48:47.035Z",
+  "updatedAt": "2026-04-11T19:36:06.899Z",
   "entries": [
     "00-andruia-consultant",
     "007",
@@ -1168,6 +1168,7 @@
     "skill-developer",
     "skill-improver",
     "skill-installer",
+    "skill-optimizer",
     "skill-rails-upgrade",
     "skill-router",
     "skill-scanner",

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

@@ -1,9 +1,9 @@
 ---
 title: Jetski/Cortex + Gemini Integration Guide
-description: "Use antigravity-awesome-skills with Jetski/Cortex without hitting context-window overflow with 1.400+ skills."
+description: "Use antigravity-awesome-skills with Jetski/Cortex without hitting context-window overflow with 1.401+ skills."
 ---
 
-# Jetski/Cortex + Gemini: safe integration with 1,1.400+ skills
+# Jetski/Cortex + Gemini: safe integration with 1,1.401+ skills
 
 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**.
 
@@ -23,7 +23,7 @@ Never do:
 - concatenate all `SKILL.md` content into a single system prompt;
 - re-inject the entire library for **every** request.
 
-With over 1,1.400 skills, this approach fills the context window before user messages are even added, causing truncation.
+With over 1,1.401 skills, this approach fills the context window before user messages are even added, causing truncation.
 
 ---
 

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

@@ -20,7 +20,7 @@ This example shows one way to integrate **antigravity-awesome-skills** with a Je
 - 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 1,400+ skills installed.
+This pattern avoids context overflow when you have 1,401+ skills installed.
 
 ---
 

package/bundled-skills/docs/maintainers/repo-growth-seo.md

@@ -6,7 +6,7 @@ This document keeps the repository's GitHub-facing discovery copy aligned with t
 
 Preferred positioning:
 
-> Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and other AI coding assistants.
+> Installable GitHub library of 1,401+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and other AI coding assistants.
 
 Key framing:
 
@@ -20,7 +20,7 @@ Key framing:
 
 Preferred description:
 
-> Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
+> Installable GitHub library of 1,401+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
 
 Preferred homepage:
 
@@ -28,7 +28,7 @@ Preferred homepage:
 
 Preferred social preview:
 
-- use a clean preview image that says `1,400+ Agentic Skills`;
+- use a clean preview image that says `1,401+ Agentic Skills`;
 - mention Claude Code, Cursor, Codex CLI, and Gemini CLI;
 - avoid dense text and tiny logos that disappear in social cards.
 

package/bundled-skills/docs/maintainers/skills-update-guide.md

@@ -69,7 +69,7 @@ For manual updates, you need:
 The update process refreshes:
 - Skills index (`skills_index.json`)
 - Web app skills data (`apps\web-app\public\skills.json`)
-- All 1,400+ skills from the skills directory
+- All 1,401+ skills from the skills directory
 
 ## When to Update
 

package/bundled-skills/docs/users/bundles.md

@@ -673,4 +673,4 @@ Found a skill that should be in a bundle? Or want to create a new bundle? [Open
 
 ---
 
-_Last updated: March 2026 | Total Skills: 1,400+ | Total Bundles: 37_
+_Last updated: March 2026 | Total Skills: 1,401+ | Total Bundles: 37_

package/bundled-skills/docs/users/claude-code-skills.md

@@ -12,7 +12,7 @@ Install the library into Claude Code, then invoke focused skills directly in the
 
 ## Why use this repo for Claude Code
 
-- It includes 1,400+ skills instead of a narrow single-domain starter pack.
+- It includes 1,401+ skills instead of a narrow single-domain starter pack.
 - It supports the standard `.claude/skills/` path and the Claude Code plugin marketplace flow.
 - It also ships generated bundle plugins so teams can install focused packs like `Essentials` or `Security Developer` from the marketplace metadata.
 - It includes onboarding docs, bundles, and workflows so new users do not need to guess where to begin.

package/bundled-skills/docs/users/gemini-cli-skills.md

@@ -12,7 +12,7 @@ Install into the Gemini skills path, then ask Gemini to apply one skill at a tim
 
 - It installs directly into the expected Gemini skills path.
 - It includes both core software engineering skills and deeper agent/LLM-oriented skills.
-- It helps new users get started with bundles and workflows rather than forcing a cold start from 1,400+ files.
+- It helps new users get started with bundles and workflows rather than forcing a cold start from 1,401+ files.
 - It is useful whether you want a broad internal skill library or a single repo to test many workflows quickly.
 
 ## Install Gemini CLI Skills

package/bundled-skills/docs/users/getting-started.md

@@ -1,4 +1,4 @@
-# Getting Started with Antigravity Awesome Skills (V9.11.0)
+# Getting Started with Antigravity Awesome Skills (V9.12.0)
 
 **New here? This guide will help you supercharge your AI Agent in 5 minutes.**
 

package/bundled-skills/docs/users/kiro-integration.md

@@ -18,7 +18,7 @@ Kiro is AWS's agentic AI IDE that combines:
 
 Kiro's agentic capabilities are enhanced by skills that provide:
 
-- **Domain expertise** across 1,400+ specialized areas
+- **Domain expertise** across 1,401+ specialized areas
 - **Best practices** from Anthropic, OpenAI, Google, Microsoft, and AWS
 - **Workflow automation** for common development tasks
 - **AWS-specific patterns** for serverless, infrastructure, and cloud architecture

package/bundled-skills/docs/users/usage.md

@@ -14,7 +14,7 @@ If you came in through a **Claude Code** or **Codex** plugin instead of a full l
 
 When you ran `npx antigravity-awesome-skills` or cloned the repository, you:
 
-✅ **Downloaded 1,400+ skill files** to your computer (default: `~/.gemini/antigravity/skills/`; or a custom path like `~/.agent/skills/` if you used `--path`)  
+✅ **Downloaded 1,401+ skill files** to your computer (default: `~/.gemini/antigravity/skills/`; or a custom path like `~/.agent/skills/` if you used `--path`)  
 ✅ **Made them available** to your AI assistant  
 ❌ **Did NOT enable them all automatically** (they're just sitting there, waiting)
 
@@ -34,7 +34,7 @@ Bundles are **curated groups** of skills organized by role. They help you decide
 
 **Analogy:**
 
-- You installed a toolbox with 1,400+ tools (✅ done)
+- You installed a toolbox with 1,401+ tools (✅ done)
 - Bundles are like **labeled organizer trays** saying: "If you're a carpenter, start with these 10 tools"
 - You can either **pick skills from the tray** or install that tray as a focused marketplace bundle plugin
 
@@ -212,7 +212,7 @@ Let's actually use a skill right now. Follow these steps:
 
 ## Step 5: Picking Your First Skills (Practical Advice)
 
-Don't try to use all 1,400+ skills at once. Here's a sensible approach:
+Don't try to use all 1,401+ skills at once. Here's a sensible approach:
 
 If you want a tool-specific starting point before choosing skills, use:
 
@@ -343,7 +343,7 @@ Usually no, but if your AI doesn't recognize a skill:
 
 ### "Can I load all skills into the model at once?"
 
-No. Even though you have 1,400+ skills installed locally, you should **not** concatenate every `SKILL.md` into a single system prompt or context block.
+No. Even though you have 1,401+ skills installed locally, you should **not** concatenate every `SKILL.md` into a single system prompt or context block.
 
 The intended pattern is:
 

package/bundled-skills/docs/users/visual-guide.md

@@ -34,7 +34,7 @@ antigravity-awesome-skills/
 ├── 📄 CONTRIBUTING.md                  ← Contributor workflow
 ├── 📄 CATALOG.md                       ← Full generated catalog
 │
-├── 📁 skills/                          ← 1,400+ skills live here
+├── 📁 skills/                          ← 1,401+ skills live here
 │   │
 │   ├── 📁 brainstorming/
 │   │   └── 📄 SKILL.md                 ← Skill definition
@@ -47,7 +47,7 @@ antigravity-awesome-skills/
 │   │   └── 📁 2d-games/
 │   │       └── 📄 SKILL.md             ← Nested skills also supported
 │   │
-│   └── ... (1,400+ total)
+│   └── ... (1,401+ total)
 │
 ├── 📁 apps/
 │   └── 📁 web-app/                     ← Interactive browser
@@ -100,7 +100,7 @@ antigravity-awesome-skills/
 
 ```
                     ┌─────────────────────────┐
-                    │  1,400+ SKILLS          │
+                    │  1,401+ SKILLS          │
                     └────────────┬────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
@@ -201,7 +201,7 @@ If you want a workspace-style manual install instead, cloning into `.agent/skill
 │   ├── 📁 brainstorming/                 │
 │   ├── 📁 stripe-integration/            │
 │   ├── 📁 react-best-practices/          │
-│   └── ... (1,400+ total)                │
+│   └── ... (1,401+ total)                │
 └─────────────────────────────────────────┘
 ```
 

package/bundled-skills/skill-optimizer/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: skill-optimizer
+description: "Diagnose and optimize Agent Skills (SKILL.md) with real session data and research-backed static analysis. Works with Claude Code, Codex, and any Agent Skills-compatible agent."
+risk: safe
+source: hqhq1025/skill-optimizer (MIT)
+date_added: "2026-04-11"
+---
+
+## When to Use This Skill
+
+- Use when skills are not triggering as expected or seem broken
+- Use when you want to audit and improve your skill library's quality
+- Use when you want to understand which skills are underperforming or wasting context tokens
+
+## Rules
+
+- **Read-only**: never modify skill files. Only output report.
+- **All 8 dimensions**: do not skip any. If data is insufficient, report "N/A — insufficient session data" rather than omitting.
+- **Quantify**: "you had 12 research tasks last week but the skill never triggered" beats "you often do research".
+- **Suggest, don't prescribe**: give specific wording suggestions for description improvements, but frame as suggestions.
+- **Show evidence**: for undertrigger claims, quote the actual user message that should have triggered the skill.
+- **Evidence-based suggestions**: when suggesting description rewrites, cite the specific research finding that motivates the change (e.g., "front-load trigger keywords — MCP study shows 3.6x selection rate improvement").
+
+## Overview
+
+Analyze skills using **historical session data + static quality checks**, output a diagnostic report with P0/P1/P2 prioritized fixes. Scores each skill on a 5-point composite scale across 8 dimensions.
+
+CSO (Claude/Agent Search Optimization) = writing skill descriptions so agents select the right skill at the right time. This skill checks for CSO violations.
+
+## Usage
+
+- `/optimize-skill` → scan all skills
+- `/optimize-skill my-skill` → single skill
+- `/optimize-skill skill-a skill-b` → multiple specified skills
+
+## Data Sources
+
+Auto-detect the current agent platform and scan the corresponding paths:
+
+| Source | Claude Code | Codex | Shared |
+|--------|------------|-------|--------|
+| Session transcripts | `~/.claude/projects/**/*.jsonl` | `~/.codex/sessions/**/*.jsonl` | — |
+| Skill files | `~/.claude/skills/*/SKILL.md` | `~/.codex/skills/*/SKILL.md` | `~/.agents/skills/*/SKILL.md` |
+
+**Platform detection:** Check which directories exist. Scan all available sources — a user may have both Claude Code and Codex installed.
+
+## Workflow
+
+```
+Identify target skills
+        ↓
+Collect session data (python3 scripts scan JSONL transcripts)
+        ↓
+Run 8 analysis dimensions
+        ↓
+Compute composite scores
+        ↓
+Output report with P0/P1/P2
+```
+
+### Step 1: Identify Target Skills
+
+Scan skill directories in order: `~/.claude/skills/`, `~/.codex/skills/`, `~/.agents/skills/`. Deduplicate by skill name (same name in multiple locations = same skill). For each, read `SKILL.md` and extract:
+- name, description (from YAML frontmatter)
+- trigger keywords (from description field)
+- defined workflow steps (Step 1/2/3... or ### sections under Workflow)
+- word count
+
+If user specified skill names, filter to only those.
+
+### Step 2: Collect Session Data
+
+Use python3 scripts via Bash to scan session JSONL files. Extract:
+
+**Claude Code sessions** (`~/.claude/projects/**/*.jsonl`):
+- `Skill` tool_use calls (which skills were invoked)
+- User messages (full text)
+- Assistant messages after skill invocation (for workflow tracking)
+- User messages after skill invocation (for reaction analysis)
+
+**Codex sessions** (`~/.codex/sessions/**/*.jsonl`):
+- `session_meta` events → extract `base_instructions` for skill loading evidence
+- `response_item` events → assistant outputs (workflow tracking)
+- `event_msg` events → tool execution and skill-related events
+- User messages from `turn_context` events (for reaction analysis)
+
+**Note:** Codex injects skills via context rather than explicit `Skill` tool calls. Skill loading (present in `base_instructions`) does NOT equal active invocation. To detect actual use, search for skill-specific workflow markers (step headers, output formats) in `response_item` content within that session. A skill is "invoked" only if the agent produced output following the skill's defined workflow.
+
+**Aggregated:**
+- Per-skill: invocation count, trigger keyword match count
+- Per-skill: user reaction sentiment after invocation
+- Per-skill: workflow step completion markers
+
+### Step 3: Run 8 Analysis Dimensions
+
+**You MUST run ALL 8 dimensions.** The baseline behavior without this skill is to skip dimensions 4.2, 4.3, 4.5b, and 4.8. These are the most valuable dimensions — do not skip them.
+
+#### 4.1 Trigger Rate
+
+Count how many times each skill was actually invoked vs how many times its trigger keywords appeared in user messages.
+
+**Claude Code:** count `Skill` tool_use calls in transcripts.
+**Codex:** count sessions where the agent produced output following the skill's workflow markers (not merely loaded in context).
+
+**Diagnose:**
+- Never triggered → skill may be useless or trigger words wrong
+- Keywords match >> actual invocations → undertrigger problem, description needs work
+- High frequency → core skill, worth optimizing
+
+#### 4.2 Post-Invocation User Reaction
+
+**This dimension is critical and easy to skip. Do not skip it.**
+
+After a skill is invoked in a session, read the user's next 3 messages. Classify:
+- **Negative**: "no", "wrong", "never mind", "not what I wanted", user interrupts
+- **Correction**: user re-describes their intent, manually overrides skill output
+- **Positive**: "good", "ok", "continue", "nice", user follows the workflow
+- **Silent switch**: user changes topic entirely (likely false positive trigger)
+
+Report per-skill satisfaction rate.
+
+#### 4.3 Workflow Completion Rate
+
+**This dimension is critical and easy to skip. Do not skip it.**
+
+For each skill invocation found in session data:
+1. Extract the skill's defined steps from SKILL.md
+2. Search the assistant messages in that session for step markers (Step N, specific output formats defined in the skill)
+3. Calculate: how far did execution get?
+
+Report: `{skill-name} (N steps): avg completed Step X/N (Y%)`
+
+If a specific step is frequently where execution stops, flag it.
+
+#### 4.4 Static Quality Analysis
+
+Check each SKILL.md against these 14 rules:
+
+| Check | Pass Criteria |
+|-------|--------------|
+| Frontmatter format | Only `name` + `description`, total < 1024 chars |
+| Name format | Letters, numbers, hyphens only |
+| Description trigger | Starts with "Use when..." or has explicit trigger conditions |
+| Description workflow leak | Description does NOT summarize the skill's workflow steps (CSO violation) |
+| Description pushiness | Description actively claims scenarios where it should be used, not just passive |
+| Overview section | Present |
+| Rules section | Present |
+| MUST/NEVER density | Count ALL-CAPS directive words; >5 per 100 words = flag |
+| Word count | < 500 words (flag if over) |
+| Narrative anti-pattern | No "In session X, we found..." storytelling |
+| YAML quoting safety | description containing `: ` must be wrapped in double quotes |
+| Critical info position | Core trigger conditions and primary actions must be in the first 20% of SKILL.md |
+| Description 250-char check | Primary trigger keywords must appear within the first 250 characters of description |
+| Trigger condition count | ≤ 2 trigger conditions in description is ideal |
+
+#### 4.5a False Positive Rate (Overtrigger)
+
+Skill was invoked but user immediately rejected or ignored it.
+
+#### 4.5b Undertrigger Detection
+
+**This is the highest-value dimension.** For each skill, extract its **capability keywords** (not just trigger keywords — what the skill CAN do). Then scan user messages for tasks that match those capabilities but where the skill was NOT invoked.
+
+Report: which user messages SHOULD have triggered the skill but didn't, and suggest description improvements.
+
+**Compounding Risk Assessment:**
+For skills with chronic undertriggering (0 triggers across 5+ sessions where relevant tasks appeared), flag as "compounding risk" — undertriggered skills cannot self-improve through usage feedback, causing the gap to widen over time. Recommend immediate description rewrite as P0.
+
+#### 4.6 Cross-Skill Conflicts
+
+Compare all skill pairs:
+- Trigger keyword overlap (same keywords in two descriptions)
+- Workflow overlap (two skills teach similar processes)
+- Contradictory guidance
+
+#### 4.7 Environment Consistency
+
+For each skill, extract referenced:
+- File paths → check if they exist (`test -e`)
+- CLI tools → check if installed (`which`)
+- Directories → check if they exist
+
+Flag any broken references.
+
+#### 4.8 Token Economics
+
+**This dimension is critical and easy to skip. Do not skip it.**
+
+For each skill:
+- Word count (from Step 1)
+- Trigger frequency (from 4.1)
+- Cost-effectiveness = trigger count / word count
+- Flag: large + never-triggered skills as candidates for removal or compression
+
+**Progressive Disclosure Tier Check:**
+Evaluate each skill against the 3-tier loading model:
+- Tier 1 (frontmatter): ~100 tokens. Check: is description ≤ 1024 chars?
+- Tier 2 (SKILL.md body): <500 lines recommended. Check: word count.
+- Tier 3 (reference files): loaded on demand. Check: does skill use reference files for detailed content, or cram everything into SKILL.md?
+
+Flag skills that put 500+ words in SKILL.md without using reference files as "poor progressive disclosure".
+
+### Step 4: Composite Score
+
+Rate each skill on a 5-point scale:
+
+| Score | Meaning |
+|-------|---------|
+| 5 | Healthy: high trigger rate, positive reactions, complete workflows, clean static |
+| 4 | Good: minor issues in 1-2 dimensions |
+| 3 | Needs attention: significant gap in 1 dimension or minor gaps in 3+ |
+| 2 | Problematic: never triggered, or negative user reactions, or major static issues |
+| 1 | Broken: doesn't work, references missing, or fundamentally misaligned |
+
+**Scored dimensions** (weighted average):
+- Trigger rate: 25%
+- User reaction: 20%
+- Workflow completion: 15%
+- Static quality: 15%
+- Undertrigger: 15%
+- Token economics: 10%
+
+**Qualitative dimensions** (reported but not scored):
+- 4.5a Overtrigger: reported as count + examples
+- 4.6 Cross-Skill Conflicts: reported as conflict pairs
+- 4.7 Environment Consistency: reported as pass/fail per reference
+
+## Report Format
+
+```markdown
+# Skill Optimization Report
+**Date**: {date}
+**Scope**: {all / specified skills}
+**Session data**: {N} sessions, {date range}
+
+## Overview
+| Skill | Triggers | Reaction | Completion | Static | Undertrigger | Token | Score |
+|-------|----------|----------|------------|--------|--------------|-------|-------|
+| example-skill | 2 | 100% | 86% | B+ | 1 miss | 486w | 4/5 |
+
+## P0 Fixes (blocking usage)
+1. ...
+
+## P1 Improvements (better experience)
+1. ...
+
+## P2 Optional Optimizations
+1. ...
+
+## Per-Skill Diagnostics
+### {skill-name}
+#### 4.1 Trigger Rate
+...
+#### 4.2 User Reaction
+...
+(all 8 dimensions)
+```
+
+## Research Background
+
+The analysis dimensions in this report are grounded in the following research:
+- **Undertrigger detection**: Memento-Skills (arXiv:2603.18743) — skills as structured files require accurate routing; unrouted skills cannot self-improve via the read-write learning loop
+- **Description quality**: MCP Description Quality (arXiv:2602.18914) — well-written descriptions achieve 72% tool selection rate vs. 20% random baseline (3.6x improvement)
+- **Information position**: Lost in the Middle (Liu et al., TACL 2024) — U-shaped LLM attention curve
+- **Format impact**: He et al. (arXiv:2411.10541) — format changes alone can cause 9-40% performance variance
+- **Instruction compliance**: IFEval (arXiv:2311.07911) — LLMs struggle with multi-constraint prompts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-collection",
-  "version": "2.0.38",
+  "version": "2.0.39",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills_index.json

@@ -25596,6 +25596,30 @@
       "reasons": []
     }
   },
+  {
+    "id": "skill-optimizer",
+    "path": "skills/skill-optimizer",
+    "category": "meta",
+    "name": "skill-optimizer",
+    "description": "Diagnose and optimize Agent Skills (SKILL.md) with real session data and research-backed static analysis. Works with Claude Code, Codex, and any Agent Skills-compatible agent.",
+    "risk": "safe",
+    "source": "hqhq1025/skill-optimizer (MIT)",
+    "date_added": "2026-04-11",
+    "plugin": {
+      "targets": {
+        "codex": "blocked",
+        "claude": "blocked"
+      },
+      "setup": {
+        "type": "none",
+        "summary": "",
+        "docs": null
+      },
+      "reasons": [
+        "target_specific_home_path"
+      ]
+    }
+  },
   {
     "id": "skill-rails-upgrade",
     "path": "skills/skill-rails-upgrade",