@needle-tools/engine/plugins/vite/ai.js

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
import { dirname, join } from "path";
import { fileURLToPath } from "url";
import { needleLog } from "./logging.js";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const pluginName = "needle-ai";

/**
 * Needle Engine AI skill installer.
 *
 * Writes a Needle Engine skill to `<dir>/skills/needle-engine/SKILL.md`
 * for each supported AI agent directory (`.claude/`, `.github/`, `.agents/`).
 * Both Claude Code and GitHub Copilot auto-load skills based on their
 * description frontmatter, so the AI agent will automatically have Needle
 * Engine context when working in the project.
 *
 * The skill is only written if at least one of the supported directories
 * already exists in the project root (i.e. the developer is already using
 * an AI coding agent).
 * Old skill files are always overwritten so the skill stays up to date with
 * the engine version.
 *
 * @param {"build" | "serve"} command
 * @param {{} | undefined | null} config
 * @param {import('../types/index.js').userSettings} userSettings
 * @returns {import('vite').Plugin | null}
 */
export function needleAI(command, config, userSettings) {
    return {
        name: pluginName,
        enforce: "pre",
        buildStart() {
            installClaudeSkill();
        },
        configureServer() {
            installClaudeSkill();
        },
    };
}

function writeSkill(claudeDir) {
    const skillDir = join(claudeDir, "skills", "needle-engine");
    if (!existsSync(skillDir)) {
        mkdirSync(skillDir, { recursive: true });
    }
    const skillPath = join(skillDir, "SKILL.md");
    const templatePath = join(__dirname, "../../SKILL.md");
    const content = readFileSync(templatePath, "utf8");
    writeFileSync(skillPath, content, "utf8");
    return skillPath;
}

function installClaudeSkill() {
    const cwd = process.cwd();
    const dirs = [".claude", ".github", ".agents"].map(d => join(cwd, d)).filter(d => existsSync(d));
    if (dirs.length === 0) return; // only install if developer uses an AI coding agent

    for (const dir of dirs) {
        const path = writeSkill(dir);
        if (path) needleLog(`[${pluginName}] Installed Needle Engine skill → ${path}`);
    }
}