stack-analyzer

name	stack-analyzer
description	Analyze project stack and recommend skills. Auto-detects frameworks, activates generic ai-dev-kit skills, and optionally scaffolds project-specific skills in the target repo.

Stack Analyzer Skill

A meta-skill that analyzes a project's technology stack and recommends or scaffolds appropriate skills for AI-assisted development. This skill runs automatically during /ai-dev-kit:setup but can also be invoked manually.

Design Principles

Plugin Isolation

Leave No Trace: The ai-dev-kit plugin must be completely removable without leaving artifacts. This skill enforces:

Component	Location	On Uninstall
Generic skills	plugins/ai-dev-kit/skills/	Removed with plugin
Project-specific skills	Target repo .claude/skills/	User's choice
Generated manifest	.claude/skills/_generated.json	User's choice

Generality

All ai-dev-kit skills are framework-generic, not tailored to any specific codebase:

Pattern	Correct	Wrong
BAML skill	Universal BAML patterns	CodeGraph-DE-specific DTOs
Supabase skill	General best practices	Book-Vetting-specific queries
Schema alignment	Works with any ORM	Assumes specific models

Variables

Variable	Default	Description
AUTO_ACTIVATE	false	Automatically activate recommended generic skills
SCAFFOLD_SKILLS	false	Scaffold project-specific skills in target repo
OUTPUT_REPORT	true	Generate recommendation report
MANIFEST_PATH	.claude/skills/_generated.json	Path for generated manifest

Instructions

MANDATORY - Follow the Workflow steps below in order.

1. Run library-detection skill to get project stack
2. Match detected stack against skill recommendations
3. Report recommended generic skills
4. Optionally scaffold project-specific skills
5. Update generated manifest if skills were created

Red Flags - STOP and Reconsider

If you're about to:

• Create a skill tailored to a specific codebase (vs generic pattern)
• Put project-specific skills in the plugin directory
• Skip the generated manifest update
• Recommend skills for undetected technologies

STOP -> Verify the detection results -> Use generic patterns -> Then proceed

Workflow

1. Detect Project Stack

Invoke the library-detection skill first:

Read and execute plugins/ai-dev-kit/skills/library-detection/SKILL.md

This returns:
- languages (typescript, python, etc.)
- frameworks (react, fastapi, etc.)
- test_frameworks (vitest, pytest, etc.)
- databases (postgresql, sqlite, etc.)
- build_tools (vite, uv, etc.)

2. Match Against Skill Recommendations

Load recommendations from ./config/recommendations.yaml and match:

For each detected technology:
  IF matches skill activation rule:
    Add to recommended_skills list
  IF matches scaffold template rule:
    Add to scaffold_candidates list

3. Generate Report

Create a recommendation report:

# Stack Analysis Report

## Detected Stack
- **Languages**: TypeScript, Python
- **Frameworks**: Next.js, FastAPI
- **Database**: PostgreSQL (via Supabase)
- **Test**: Vitest, Pytest
- **AI/ML**: BAML

## Recommended Generic Skills (in plugin)

| Skill | Reason | Status |
|-------|--------|--------|
| baml-integration | BAML detected in baml_src/ | Active |
| supabase-patterns | Supabase dependency found | Active |
| schema-alignment | SQLAlchemy detected | Active |

## Project-Specific Skills (scaffoldable)

| Template | Trigger | Output |
|----------|---------|--------|
| project-research | 3 research subagents found | .claude/skills/{project}-research/ |
| project-domain | Models in src/models/ | .claude/skills/{project}-domain/ |

4. Scaffold Project-Specific Skills (if enabled)

For each scaffold candidate:

# 1. Copy template to target repo
cp -r ./templates/{template}/ ${TARGET_REPO}/.claude/skills/{project}-{template}/

# 2. Add generation header to SKILL.md
echo "<!-- Generated by ai-dev-kit:recommend-skills on $(date) -->" | \
  cat - ./templates/{template}/SKILL.md > temp && mv temp SKILL.md

