installSkills

#!/usr/bin/env -S java --source 25

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.UncheckedIOException;
import java.lang.invoke.MethodHandles;
import java.nio.file.FileSystemException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Locale;
import java.util.function.Predicate;

String name = MethodHandles.lookup().lookupClass().getName();
String version = "2026-07-05.4";
Path defaultTargetDirectory = Path.of(System.getProperty("user.home"), ".agents", "skills");
BufferedReader input = new BufferedReader(new InputStreamReader(System.in));

void main(String... args) {
    var status = 1;
    try {
        status = run(args);
    } catch (Exception exception) {
        reportFailure("installation aborted", exception);
    }
    System.exit(status);
}

int run(String... args) throws IOException {
    var options = parse(args);
    if (options.help()) {
        usage();
        return 0;
    }
    if (options.version()) {
        IO.println(name + " " + version);
        return 0;
    }

    var sourceSkillsDirectory = sourceSkillsDirectory();
    if (!Files.isDirectory(sourceSkillsDirectory)) {
        fail(1,
                "Error: skills source directory not found: " + sourceSkillsDirectory,
                "Place this script in the repository root before running it.");
    }

    var skills = discoverSkills();
    if (skills.isEmpty()) {
        fail(1,
                "Error: no skills found under: " + sourceSkillsDirectory,
                "Each skill directory must contain a SKILL.md file.");
    }

    createTargetDirectory(options.targetDirectory());

    IO.println();
    IO.println("Skills development install");
    IO.println("Source: " + sourceSkillsDirectory);
    IO.println("Target: " + options.targetDirectory());
    IO.println("Mode:   " + options.mode());
    IO.println();

    var summary = InstallSummary.NONE;
    for (var skill : skills) {
        if (confirmInstall(skill)) {
            try {
                summary = summary.plus(InstallSummary.INSTALLED_SKILL).plus(installSkill(skill, options));
            } catch (IOException | UncheckedIOException exception) {
                reportFailure("skill '" + skill.name() + "' was not installed", exception);
                summary = summary.plus(InstallSummary.FAILED_SKILL);
            }
        } else {
            printEntry("skip", skill.name());
            summary = summary.plus(InstallSummary.SKIPPED_SKILL);
        }
        IO.println();
    }

    IO.println("Summary");
    printCount("skills installed:", summary.skillsInstalled());
    printCount("skills skipped:", summary.skillsSkipped());
    printCount("skills failed:", summary.skillsFailed());
    printCount("symlinks removed:", summary.removedLinks());
    printCount("directories removed:", summary.removedDirectories());
    printCount("files skipped:", summary.skippedFiles());
    printCount("links created:", summary.linksCreated());
    printCount("copies created:", summary.copiesCreated());
    IO.println();

    if (summary.skillsFailed() > 0) {
        System.err.println("Error: " + summary.skillsFailed() + " skill(s) failed to install.");
        return 1;
    }

    IO.println("Done.");
    return 0;
}

Path repositoryRoot() {
    var sourceFile = System.getProperty("jdk.launcher.sourcefile");
    if (sourceFile == null || sourceFile.isBlank()) {
        throw new IllegalStateException(
                "cannot resolve the repository root: run the installer as './installSkills'"
                        + " or 'java --source 25 installSkills'");
    }
    var root = Path.of(sourceFile).toAbsolutePath().normalize().getParent();
    if (root == null) {
        throw new IllegalStateException("cannot resolve the repository root from: " + sourceFile);
    }
    return root;
}

Path sourceSkillsDirectory() {
    return repositoryRoot().resolve("skills");
}

void createTargetDirectory(Path targetDirectory) throws IOException {
    try {
        Files.createDirectories(targetDirectory);
    } catch (IOException exception) {
        throw new IOException("cannot create the target skills directory: " + targetDirectory, exception);
    }
}

Options parse(String... args) {
    var targetDirectory = defaultTargetDirectory;
    var mode = InstallMode.symlink;

    for (var index = 0; index < args.length; index++) {
        switch (args[index]) {
            case "--copy" -> mode = InstallMode.copy;
            case "--target" -> {
                if (index + 1 >= args.length || args[index + 1].isBlank() || args[index + 1].startsWith("-")) {
                    failUsage("Error: --target requires a directory path.");
                }
                targetDirectory = Path.of(args[++index]).toAbsolutePath().normalize();
            }
            case "--help", "-h" -> {
                return new Options(targetDirectory, mode, true, false);
            }
            case "--version", "-version" -> {
                return new Options(targetDirectory, mode, false, true);
            }
            default -> failUsage("Error: unknown option or argument: " + args[index]);
        }
    }

    return new Options(targetDirectory, mode, false, false);
}

