skillman: Instructions file for Codex

AGENTS.md

Project Overview

skillman is a CLI wrapper to manage project skills and lock them in skills.json. It provides a declarative way to install skills per project, similar to how package managers work with package.json.

Architecture

src/
├── cli.ts              # CLI entry point with parseArgs
├── config.ts           # skills.json config management
├── skills.ts           # Skills CLI execution
└── utils/
    ├── colors.ts       # ANSI color codes for terminal output
    └── gitignore.ts    # .gitignore file management
test/index.test.ts      # Tests using vitest

Config (src/config.ts)

• findSkillsConfig(cwd?) — Finds skills.json by traversing up from cwd
• readSkillsConfig(options?) — Reads and validates skills.json (options: { cwd?, createIfNotExists? })
• updateSkillsConfig(updater, options?) — Generic update with callback (options: { cwd?, createIfNotExists? }, defaults createIfNotExists: true)
• addSkill(source, skills?, options?) — Adds a skill source (options: { cwd?, createIfNotExists? }, defaults createIfNotExists: true)
• Auto-injects $schema field during validation if missing

Skills CLI (src/skills.ts)

• findSkillsBinary(options?) — Finds local skills binary in node_modules/.bin (options: { cache? }, cached by default)
• installSkills(options?) — Spawns skills add for each source with progress logging; options: { cwd?, agents?, global?, yes? }
• installSkillSource(entry, options) — Installs a single skill source; options: { cwd?, agents?, global?, yes?, prefix? }

CLI Entry (src/cli.ts)

• main(argv?) — CLI entry point using Node.js parseArgs
• parseSource(input) — Parses source input into { source, skills }; supports:
  • Colon/comma format: owner/repo:skill1,skill2 or owner/repo:skill1:skill2
  • skills.sh URLs: https://skills.sh/owner/repo/skill-name

Utils (src/utils/)

colors.ts — ANSI escape codes for terminal styling: