feat(skills): add skills infrastructure using Claude Code plugin system

[claude]

Summary

This PR adds a new skills infrastructure to ai-toolkit that aligns with Claude Code's plugin system, making it:

1. As easy to add skills as it is to add commands - Skills use the same markdown-based pattern with YAML frontmatter
2. Compatible with Claude Code's plugin interface - Skills are installed in the plugin-compatible directory structure (skills/<skill-name>/SKILL.md)
3. Pick-and-choose installation - Users can select specific skills to install via the init generator

Key Changes

New Package: @ai-toolkit/skills-agnostic

• Created packages/skills/agnostic/ directory with standard Nx structure
• Added example codebase-exploration skill demonstrating the pattern
• Skills use name and description in frontmatter (same as agents)

New Generator: add-skill

• Creates new skills with templates similar to add-command and add-agent
• Supports creating new skill packages or adding to existing ones
• Auto-generates package index after skill creation

New Generator: init-plugin

• Creates Claude Code plugin structure with .claude-plugin/plugin.json manifest
• Supports including skills, commands, and agents directories
• Generates README with installation and development instructions

Updated: init Generator

• Added skills installation support parallel to commands/agents
• Default mode installs codebase-exploration skill
• Custom mode allows selecting specific skills
• Skills installed in ~/.claude/skills/<skill-name>/SKILL.md format

Infrastructure Updates

• Extended generate-index utility to support SkillName type
• Added skills package paths to tsconfig.base.json and nx.json
• Extended prompt-utils context with skills-related properties

How Skills Differ from Commands/Agents

Aspect	Commands	Agents	Skills
Invocation	User-invoked via /command	Invoked by commands/other agents	Model-invoked autonomously
Trigger	Explicit slash command	Delegation from commands	Claude decides based on task context
Format	commands/<name>.md	agents/<name>.md	skills/<name>/SKILL.md

Testing

# Build affected projects
npx nx affected --target=build --base=next

# Run typecheck
npx nx affected --target=typecheck --base=next

# Run lint
npx nx affected --target=lint --base=next

Example Usage

# Add a new skill
npx nx generate @uniswap/ai-toolkit-nx-claude:add-skill

# Create a Claude Code plugin
npx nx generate @uniswap/ai-toolkit-nx-claude:init-plugin

# Install skills via init (includes skills now)
npx nx generate @uniswap/ai-toolkit-nx-claude:init

Linear Issue

Closes: https://linear.app/uniswap/issue/DEV-157/update-ai-toolkit-skills-infrastructure-to-use-claude-code-plugin

Autonomous implementation using claude-opus-4-5-20251101

---

✨ Claude-Generated Content

Summary

Adds skills infrastructure to ai-toolkit that aligns with Claude Code's plugin system. Skills are model-invoked capabilities that Claude autonomously decides when to use based on task context, complementing user-invoked commands and delegated agents.

Changes

• New package @ai-toolkit/skills-agnostic: Created skills package with standard Nx structure and example codebase-exploration skill
• New add-skill generator: Creates new skills with templates similar to add-command and add-agent, supporting both existing packages and new package creation
• New init-plugin generator: Creates Claude Code plugin structure with .claude-plugin/plugin.json manifest and optional skills/commands/agents directories
• Updated init generator: Added skills installation support parallel to commands/agents with default and custom selection modes
• Extended generate-index utility: Added support for SkillName type alongside existing Agent and CommandName types
• Infrastructure updates: Added skills package paths to tsconfig.base.json and nx.json, extended prompt-utils context with skills-related properties

Technical Details

Aspect	Commands	Agents	Skills
Invocation	User-invoked via /command	Delegated by commands/agents	Model-invoked autonomously
Format	commands/<name>.md	agents/<name>.md	skills/<name>/SKILL.md
Skills use the same markdown-based pattern with YAML frontmatter (name, description, allowed-tools) making them consistent with the existing commands and agents structure.

Notes

• Skills are installed in ~/.claude/skills/<skill-name>/SKILL.md format for Claude Code plugin compatibility
• The codebase-exploration skill is included by default in standard installations
• Plugin structure follows Claude Code's plugin specification with manifest in .claude-plugin/plugin.json

[linear]

DEV-157 Update ai-toolkit skills infrastructure to use Claude Code plugin system

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
ai-toolkit-slack-oauth-backend	Ready	Preview, Comment	Dec 12, 2025 11:48pm

[github-actions]

👋 Hi!

