$ show tech-leads-club/agent-skills
This monorepo (Nx) implements a complete ecosystem for managing and distributing 'skills'—curated, structured instructions for AI coding agents. The codebase reveals a production CLI (`agent-skills`) built with Ink/React for interactive terminal UI, an MCP server (`agent-skills-mcp`) for agent-in-context skill lookup via FastMCP, a Next.js marketplace website for browsing, and a skills catalog with over 150 skill definitions across architecture, cloud, development, quality, security, and other domains. The core library (`@tech-leads-club/core`) uses a clean hexagonal architecture with port/adapter separation for file system, HTTP, environment, logging, and shell operations, enabling testability and future portability. The CLI supports interactive and non-interactive install/remove/update workflows with atomic lockfile writes, append-only audit logging, and content-hash integrity verification. The MCP server implements a progressive disclosure pattern (search → read → fetch/prepare) to minimize token usage, with registry caching and ETag revalidation. The marketplace is highly SEO-optimized with JSON-LD structured data, breadcrumbs, and static generation. Property-based tests (fast-check) for UI components and cache boundaries demonstrate strong engineering discipline. The skills catalog itself is the core product—each skill is a markdown file with YAML frontmatter, optional scripts/references, and trigger phrases, all validated by a custom validation tool and security-scanned in CI. While the architecture is solid and the codebase is actively maintained with frequent releases, some areas show drift risk: duplicate validation scripts across skills, hardcoded benchmark data in the marketplace, and tight coupling to external CDN availability for registry downloads. The cloud-deploy skill references an enormous set of Cloudflare product docs that will inevitably become outdated. Overall, this is a well-crafted, modern TypeScript monorepo that effectively solves the problem of giving AI agents reusable, safe, and discoverable instructions.
The LLM identified 4 files worth highlighting for reuse:
Exports the abstract port interfaces (FileSystemPort, HttpPort, EnvPort, LoggerPort, PackageResolverPort, PathsPort, ShellPort) that define the boundaries between core business logic and infrastructure. These interfaces allow all core services (installer, registry, lockfile, audit) to depend only on abstractions, not on Node.js specifics. Together with the adapter implementations in libs/core/src/lib/adapters/ and the createNodeAdapters() factory, this forms a clean, testable port/adapter layer that can be extracted as a standalone Dependency Injection utility for any Node.js application.
Implements the core install/remove skill logic with atomic lockfile updates using a temp-file-then-rename pattern with automatic backup creation before overwrite. Handles symlink fallback, cross-agent configuration updates, and integrates with the audit log and content-hash verification. The lockfile schema is validated with Zod and supports version migration. This service demonstrates a robust, crash-safe file-based state management pattern reusable in any tool that needs safe, idempotent installation of packaged assets.
Provides an append-only JSONL audit log with timestamped entries, best-effort writes (silently tolerates filesystem errors), and reverse-order reading with limit. This is a lightweight, production-tested pattern for recording an immutable history of operations (installs, removals, updates) without introducing a database dependency. The same pattern can be extracted for any CLI or background job that needs a simple, durable audit trail.
A runnable validation tool that performs 20+ checks per skill definition (frontmatter, naming conventions, description triggers, negative scope, metadata integrity). It operates in batch mode, produces structured error reports with severity levels, and integrates with CI. This is a reusable pattern for any content-based registry or catalog that needs automated quality gates, with the validation logic easily adaptable to different schema and rule sets.