claude-skills/scripts/codex-install.sh
Alireza Rezvani ebbf6b0872
Some checks failed
Sync Codex Skills Symlinks / sync (push) Has been cancelled
fix: v2.14.0 audit P0/P1 fixes (plugin updates, Codex, mirrors, script paths, two script bugs) (#1048)
* fix(plugins): bump all plugins to 2.14.1 and gate unbumped changes

Claude Code caches plugins by version. 70 of 104 plugins changed between
v2.12.0 and v2.14.0 without a bump, so claude plugin update reported
"already at the latest version" and existing installs never received the
v2.13/v2.14 fixes. Every plugin moves to 2.14.1 so stale caches refresh once.

check_plugin_versions.py (G11, blocking in ci-quality-gate) fails when a
plugin's payload, including symlinked vendor files, changes without a higher
version, and when marketplace.json and plugin.json disagree.
bump_plugin_versions.py sets both together.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(codex): stop installing all skills by default

With the full library (~380 skills) Codex drops every skill description from
its prompt budget, so it cannot pick skills. codex-install.sh now asks for
--category (comma-separated), --skill or an explicit --all, lists categories
when run without arguments, and warns when more than ~100 skills are
installed. The Windows installer and install docs follow.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(gemini): link whole skill folders and drop duplicate mirror entries

Each .gemini/skills entry held only a SKILL.md symlink, so the relative
scripts/ and references/ a skill points to were missing. Entries are now
directory symlinks (Gemini CLI 0.65 discovers them). Dual-published copies
with identical SKILL.md are listed once, commands and agents that share a
skill's name are skipped, fixtures under assets/ and vendor/ re-exports are
excluded, discovery is sorted so reruns are stable, and stale generated
entries are pruned. gemini skills list: 20 conflicts -> 1 (handoff, fixed
next). GEMINI.md documents folder trust and fixes a dead example path.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(handoff): rename the productivity skill to session-handoff

engineering/handoff and productivity/handoff both shipped a skill named
handoff. Claude Code namespaces them, but Codex, Gemini CLI, Vibe and Hermes
key skills by name and silently kept one. The productivity skill is now
session-handoff (handoff-productivity:session-handoff); its folder, plugin
manifest, hook script paths, command paths, mirrors, harness manifest and
docs page follow. /cs-handoff, /cs-handoff-setup and ~/.config/handoff are
unchanged; the plugin README carries a migration note.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(convert): include plugins whose SKILL.md is at the plugin root

convert.sh searched at -mindepth 4, which skipped boost-asio-pro, deepread,
hivemind, loop-library, minimalist, strict-api and swedish-mentor for every
converted tool (opencode, Cursor, Windsurf, Kilo, Augment, Aider,
Antigravity). It now searches from depth 2 and skips assets/ fixtures.
opencode conversion: 375 -> 382 skills.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(codex): keep skill-tester's sample fixture from loading as a skill

Codex scans installed skill folders recursively and picked up
skill-tester/assets/sample-skill/SKILL.md as 'sample-text-processor'.
The installer renames SKILL.md files under assets/ in the installed copy.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(plugins): address scripts via ${CLAUDE_PLUGIN_ROOT} in commands and agents

343 script invocations in 90 command/agent files across 36 plugins used
repo-relative or ../ paths. Plugin commands and agents run from the user's
project, so those paths only resolved inside a clone of this repo; in the
v2.14.0 evals the agent fell back to find / to locate scripts. Every one now
uses ${CLAUDE_PLUGIN_ROOT}/. Two cross-plugin calls (write-a-skill ->
karpathy-coder, c-level-agents cpo -> product-manager-toolkit) go through
vendor/ symlinks, per the repo's install-cache lesson.

check_paths.py (G1) now fails a plugin command or agent that invokes a
script without ${CLAUDE_PLUGIN_ROOT}; on the v2.14.0 tree it reports 279.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(month-end-close): treat opening-balance rows as balances and pair transpositions

On a bank and GL export that each begin with an 'Opening balance' row, the
matcher returned RECONCILED_WITH_ITEMS and told the user to book a 25,000.00
journal entry for the opening balance, and it reported a 7,980/7,890
transposition as two unrelated items. Opening rows are now balances: a
difference between them is reported as carried in from the prior period
(R5, blocks sign-off, never booked). Same-date digit transpositions pair into
one correcting entry. The GL file's 'memo' column is read as description.
The v2.14.0 eval fixture now proves 1,405.00 = 150 opening + 90
transposition + 1,200 outstanding check - 35 bank fee. Bundled copy synced.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* fix(coding-agent-rollout): flag connection-URL passwords and production MCP servers

On a committed .claude/settings.json holding
env.DATABASE_URL=postgresql://admin:<password>@prod-db... and
enabledMcpjsonServers: ["postgres-prod"], the linter flagged neither: the
env check only matched token formats and KEY/TOKEN/SECRET names. S11 now
catches a password embedded in any connection URL (BLOCKER in shared files),
and new S13 warns when a shared file pre-approves an MCP server whose name
marks it as production. Bundled copy synced; --sample output unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

* docs: changelog and lessons for the v2.14.0 audit fixes

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016uNBQ6tRS5P1dRsgNfK4Wh

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-10-22 09:50:05 +02:00

424 lines
10 KiB
Bash
Executable file

#!/usr/bin/env bash
#
# Codex Installation Script for Claude Skills Library
#
# Installs skills from this repository to your local Codex skills directory.
# Follows symlinks to copy actual skill contents.
#
# Usage:
# ./scripts/codex-install.sh (--category <name>[,<name>] | --skill <name> | --all)
#
# Options:
# --category <name> Install one or more categories (comma-separated)
# --skill <name> Install a single skill by name
# --all Install every skill (not recommended, see below)
# --list List available skills and categories
# --dry-run Show what would be installed without making changes
# --help Show this help message
#
# Codex fits all skill descriptions into a fixed prompt budget. Around 100
# skills it starts cutting descriptions short; with the full library (~380)
# it drops them entirely and Codex can no longer tell which skill fits a task.
# Install the categories you use. Run without arguments to see them.
#
# Examples:
# ./scripts/codex-install.sh --category engineering,product
# ./scripts/codex-install.sh --skill content-creator
# ./scripts/codex-install.sh --list
#
set -e
# Configuration
CODEX_SKILLS_DIR="${CODEX_SKILLS_DIR:-$HOME/.codex/skills}"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(dirname "$SCRIPT_DIR")"
CODEX_SKILLS_SRC="$REPO_ROOT/.codex/skills"
CODEX_INDEX="$REPO_ROOT/.codex/skills-index.json"
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Print colored output
print_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Show help
show_help() {
sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'
exit "${1:-0}"
}
# Codex's skill list budget: beyond this many installed skills, descriptions
# are truncated, and with the full library they disappear.
CODEX_SKILL_WARN_AT=100
warn_if_crowded() {
[[ -d $CODEX_SKILLS_DIR ]] || return 0
local total
total=$(find "$CODEX_SKILLS_DIR" -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l | tr -d ' ')
if ((total > CODEX_SKILL_WARN_AT)); then
echo ""
print_warning "$total skills are now installed in $CODEX_SKILLS_DIR."
print_warning "Above about $CODEX_SKILL_WARN_AT, Codex shortens skill descriptions; with the full library it shows names only."
print_warning "Remove categories you don't use from $CODEX_SKILLS_DIR to keep skill selection working."
fi
}
# Shown when no mode is given: installing everything is no longer the default.
choose_hint() {
print_error "Choose what to install: --category <name>[,<name>], --skill <name>, or --all."
echo ""
if [[ -f $CODEX_INDEX ]] && command -v python3 &> /dev/null; then
CODEX_INDEX="$CODEX_INDEX" python3 << 'EOF'
import json, os
cats = json.load(open(os.environ["CODEX_INDEX"], encoding="utf-8")).get("categories", {})
print("Categories:")
for name, info in sorted(cats.items()):
print(f" {name:22} {info['count']:>3} skills")
EOF
fi
echo ""
print_info "Example: $0 --category engineering,product"
print_info "--all installs every skill, which leaves Codex with skill names but no descriptions."
exit 2
}
# Check prerequisites
check_prerequisites() {
if [[ ! -d $CODEX_SKILLS_SRC ]]; then
print_error "Codex skills directory not found: $CODEX_SKILLS_SRC"
print_info "Run 'python scripts/sync-codex-skills.py' first to generate symlinks."
exit 1
fi
if [[ ! -f $CODEX_INDEX ]]; then
print_warning "skills-index.json not found. Some features may be limited."
fi
}
# List available skills
list_skills() {
print_info "Available skills in $CODEX_SKILLS_SRC:"
echo ""
if [[ -f $CODEX_INDEX ]] && command -v python3 &> /dev/null; then
# Use Python to parse JSON and display nicely
CODEX_INDEX="$CODEX_INDEX" python3 << 'EOF'
import json
import os
import sys
try:
with open(os.environ["CODEX_INDEX"], "r", encoding="utf-8") as f:
index = json.load(f)
print("Categories:")
print("-" * 50)
for cat, info in index.get('categories', {}).items():
print(f" {cat}: {info['count']} skills")
print()
print("Skills by category:")
print("-" * 50)
current_cat = None
for skill in index.get('skills', []):
if skill['category'] != current_cat:
current_cat = skill['category']
print(f"\n [{current_cat}]")
print(f" - {skill['name']}: {skill['description'][:60]}...")
except Exception as e:
print(f"Error parsing index: {e}")
sys.exit(1)
EOF
else
# Fallback to simple listing
for skill in "$CODEX_SKILLS_SRC"/*; do
if [[ -L $skill ]] && [[ -e "$skill/SKILL.md" ]]; then
echo " - $(basename "$skill")"
fi
done
fi
exit 0
}
# Install a single skill
install_skill() {
local skill_name="$1"
local dry_run="$2"
if [[ -z $skill_name || $skill_name == */* || $skill_name == *..* ]]; then
print_error "Invalid skill name: $skill_name"
return 1
fi
local skill_src="$CODEX_SKILLS_SRC/$skill_name"
local skill_dest="$CODEX_SKILLS_DIR/$skill_name"
# Check if skill exists
if [[ ! -e $skill_src ]]; then
print_error "Skill not found: $skill_name"
return 1
fi
# Check if it's a valid skill (has SKILL.md)
if [[ ! -e "$skill_src/SKILL.md" ]]; then
print_error "Invalid skill (no SKILL.md): $skill_name"
return 1
fi
if [[ $dry_run == "true" ]]; then
print_info "[DRY RUN] Would install: $skill_name -> $skill_dest"
return 0
fi
# Create destination directory
mkdir -p "$CODEX_SKILLS_DIR"
# Remove existing installation
if [[ -e $skill_dest ]]; then
print_info "Updating existing skill: $skill_name"
rm -rf "$skill_dest"
fi
# Copy skill (following symlinks with -L)
cp -rL "$skill_src" "$skill_dest"
# Codex scans installed skill folders recursively, so a fixture such as
# skill-tester/assets/sample-skill/SKILL.md would load as a real skill.
find "$skill_dest" -mindepth 2 -path '*/assets/*' -name SKILL.md \
-exec sh -c 'mv "$1" "$1.fixture"' _ {} \;
print_success "Installed: $skill_name"
return 0
}
# Install skills by category
install_category() {
local category="$1"
local dry_run="$2"
local installed=0
local failed=0
if [[ ! -f $CODEX_INDEX ]]; then
print_error "skills-index.json required for category installation"
exit 1
fi
if ! command -v python3 &> /dev/null; then
print_error "python3 is required for category installation"
exit 1
fi
print_info "Installing skills from category: $category"
# Get skills for this category from index
local skills
skills=$(
CODEX_INDEX="$CODEX_INDEX" CATEGORY="$category" python3 << 'EOF'
import json
import os
with open(os.environ["CODEX_INDEX"], "r", encoding="utf-8") as f:
index = json.load(f)
seen = set()
for skill in index.get('skills', []):
name = skill.get('name')
if skill.get('category') in os.environ["CATEGORY"].split(",") and name and name not in seen:
seen.add(name)
print(name)
EOF
)
if [[ -z $skills ]]; then
print_error "No skills found for category: $category"
exit 1
fi
while IFS= read -r skill; do
if install_skill "$skill" "$dry_run"; then
((++installed))
else
((++failed))
fi
done <<< "$skills"
echo ""
print_info "Category '$category' complete: $installed installed, $failed failed"
[[ $dry_run == "true" ]] || warn_if_crowded
}
# Install all skills
install_all() {
local dry_run="$1"
local installed=0
local failed=0
local skills=""
print_info "Installing all skills to: $CODEX_SKILLS_DIR"
print_warning "With every skill installed, Codex drops skill descriptions from its prompt."
print_warning "Prefer --category <name>[,<name>] for the domains you use."
echo ""
if [[ -f $CODEX_INDEX ]] && command -v python3 &> /dev/null; then
skills=$(
CODEX_INDEX="$CODEX_INDEX" python3 << 'EOF'
import json
import os
with open(os.environ["CODEX_INDEX"], "r", encoding="utf-8") as f:
index = json.load(f)
seen = set()
for skill in index.get("skills", []):
name = skill.get("name")
if name and name not in seen:
seen.add(name)
print(name)
EOF
)
while IFS= read -r skill_name; do
if [[ -z $skill_name ]]; then
continue
fi
if install_skill "$skill_name" "$dry_run"; then
((++installed))
else
((++failed))
fi
done <<< "$skills"
else
for skill in "$CODEX_SKILLS_SRC"/*; do
if [[ -L $skill ]] || [[ -d $skill ]]; then
local skill_name
skill_name=$(basename "$skill")
if install_skill "$skill_name" "$dry_run"; then
((++installed))
else
((++failed))
fi
fi
done
fi
echo ""
print_info "Installation complete: $installed installed, $failed failed"
if [[ $dry_run != "true" ]]; then
echo ""
print_success "Skills installed to: $CODEX_SKILLS_DIR"
print_info "Verify with: ls $CODEX_SKILLS_DIR"
warn_if_crowded
fi
}
# Main
main() {
local mode=""
local target=""
local dry_run="false"
# Parse arguments
while [[ $# -gt 0 ]]; do
case $1 in
--all)
mode="all"
shift
;;
--category)
if [[ $# -lt 2 || -z ${2:-} || ${2:-} == --* ]]; then
print_error "Category name required"
exit 1
fi
mode="category"
target="$2"
shift 2
;;
--skill)
if [[ $# -lt 2 || -z ${2:-} || ${2:-} == --* ]]; then
print_error "Skill name required"
exit 1
fi
mode="skill"
target="$2"
shift 2
;;
--list)
mode="list"
shift
;;
--dry-run)
dry_run="true"
shift
;;
--help | -h)
show_help
;;
*)
print_error "Unknown option: $1"
show_help
;;
esac
done
# Banner
echo ""
echo "========================================"
echo " Claude Skills - Codex Installer"
echo "========================================"
echo ""
check_prerequisites
case $mode in
list)
list_skills
;;
skill)
if [[ -z $target ]]; then
print_error "Skill name required"
exit 1
fi
install_skill "$target" "$dry_run"
;;
category)
if [[ -z $target ]]; then
print_error "Category name required"
exit 1
fi
install_category "$target" "$dry_run"
;;
all)
install_all "$dry_run"
;;
"")
choose_hint
;;
esac
}
main "$@"