I'm Claude, an AI assistant here to help with code reviews and answer questions about your PR. You can tag me anytime with @claude followed by your request.

💡 Tip: Ask me to explain code, suggest improvements, review specific changes, or help with AI Toolkit development patterns.

This repository contains the AI Toolkit - standardized, one-shot setup for Claude Code AI workflows. When working on changes, make sure to follow the Nx monorepo patterns and update relevant CLAUDE.md files.

Learn how to use Claude in ai-toolkit PRs

[github-actions]

🤖 Claude Code Review

✅ Review complete

Skills Infrastructure Review

This PR adds a comprehensive skills infrastructure to the AI Toolkit, introducing the concept of "model-invoked capabilities" that Claude autonomously decides when to use. The implementation follows established patterns from the existing commands and agents infrastructure.

Summary

The PR introduces:

1. New add-skill generator - Creates Claude Code skills with support for dynamic package discovery and creation
2. New init-plugin generator - Scaffolds Claude Code plugin structures for distribution
3. Skills package (@ai-toolkit/skills-agnostic) - Initial skills package with a codebase-exploration skill
4. Init generator updates - Integrates skills into the existing installation flow
5. Generate-index utility updates - Extends to support skill index generation

Architecture Assessment

The implementation correctly follows the existing patterns:

• Skills use the same frontmatter-based markdown format as commands/agents
• The generate-index utility was properly extended for the SkillName type
• The init generator dynamically loads skills to avoid hard compile-time dependency
• Nx workspace integration is properly configured with build targets and dependencies

Issues Found

1. Schema Violation - createNewPackage has both default and prompt-when

Per the repository's CLAUDE.md guidelines:

❌ DO NOT include a default value if the field should be optional
Only properties without x-prompt and without defaults will properly respect prompt-when

In add-skill/schema.json, the createNewPackage property has both default: false and prompt-when, which can interfere with conditional prompting logic.

2. Unused runGenerateIndexTask tree parameter

In add-skill/generator.ts:302, the runGenerateIndexTask function captures tree as a parameter but the inner function only uses tree.root. The outer tree is already in closure scope, making this parameter redundant and slightly confusing.

Observations (Non-blocking)

1. Dynamic require for skills: The getSkills() function in init/generator.ts uses dynamic require() which is appropriate for optional dependencies, but the ESLint disable comment should have a more specific reason documented.

2. Plugin directory structure: The init-plugin generator creates a .claude-plugin/plugin.json manifest, which aligns well with typical plugin conventions. The documentation references https://docs.anthropic.com/claude-code/plugins which I cannot verify exists.

3. Skill installation format: Skills are installed as skills/<skill-name>/SKILL.md for Claude Code plugin compatibility - this is a deliberate design choice well documented in comments.

Positive Aspects

• Clean separation between skills (model-invoked) and commands (user-invoked)
• Good use of existing generateIndex utility with minimal changes
• Proper Nx workspace configuration including build dependencies
• Well-structured skill markdown template with TODO placeholders
• The codebase-exploration skill is a good first example with practical guidance

Files Reviewed

All significant source files in the diff were reviewed. The jest.config.ts formatting changes appear to be auto-formatting only.

---

_{💡 Want a fresh review? Add a comment containing @request-claude-review to trigger a new review at any time.}

[github-actions]

📋 Review verdict: COMMENT

👆 The main review comment above is the source of truth for this PR review. It is automatically updated on each review cycle, so always refer to it for the most current feedback.

This formal review submission is for the verdict only. 2 inline comment(s) are attached below.

[github-actions]

Per the repository's CLAUDE.md guidelines for Nx Generator Schema Configuration:

❌ DO NOT include a default value if the field should be optional
Only properties without x-prompt and without defaults will properly respect prompt-when

This createNewPackage field has both default: false and prompt-when, which can interfere with the conditional prompting logic in prompt-utils. The field should likely not have a default value since it's conditionally prompted.

Suggested change

	"default": false,
	"createNewPackage": {
	"type": "boolean",
	"description": "Create a new package for this skill",
	"prompt-message": "➕ Would you like to create a new package instead?",
	"prompt-type": "confirm",
	"prompt-when": "package === '__create_new__'"
	},

[github-actions]

The tree parameter here is unused - the inner function only accesses tree.root which is already available through closure. This parameter adds confusion since the outer tree is captured in the closure anyway.

Consider removing the parameter for clarity:

const runGenerateIndexTask = () => {
  return () => {
    // tree.root is already accessible via closure