feat(cli): add install-skills command

src/main/java/io/flamingock/cli/executor/FlamingockExecutorCli.java

@@ -17,6 +17,7 @@
 
 import io.flamingock.cli.executor.command.AuditCommand;
 import io.flamingock.cli.executor.command.ExecuteCommand;
+import io.flamingock.cli.executor.command.InstallSkillsCommand;
 import io.flamingock.cli.executor.command.IssueCommand;
 import io.flamingock.cli.executor.handler.ExecutorExceptionHandler;
 import io.flamingock.cli.executor.util.VersionProvider;
@@ -45,6 +46,7 @@
                 "",
                 "@|bold Examples:|@",
                 "  flamingock execute apply --jar ./app.jar",
+                "  flamingock install-skills",
                 "  flamingock audit list --jar ./app.jar",
                 "  flamingock audit fix --jar ./app.jar -c my-change-id -r APPLIED",
                 "  flamingock issue list --jar ./app.jar",
@@ -59,7 +61,7 @@
                 "",
                 "For detailed help on any command, use: flamingock <command> --help"
         },
-        subcommands = {ExecuteCommand.class, AuditCommand.class, IssueCommand.class},
+        subcommands = {ExecuteCommand.class, AuditCommand.class, IssueCommand.class, InstallSkillsCommand.class},
         mixinStandardHelpOptions = true,
         versionProvider = VersionProvider.class
 )

src/main/java/io/flamingock/cli/executor/command/InstallSkillsCommand.java

@@ -0,0 +1,91 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.cli.executor.command;
+
+import io.flamingock.cli.executor.output.ConsoleFormatter;
+import io.flamingock.cli.executor.skills.SkillsInstallationTarget;
+import io.flamingock.cli.executor.skills.SkillsInstallationPipeline;
+import io.flamingock.cli.executor.skills.SkillsInstallationResult;
+import io.flamingock.cli.executor.skills.SkillsInstallationTargetResolver;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.concurrent.Callable;
+
+/**
+ * Installs the official Flamingock AI skills into the current project.
+ */
+@Command(
+        name = "install-skills",
+        description = "Install official Flamingock AI skills into the current project",
+        mixinStandardHelpOptions = true
+)
+public class InstallSkillsCommand implements Callable<Integer> {
+
+    @Option(names = {"-g", "--global"}, description = "Install skills globally (not implemented yet)")
+    private boolean global;
+
+    private final SkillsInstallationTargetResolver targetResolver;
+    private final SkillsInstallationPipeline pipeline;
+    private final Path workingDirectory;
+
+    /**
+     * Creates a command with the default production collaborators.
+     */
+    public InstallSkillsCommand() {
+        this(new SkillsInstallationTargetResolver(), new SkillsInstallationPipeline(), Path.of(""));
+    }
+
+    InstallSkillsCommand(
+            SkillsInstallationTargetResolver targetResolver,
+            SkillsInstallationPipeline pipeline,
+            Path workingDirectory
+    ) {
+        this.targetResolver = targetResolver;
+        this.pipeline = pipeline;
+        this.workingDirectory = workingDirectory;
+    }
+
+    /**
+     * Executes the install-skills command.
+     *
+     * @return process exit code
+     */
+    @Override
+    public Integer call() {
+        try {
+            List<SkillsInstallationTarget> targets = targetResolver.resolveTargets(workingDirectory.toAbsolutePath().normalize(), global);
+            SkillsInstallationResult result = pipeline.install(targets);
+            ConsoleFormatter.printInfo(buildSuccessMessage(result));
+            return 0;
+        } catch (IllegalStateException e) {
+            ConsoleFormatter.printError(e.getMessage());
+            return 1;
+        }
+    }
+
+    private String buildSuccessMessage(SkillsInstallationResult result) {
+        if (result.targets().size() == 1) {
+            return "Installed " + result.installedSkills().size()
+                    + " Flamingock skill(s) into " + result.destinationSkillsDir();
+        }
+
+        return "Installed " + result.installedSkills().size() + " Flamingock skill(s) into "
+                + result.targets().size() + " destinations.";
+    }
+}

src/main/java/io/flamingock/cli/executor/skills/SkillsInstallationPipeline.java

