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
• Migrate most of AGENTS.md into published skills. AGENTS.md retains only repo-local context — structure tree, packages-table update rule, CommandResult assertion convention, changeset workflow — as a thin pointer to the symlinked skills. Migration happens incrementally as each skill lands.
• This validates the consumer experience end-to-end: skill authoring, publishing, discovery, and consumption all happen within this repo

Proposed skills

All publishable packages are in scope, plus the private @gtbuchanan/test-utils — it's consumed only internally today, but dogfoods the consumer experience for repo contributors and anticipates a likely future public release.

@gtbuchanan/cli

Highest value — the primary consumer-facing package. Split into multiple topic-specific skills for better progressive disclosure.

• build-pipeline — Turborepo task graph, sync/verify, 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, plugin set (typescript-eslint, unicorn, promise, regexp, jsdoc, @stylistic, eslint-plugin-format for Prettier-formatted files, import-x, @eslint/json, pnpm, n, yml, @vitest/eslint-plugin, only-warn), suppression conventions

@gtbuchanan/eslint-plugin-markdownlint

• markdownlint — Rule configuration, markdownlint-native suppression comments (<!-- markdownlint-disable-next-line -->), interaction with eslint-plugin-format Prettier rules

@gtbuchanan/eslint-plugin-yamllint

• yamllint — YAML 1.1 safety rules (truthy, octal-values, anchors, document-start/end), interaction with eslint-plugin-yml key-sorting

@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/test-utils

• e2e-fixtures — Disposable fixture factory pattern, no logic in test lifecycle hooks, per-test instantiation, split-module structure from Split test-utils fixture.ts into focused modules #56

Scope

v1

Ship one skill end-to-end before fanning out: @gtbuchanan/cli/build-pipeline. This validates the full loop — authoring, files array + pack, skills-npm discovery in a consumer, AGENTS.md migration strategy — against the lowest-maintenance surface before committing to the remaining skills.

v2+

Remaining skills above, sequenced by consumer value. Re-evaluate the list once v1 is in consumer hands.

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
• Skills are documentation-only in v1 — no scripts/ subdirectories. CI workflow generators belong in gtb sync alongside the existing generated-file machinery (turbo.json, tsconfigs, per-package package.json scripts)
• 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