Development Guide

May 29, 2026 · View on GitHub

Prerequisites

Node.js >= 18.0.0 (with npm >= 9)
Git
pre-commit (optional, for git hooks)

Setup

git clone https://github.com/luongnv89/agent-skill-manager.git
cd agent-skill-manager
npm install

Running

npm start        # Launch the TUI
npm run dev          # Same as start (alias)

To test CLI commands during development:

npm run bin/agent-skill-manager.ts list
npm run bin/agent-skill-manager.ts search "my-skill"
npm run bin/agent-skill-manager.ts audit --json
npm run bin/agent-skill-manager.ts --help

Testing

npm test             # Run all tests
npm run typecheck    # Type-check without emitting

Test files are co-located with source files using the *.test.ts convention:

Test File	Coverage
`src/cli.test.ts`	Argument parsing, command dispatch
`src/config.test.ts`	Config loading, merging, saving
`src/scanner.test.ts`	Directory scanning, filtering, sorting
`src/auditor.test.ts`	Duplicate detection, instance ranking
`src/uninstaller.test.ts`	Removal plan building, file cleanup
`src/formatter.test.ts`	Table, detail, and JSON formatting
`src/utils/frontmatter.test.ts`	YAML frontmatter parsing

Pre-commit Hooks

The project uses pre-commit with:

trailing-whitespace — removes trailing whitespace
end-of-file-fixer — ensures files end with a newline
check-yaml / check-json — validates config files
check-added-large-files — prevents accidental large file commits
prettier — auto-formats TS, JS, JSON, CSS, and MD files
typecheck — runs tsc --noEmit on staged TypeScript files

Install hooks locally:

pre-commit install

Debugging

Since this is a TUI application, standard console.log will interfere with the terminal UI. For debugging:

Write to a log file: fs.writeFileSync("/tmp/sm-debug.log", JSON.stringify(data))
Run tests to isolate logic from the TUI layer

Use CLI commands to test core logic without launching the TUI:

npm run bin/agent-skill-manager.ts list --json
npm run bin/agent-skill-manager.ts audit --json

Use the --help flag to verify CLI plumbing without launching the TUI

Project Layout

See ARCHITECTURE.md for the full component breakdown and data flow diagrams.