feat: AGS v0 — cross-agent skill management CLI

[Binb1]

Summary

AGS (Agent Skills) — a zero-dependency Bun CLI for managing AI agent skills across Claude Code, Cursor, and Codex. Built for agents first, humans second.

Commands

Command	Purpose
ags scan	Discover all skills, commands, agents, and rules across agents — grouped by type with health badges, colors, and scope filtering
ags skill-cost	Context tax breakdown — per-skill token cost with bar charts relative to each agent's context limit
ags grab <url>	Install a skill from a GitHub blob URL
ags rm <name>	Remove a skill by name or path
ags stats	Usage dashboard — sessions, PRs created, real token usage, MCP integrations, skill/subagent invocations, peak hours heatmap
ags list-agents	Detect which agents are installed with skill counts

Design

• Agent-first — --json on every command with defined schemas, error codes, and structured output
• Zero runtime deps — Bun built-ins for fs, fetch, spawn, glob. Manual argv parser, YAML frontmatter parser, ANSI colors — all from scratch
• Exhaustive scanning — discovers skills, commands, agents (subagents), and rules across all three platforms. Handles both flat .md files and directory-based SKILL.md formats
• Real usage stats — parses session .jsonl files directly for accurate token counts, PR links, MCP integration usage, and skill invocation tracking
• Shell completions — static zsh/bash files for Homebrew auto-install
• Cross-compile — darwin-arm64, darwin-x64, linux-x64 via bun build --compile

Files

src/
├── index.ts              # CLI entry, argv parsing, per-command --help
├── types.ts              # All shared interfaces and output schemas
├── commands/
│   ├── scan.ts           # Grouped tables with colors, badges, scope
│   ├── budget.ts         # Context cost with bar charts vs limits
│   ├── grab.ts           # GitHub raw fetch + install
│   ├── rm.ts             # Remove by name or path
│   ├── stats.ts          # Dashboard from session jsonl parsing
│   └── list-agents.ts    # Agent detection
├── core/
│   ├── agents.ts         # Agent registry (paths, formats, detection)
│   ├── scanner.ts        # Multi-agent discovery with deduplication
│   ├── parser.ts         # Zero-dep YAML frontmatter parser
│   ├── tokens.ts         # chars/4 estimation
│   └── health.ts         # Badge computation (STALE, HEAVY, etc.)
└── utils/
    ├── output.ts         # ANSI colors, tables, agent/type formatters
    ├── git.ts            # Staleness detection via git log
    └── github.ts         # GitHub URL parsing + raw content fetch

Test plan

• ags scan discovers 23 items across Claude Code and Cursor (skills, commands, agents)
• ags scan --scope local/global and --agent/--type filters work correctly
• ags skill-cost shows context usage per agent with accurate bar charts
• ags rm removes by name and cleans up empty directories
• ags stats shows real session counts, PRs, tokens, integrations from jsonl files
• ags stats --period 7d/30d/all-time filters correctly
• ags list-agents detects installed agents
• All --json outputs are valid parseable JSON
• All <command> --help shows usage, options, and examples
• TypeScript compiles clean (tsc --noEmit)
• No hardcoded personal paths or usernames

🤖 Generated with Claude Code