skills: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents working on the skills CLI codebase.

Project Overview

skills is the CLI for the open agent skills ecosystem.

Commands

Aliases: skills a works for add. skills i, skills install (no args) restore from skills-lock.json. skills ls works for list. skills experimental_install restores from skills-lock.json. skills experimental_sync reads skills from npm dependencies (sync remains a compatibility alias).

Architecture

src/
├── index.ts         # Public library entry: named re-exports of src/api only
├── api/             # Programmatic API (see docs/api.md)
│   ├── types.ts     # Hand-written public types (never alias internal types)
│   ├── config.ts    # resolveConfig: call options > config > defaults; agent limits
│   ├── agents.ts    # getSupportedAgents, detectAgents
│   ├── resolve.ts   # resolveSource / SkillSource handles
│   ├── install.ts   # installSkills
│   ├── list.ts      # listSkills
│   └── remove.ts    # removeSkills
├── cli.ts           # Main entry point, command routing, init/check/update
├── cli.test.ts      # CLI tests
├── add.ts           # Core add command logic
├── add-prompt.test.ts # Add prompt behavior tests
├── add.test.ts      # Add command tests
├── concurrency.ts   # Bounded parallel map for source clones/downloads (SKILLS_CLONE_CONCURRENCY)
├── constants.ts      # Shared constants
├── diagnostics.ts   # nostics catalog of every error/warning code (SKILLS_<WHAT_WENT_WRONG>)
├── find.ts           # Find/search command
├── list.ts          # List installed skills command
├── list.test.ts     # List command tests
├── remove.ts         # Remove command implementation
├── remove.test.ts    # Remove command tests
├── agents.ts        # Agent definitions and detection
├── installer.ts     # Skill installation logic (symlink/copy) + listInstalledSkills
├── skills.ts        # Skill discovery and parsing
├── skill-lock.ts    # Global lock file management (~/.agents/.skill-lock.json)
├── local-lock.ts    # Local lock file management (skills-lock.json, checked in)
├── sync.ts          # Sync command - crawl node_modules for skills
├── source-parser.ts # Parse git URLs, GitHub shorthand, local paths
├── git.ts           # Git clone operations
├── telemetry.ts     # Anonymous usage tracking
├── types.ts         # TypeScript types
├── plugin-manifest.ts # Plugin manifest discovery support
├── prompts/         # Interactive prompt helpers
│   └── search-multiselect.ts
├── providers/       # Remote skill providers (GitHub, HuggingFace, Mintlify)
│   ├── index.ts
│   ├── registry.ts
│   ├── types.ts
│   └── wellknown.ts
├── init.test.ts     # Init command tests
├── use.ts           # Use command - generate a skill prompt or launch an agent
├── use.test.ts      # Use command tests
└── test-utils.ts    # Test utilities

tests/
├── cross-platform-paths.test.ts # Path normalization across platforms
├── full-depth-discovery.test.ts # --full-depth skill discovery tests
├── openclaw-paths.test.ts       # OpenClaw-specific path tests
├── plugin-manifest-discovery.test.ts # Plugin manifest skill discovery
├── sanitize-name.test.ts     # Tests for sanitizeName (path traversal prevention)
├── skill-matching.test.ts    # Tests for filterSkills (multi-word skill name matching)
├── source-parser.test.ts     # Tests for URL/path parsing
├── installer-symlink.test.ts # Tests for symlink installation
├── list-installed.test.ts    # Tests for listing installed skills
├── skill-path.test.ts        # Tests for skill path handling
├── wellknown-provider.test.ts # Tests for well-known provider
├── xdg-config-paths.test.ts   # XDG global path handling tests
├── api.test.ts                # Programmatic API tests
└── dist.test.ts               # Tests for built distribution

e2e/                 # Production e2e: packed tarball vs. live sources (`pnpm test:e2e`)
├── setup.ts         # globalSetup: build, `pnpm pack`, `npm install` into a clean prefix
├── env.ts           # Env allowlist (drops agent markers, XDG/config overrides, CI)
├── sandbox.ts       # Per-test HOME + project dir; runs the installed bin
├── package.e2e.ts   # Tarball contents, bin shim, runtime deps
├── api.e2e.ts       # Programmatic API from the installed package, CLI interop, shipped types
├── github.e2e.ts    # anthropics/skills, mattpocock/skills, vercel-labs/agent-skills
├── blob.e2e.ts      # skills.sh blob fast path, parity with a git clone
├── well-known.e2e.ts # https://vercel.com discovery index
├── notion.e2e.ts    # Stub `ntn` on PATH + local archive server
└── npm.e2e.ts       # experimental_sync with registry and tarball packages

__snapshots__/tsnapi/          # Public API snapshot, checked by every build