void failUsage(String message) {
    fail(2, message, "", usageText());
}

void fail(int exitCode, String... messages) {
    for (var message : messages) {
        System.err.println(message);
    }
    System.exit(exitCode);
}

void reportFailure(String context, Throwable throwable) {
    System.err.println("Error: " + context + ": " + describe(throwable));
}

String describe(Throwable throwable) {
    var reasons = new ArrayList<String>();
    var rootCause = throwable;
    for (var current = throwable; current != null && current != current.getCause(); current = current.getCause()) {
        rootCause = current;
        var message = current.getMessage();
        var reason = message == null || message.isBlank() ? current.getClass().getSimpleName() : message;
        if (reasons.isEmpty() || !reasons.getLast().contains(reason)) {
            reasons.add(reason);
        }
    }

    var description = new StringBuilder(String.join(" -> ", reasons))
            .append(" [")
            .append(rootCause.getClass().getSimpleName())
            .append(']');
    for (var suppressed : throwable.getSuppressed()) {
        description.append(" (also failed: ").append(describe(suppressed)).append(')');
    }
    return description.toString();
}

void printEntry(String label, Object value) {
    IO.println("  %-16s%s".formatted(label, value));
}

void printCount(String label, int count) {
    IO.println("  %-21s%s".formatted(label, count));
}

void usage() {
    IO.println(usageText());
}

String usageText() {
    return """
            Usage: %s [--copy] [--target DIR] [--help] [--version]

            Install selected local skills from the repository skills directory as symbolic links by default.
            The installer prompts before installing each discovered skill.

            Options:
              --copy        Copy the skill files instead of creating symbolic links.
              --target DIR  Destination skills directory. Default: %s
              --help        Show this help message.
              --version     Show version information.
            """.formatted(name, defaultTargetDirectory);
}

List<Skill> discoverSkills() throws IOException {
    return listEntries(sourceSkillsDirectory(), this::isSkillDirectory)
            .stream()
            .map(Skill::of)
            .toList();
}

List<Path> listEntries(Path directory, Predicate<Path> filter) throws IOException {
    try (var paths = Files.list(directory)) {
        return paths
                .filter(filter)
                .sorted(Comparator.comparing(Path::getFileName))
                .toList();
    }
}

boolean isSkillDirectory(Path path) {
    return Files.isDirectory(path) && Files.isRegularFile(path.resolve("SKILL.md"));
}

boolean confirmInstall(Skill skill) throws IOException {
    IO.println("Install skill '%s'? [y/N]".formatted(skill.name()));
    var answer = input.readLine();
    if (answer == null) {
        throw new IllegalStateException(
                "standard input closed before the prompt for skill '" + skill.name()
                        + "' was answered: run the installer interactively");
    }
    return List.of("y", "yes").contains(answer.strip().toLowerCase(Locale.ROOT));
}

InstallSummary installSkill(Skill skill, Options options) throws IOException {
    IO.println("Installing skill: " + skill.name());
    IO.println("Cleaning previous entries for " + skill.name());
    var removal = cleanPreviousEntries(options.targetDirectory(), skill);

    var creation = switch (options.mode()) {
        case symlink -> createSymbolicLink(skill, options.targetDirectory());
        case copy -> copySkill(skill, options.targetDirectory());
    };

    return removal.plus(creation);
}

InstallSummary cleanPreviousEntries(Path targetDirectory, Skill skill) throws IOException {
    var entries = listEntries(targetDirectory, skill::isPreviousEntry);
    if (entries.isEmpty()) {
        IO.println("  none");
        return InstallSummary.NONE;
    }

    var summary = InstallSummary.NONE;
    for (var entry : entries) {
        var entryName = entry.getFileName();
        if (Files.isSymbolicLink(entry)) {
            printEntry("remove symlink", entryName);
            Files.delete(entry);
            summary = summary.plus(InstallSummary.REMOVED_LINK);
        } else if (Files.isDirectory(entry)) {
            printEntry("remove dir", entryName);
            deleteDirectory(entry);
            summary = summary.plus(InstallSummary.REMOVED_DIRECTORY);
        } else {
            printEntry("skip file", entryName);
            summary = summary.plus(InstallSummary.SKIPPED_FILE);
        }
    }

    return summary;
}

