playbooks-cli: Instructions file for Codex

AGENTS.md

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

Project Overview

playbooks is a CLI tool that installs agent skills (reusable instruction sets in SKILL.md files) onto various coding agents. It supports 23+ agents including OpenCode, Claude Code, Cursor, Codex, and more.

Usage

npx playbooks add-skill <source>          # Install a skill from GitHub, URL, or local path
npx playbooks add-skill <source> --global # Install globally for the current user

Architecture

src/
├── index.ts          # CLI entry point, main flow orchestration
├── types.ts          # Core TypeScript types (AgentType, Skill, etc.)
├── agents.ts         # Agent configurations (paths, detection logic)
├── skills.ts         # Skill discovery from SKILL.md files
├── installer.ts      # Installation logic (symlink/copy modes)
├── source-parser.ts  # Parse input sources (GitHub, local, URLs)
├── git.ts            # Git clone operations
├── mintlify.ts       # Legacy Mintlify skill fetching
├── telemetry.ts      # Anonymous usage tracking
├── skill-lock.ts     # Lock file for installed skills
└── providers/
    ├── index.ts      # Provider registry exports
    ├── types.ts      # HostProvider interface
    ├── registry.ts   # Provider registration
    ├── mintlify.ts   # Mintlify provider
    └── huggingface.ts # HuggingFace provider

Key Concepts

Agent Configuration

Each agent is defined in src/agents.ts with:

• name: CLI identifier (e.g., claude-code)
• displayName: Human-readable name
• skillsDir: Project-level skill directory
• globalSkillsDir: User-level skill directory
• detectInstalled: Function to check if agent is installed

Skill Format

Skills are directories containing a SKILL.md with YAML frontmatter:

---
name: skill-name
description: What this skill does
---

# Instructions...

Installation Modes

1. Symlink (default): Skills are stored in .agents/skills/<name>/ and symlinked to each agent's directory
2. Copy: Skills are copied directly to each agent's directory