@@ -0,0 +1,139 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.cli.executor.skills;
+
+import io.flamingock.cli.executor.util.archive.ZipArchiveExtractor;
+import io.flamingock.cli.executor.util.filesystem.DirectoryLister;
+import io.flamingock.cli.executor.util.filesystem.DirectoryReplacer;
+import io.flamingock.cli.executor.util.filesystem.FileSystemUtils;
+import io.flamingock.cli.executor.util.filesystem.TemporaryDirectoryFactory;
+import io.flamingock.cli.executor.util.http.HttpFileDownloader;
+
+import java.io.IOException;
+import java.net.URI;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Consumer;
+import java.util.function.Supplier;
+
+/**
+ * Executes the shared staged pipeline that installs official Flamingock skills.
+ */
+public class SkillsInstallationPipeline {
+
+    private static final URI OFFICIAL_SKILLS_ARCHIVE_URI =
+            URI.create("https://github.com/flamingock/flamingock-skills/archive/refs/heads/release.zip");
+    private static final String ARCHIVE_FILE_NAME = "flamingock-skills.zip";
+    private static final String EXTRACTION_DIRECTORY_NAME = "extracted";
+    private static final String SKILL_DIRECTORY_PREFIX = "flamingock-";
+    private static final String TEMP_DIRECTORY_PREFIX = "flamingock-skills-";
+    private static final String DOWNLOAD_LABEL = "official Flamingock skills";
+    private static final String ARCHIVE_DESCRIPTION = "skills archive";
+    private static final String USER_AGENT = "Flamingock CLI/1.0 install-skills";
+
+    private final HttpFileDownloader downloader;
+    private final ZipArchiveExtractor extractor;
+    private final DirectoryLister directoryLister;
+    private final DirectoryReplacer replacer;
+    private final Supplier<Path> workspaceSupplier;
+    private final Consumer<Path> cleanup;
+
+    public SkillsInstallationPipeline() {
+        this(new HttpFileDownloader(),
+                new ZipArchiveExtractor(),
+                new DirectoryLister(),
+                new DirectoryReplacer(),
+                () -> TemporaryDirectoryFactory.create(TEMP_DIRECTORY_PREFIX, "skill installation"),
+                FileSystemUtils::deleteRecursively);
+    }
+
+    SkillsInstallationPipeline(
+            HttpFileDownloader downloader,
+            ZipArchiveExtractor extractor,
+            DirectoryLister directoryLister,
+            DirectoryReplacer replacer,
+            Supplier<Path> workspaceSupplier,
+            Consumer<Path> cleanup
+    ) {
+        this.downloader = downloader;
+        this.extractor = extractor;
+        this.directoryLister = directoryLister;
+        this.replacer = replacer;
+        this.workspaceSupplier = workspaceSupplier;
+        this.cleanup = cleanup;
+    }
+
+    /**
+     * Runs the download, extract, enumerate, replace, and cleanup stages.
+     *
+     * @param targets resolved installation targets
+     * @return installation result summary
+     */
+    public SkillsInstallationResult install(List<SkillsInstallationTarget> targets) {
+        Objects.requireNonNull(targets, "targets must not be null");
+        if (targets.isEmpty()) {
+            throw new IllegalStateException("No skills installation targets were resolved. Choose a destination and retry.");
+        }
+
+        Path workspace = workspaceSupplier.get();
+        RuntimeException installationFailure = null;
+        try {
+            Path archive = downloader.downloadTo(
+                    workspace,
+                    OFFICIAL_SKILLS_ARCHIVE_URI,
+                    ARCHIVE_FILE_NAME,
+                    USER_AGENT,
+                    DOWNLOAD_LABEL
+            );
+            Path snapshotRoot = extractor.extractSingleRootDirectory(
+                    archive,
+                    workspace,
+                    EXTRACTION_DIRECTORY_NAME,
+                    ARCHIVE_DESCRIPTION
+            );
+            List<Path> skillDirectories = directoryLister.listDirectories(
+                    snapshotRoot,
+                    path -> path.getFileName().toString().startsWith(SKILL_DIRECTORY_PREFIX)
+            );
+            List<String> installedSkills = new ArrayList<>();
+            for (Path skillDirectory : skillDirectories) {
+                installedSkills.add(skillDirectory.getFileName().toString());
+            }
+            for (SkillsInstallationTarget target : targets) {
+                for (Path skillDirectory : skillDirectories) {
+                    Path destinationSkillDirectory = target.destinationSkillsDir().resolve(skillDirectory.getFileName().toString());
+                    replacer.replaceDirectory(skillDirectory, destinationSkillDirectory);
+                }
+            }
+            return new SkillsInstallationResult(targets, installedSkills);
+        } catch (IOException e) {
+            installationFailure = new IllegalStateException("Failed to install Flamingock skills: " + e.getMessage(), e);
+            throw installationFailure;
+        } finally {
+            try {
+                cleanup.accept(workspace);
+            } catch (RuntimeException cleanupFailure) {
+                if (installationFailure != null) {
+                    installationFailure.addSuppressed(cleanupFailure);
+                } else {
+                    throw cleanupFailure;
+                }
+            }
+        }
+    }
+}

src/main/java/io/flamingock/cli/executor/skills/SkillsInstallationResult.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.cli.executor.skills;
+
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * Summary of a completed skills installation.
+ *
+ * @param targets installation targets that received the installed skills
+ * @param installedSkills installed official skill folder names
+ */
+public record SkillsInstallationResult(List<SkillsInstallationTarget> targets, List<String> installedSkills) {
+
+    public SkillsInstallationResult {
+        targets = List.copyOf(targets);
+        installedSkills = List.copyOf(installedSkills);
+    }
+
+    /**
+     * Returns the single destination directory when the installation resolved to one target.
+     *
+     * @return single destination directory
+     */
+    public Path destinationSkillsDir() {
+        if (targets.size() != 1) {
+            throw new IllegalStateException("Installation resolved to " + targets.size()
+                    + " targets; destinationSkillsDir() is only available for single-target installs.");
+        }
+        return targets.get(0).destinationSkillsDir();
+    }
+}

src/main/java/io/flamingock/cli/executor/skills/SkillsInstallationTarget.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2026 Flamingock (https://www.flamingock.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.flamingock.cli.executor.skills;
+
+import java.nio.file.Path;
+import java.util.Objects;
+
+/**
+ * Resolved destination for a skills installation run.
+ *
+ * @param identifier stable identifier for the target
+ * @param destinationSkillsDir destination directory that will receive the skills
+ */
+public record SkillsInstallationTarget(String identifier, Path destinationSkillsDir) {
+
+    public SkillsInstallationTarget {
+        identifier = Objects.requireNonNull(identifier, "identifier must not be null");
+        destinationSkillsDir = Objects.requireNonNull(destinationSkillsDir, "destinationSkillsDir must not be null");
+    }
+
+    /**
+     * Creates the current project-local installation target.
+     *
+     * @param destinationSkillsDir local destination directory
+     * @return local installation target
+     */
+    public static SkillsInstallationTarget local(Path destinationSkillsDir) {
+        return new SkillsInstallationTarget("local", destinationSkillsDir);
+    }
+}