Add AI skills for consuming packages via skills-npm

[gtbuchanan]

Summary

Ship Agent Skills with published packages so AI coding assistants can discover tooling conventions via skills-npm. This enables consuming repos to get contextual guidance (config API, CLI commands, testing patterns, CI/CD setup) without manually copying instructions.

Background

skills-npm discovers skills/ directories in node_modules and symlinks them for coding agents to consume. Each skill is a directory containing a SKILL.md with YAML frontmatter (name, description) and Markdown instructions, following the Agent Skills specification.

Dogfooding

This repo currently uses AGENTS.md for agent context. Since we dogfood gtb and all config packages, we should also dogfood the skills:

• Add skills-npm as a workspace devDependency
• Wire it into the prepare script (alongside prek) so skills are symlinked on pnpm install
• Replace AGENTS.md (or most of it) with skill references — the root AGENTS.md would become a thin pointer to the symlinked skills, or be removed entirely if the agent discovers skills automatically
• This validates the consumer experience end-to-end: skill authoring, publishing, discovery, and consumption all happen within this repo

The AGENTS.md content today maps closely to the proposed skills (architecture, testing, CI/CD, conventions). Migrating it validates that skills provide equivalent or better context to agents.

Proposed skills

@gtbuchanan/cli

Highest value — the primary consumer-facing package.

• build-pipeline — Turborepo task graph, turbo:init/turbo:check, consumer script customization, pipeline conventions
• testing — Test buckets (fast/slow/e2e), Vitest tag system, coverage merging, vitest.config.ts vs vitest.config.e2e.ts
• ci-cd — Reusable workflow setup (workflow_call wrappers), CD requirements (OIDC, GitHub App, changesets), workflow inputs
• pre-commit — prek setup, hook configuration, prepare script wiring

@gtbuchanan/eslint-config

• eslint — configure() API, dual-linter relationship with oxlint, eslint-plugin-oxlint ordering, suppression conventions

@gtbuchanan/oxlint-config

• oxlint — configure() API, category defaults, @stylistic JS formatting, --disable-nested-config for hooks

@gtbuchanan/vitest-config

• vitest — configurePackage/configureGlobal/configureEndToEndPackage/configureEndToEndGlobal API, slow tag customization, custom tags, coverage setup

@gtbuchanan/tsconfig

• tsconfig — Base config extension, tsconfig.build.json convention

@gtbuchanan/oxfmt-config

• oxfmt — configure() API, scope (non-JS/TS files), ignorePatterns for @stylistic-formatted files

@gtbuchanan/markdownlint-config

• markdownlint — configure() API, markdownlint/style/prettier extension, oxfmt conflict avoidance

Implementation notes

• Each skill directory goes in skills/<name>/ within the package, with SKILL.md as the entry point
• Add "skills" to each package's files array in package.json so skills are included in the published tarball
• Keep SKILL.md body under 500 lines; split detailed reference into references/ subdirectory
• Progressive disclosure: frontmatter (name + description) is loaded at startup for matching; full body only on activation
• The description field should include trigger keywords so agents activate the skill for relevant tasks
• Consider whether @gtbuchanan/cli skills should be separate skills or a single skill with references/ for each topic
• Validate skills with skills-ref validate in CI (e.g., as a lint step or turbo task)
• Add skills-npm as a devDependency in consuming repos (not this repo) and document the setup in the README

Open questions

• [A] Should @gtbuchanan/cli have one umbrella skill or multiple topic-specific skills? Multiple skills means better progressive disclosure but more maintenance surface.
• [B] Should @gtbuchanan/test-utils (private) get a skill for internal use, or is the vitest-config skill sufficient?
• [C] Should any skills include scripts/ (e.g., a scaffold script for new consuming repos)?
• [D] What should the AGENTS.md migration path look like? Options: (a) replace entirely with skills, (b) keep a thin AGENTS.md that references skills for repo-specific context (conventions, structure) that doesn't belong in any published package, or (c) phase out gradually as skills mature.