InstallSummary createSymbolicLink(Skill skill, Path targetDirectory) throws IOException {
    IO.println("Creating symbolic link");
    var link = targetDirectory.resolve(skill.name());
    try {
        Files.createSymbolicLink(link, skill.path());
    } catch (UnsupportedOperationException | FileSystemException exception) {
        throw new IOException("cannot create symbolic link " + link + ": retry with --copy", exception);
    }
    printEntry("link", skill.name());
    return InstallSummary.CREATED_LINK;
}

InstallSummary copySkill(Skill skill, Path targetDirectory) throws IOException {
    IO.println("Copying skill files");
    copyDirectory(skill.path(), targetDirectory.resolve(skill.name()));
    printEntry("copy", skill.name());
    return InstallSummary.CREATED_COPY;
}

void copyDirectory(Path source, Path target) throws IOException {
    try {
        for (var path : walk(source, Comparator.naturalOrder())) {
            var relative = source.relativize(path);
            if (relative.getNameCount() > 0 && "evals".equals(relative.getName(0).toString())) {
                continue;
            }
            var destination = target.resolve(relative);
            if (Files.isDirectory(path)) {
                Files.createDirectories(destination);
            } else {
                Files.copy(path, destination);
            }
        }
    } catch (IOException | UncheckedIOException exception) {
        throw rollback(target, new IOException("cannot copy " + source + " to " + target, exception));
    }
}

IOException rollback(Path target, IOException failure) {
    try {
        if (Files.exists(target)) {
            deleteDirectory(target);
        }
    } catch (IOException cleanupFailure) {
        failure.addSuppressed(cleanupFailure);
    }
    return failure;
}

void deleteDirectory(Path directory) throws IOException {
    for (var path : walk(directory, Comparator.reverseOrder())) {
        try {
            Files.delete(path);
        } catch (IOException exception) {
            throw new IOException("cannot delete " + path, exception);
        }
    }
}

List<Path> walk(Path root, Comparator<Path> order) throws IOException {
    try (var paths = Files.walk(root)) {
        return paths.sorted(order).toList();
    }
}

record Options(Path targetDirectory, InstallMode mode, boolean help, boolean version) {
}

record Skill(String name, Path path) {

    static Skill of(Path path) {
        return new Skill(path.getFileName().toString(), path);
    }

    boolean isPreviousEntry(Path path) {
        return path.getFileName().toString().equals(name);
    }
}

record InstallSummary(
        int skillsInstalled,
        int skillsSkipped,
        int skillsFailed,
        int removedLinks,
        int removedDirectories,
        int skippedFiles,
        int linksCreated,
        int copiesCreated) {

    static final InstallSummary NONE = new InstallSummary(0, 0, 0, 0, 0, 0, 0, 0);
    static final InstallSummary INSTALLED_SKILL = new InstallSummary(1, 0, 0, 0, 0, 0, 0, 0);
    static final InstallSummary SKIPPED_SKILL = new InstallSummary(0, 1, 0, 0, 0, 0, 0, 0);
    static final InstallSummary FAILED_SKILL = new InstallSummary(0, 0, 1, 0, 0, 0, 0, 0);
    static final InstallSummary REMOVED_LINK = new InstallSummary(0, 0, 0, 1, 0, 0, 0, 0);
    static final InstallSummary REMOVED_DIRECTORY = new InstallSummary(0, 0, 0, 0, 1, 0, 0, 0);
    static final InstallSummary SKIPPED_FILE = new InstallSummary(0, 0, 0, 0, 0, 1, 0, 0);
    static final InstallSummary CREATED_LINK = new InstallSummary(0, 0, 0, 0, 0, 0, 1, 0);
    static final InstallSummary CREATED_COPY = new InstallSummary(0, 0, 0, 0, 0, 0, 0, 1);

    InstallSummary plus(InstallSummary other) {
        return new InstallSummary(
                this.skillsInstalled + other.skillsInstalled,
                this.skillsSkipped + other.skillsSkipped,
                this.skillsFailed + other.skillsFailed,
                this.removedLinks + other.removedLinks,
                this.removedDirectories + other.removedDirectories,
                this.skippedFiles + other.skippedFiles,
                this.linksCreated + other.linksCreated,
                this.copiesCreated + other.copiesCreated);
    }
}

enum InstallMode {
    symlink,
    copy
}