# 3. Customize with project name
sed -i "s/{project}/${PROJECT_NAME}/g" SKILL.md

5. Update Generated Manifest

Create or update .claude/skills/_generated.json:

{
  "generated_by": "ai-dev-kit:recommend-skills",
  "generated_at": "2025-12-24T10:00:00Z",
  "plugin_version": "1.0.0",
  "skills_created": [
    {
      "path": ".claude/skills/book-vetting-research/",
      "template": "project-research",
      "created_at": "2025-12-24T10:00:00Z"
    }
  ],
  "docs_created": [
    "ai-docs/libraries/baml/"
  ],
  "cleanup_instructions": "These files were generated by ai-dev-kit. You may delete them after uninstalling the plugin."
}

Skill Recommendation Rules

Generic Skills (Activate)

Skill	Detection Criteria
baml-integration	baml_src/**/*.baml exists OR baml-py/baml dependency
supabase-patterns	supabase dependency OR supabase/migrations/ exists
schema-alignment	sqlalchemy/prisma/django/alembic detected
treesitter-patterns	tree-sitter/tree_sitter dependency
security-audit	Always recommended for production codebases

Project-Specific Skills (Scaffold)

Template	Detection Criteria
project-research	.claude/commands/**/research/** OR subagent.*research pattern
project-domain	src/models/** OR services/domain/** exists
project-testing	Custom test patterns beyond standard frameworks

Templates

project-research

For projects with research-oriented subagents:

templates/project-research/
├── SKILL.md          # Customized research patterns
├── cookbook/
│   └── research-workflow.md
└── reference/
    └── source-types.md

project-domain

For projects with rich domain models:

templates/project-domain/
├── SKILL.md          # Domain vocabulary and patterns
├── cookbook/
│   └── entity-relationships.md
└── reference/
    └── domain-glossary.md

project-testing

For projects with custom testing requirements:

templates/project-testing/
├── SKILL.md          # Custom test patterns
├── cookbook/
│   └── test-fixtures.md
└── reference/
    └── coverage-requirements.md

Integration

With /ai-dev-kit:setup

Automatically runs during brownfield setup:

1. User runs: /ai-dev-kit:setup
2. Setup invokes: stack-analyzer skill
3. Stack analyzer:
   - Detects stack
   - Displays recommendations
   - Prompts: "Activate recommended skills? [y/N]"
   - If yes: marks skills as active
   - Prompts: "Scaffold project-specific skills? [y/N]"
   - If yes: creates skills in target repo
4. Setup continues with remaining steps

With /ai-dev-kit:recommend-skills

Direct invocation:

# Report only (no changes)
/ai-dev-kit:recommend-skills

# Auto-activate generic skills
/ai-dev-kit:recommend-skills --auto-activate

# Scaffold project-specific skills
/ai-dev-kit:recommend-skills --scaffold

# All options
/ai-dev-kit:recommend-skills --auto-activate --scaffold --output=report.md

Output Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "detected_stack": {
      "type": "object",
      "description": "Output from library-detection skill"
    },
    "recommended_skills": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "skill": {"type": "string"},
          "reason": {"type": "string"},
          "status": {"enum": ["recommended", "active", "not_applicable"]}
        }
      }
    },
    "scaffold_candidates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "template": {"type": "string"},
          "trigger": {"type": "string"},
          "output_path": {"type": "string"},
          "created": {"type": "boolean"}
        }
      }
    },
    "manifest_updated": {"type": "boolean"},
    "manifest_path": {"type": "string"}
  }
}

Cleanup on Uninstall

When ai-dev-kit plugin is removed, inform user:

## ai-dev-kit Uninstall Notice

The following files were generated by ai-dev-kit and persist after uninstall:

**Project-specific skills:**
- .claude/skills/book-vetting-research/
- .claude/skills/book-vetting-domain/

**Documentation:**
- ai-docs/libraries/baml/
- ai-docs/libraries/supabase/

See .claude/skills/_generated.json for full list.

These files are safe to delete if no longer needed.