feat(construct-cli): Phase 3 — general sources (git URLs) + find/use/init

Adds a sources layer: resolve a source spec (local path, git URL, or owner/repo — shallow-cloned into the XDG cache and reused), and discover skills across the common container dirs (skills/, skills/.curated/). SKILL.md frontmatter parsing powers new commands: `skill find` (browse name+description), `skill use` (print prompts without installing), `skill init` (scaffold a SKILL.md). `skill add`/`update` now accept git URLs (--refresh re-clones). Verified end-to-end cloning Spacecraft-Software/Construct. 27 tests, clippy -D warnings, reuse lint, nix build all pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

construct-cli/src/cli.rs

@@ -185,6 +185,25 @@ pub(crate) enum SkillCommand {
     )]
     Update(AddArgs),
 
+    /// Browse a source's catalogue (name + description from SKILL.md).
+    #[command(
+        visible_alias = "search",
+        after_help = "Examples:\n  construct skill find\n  construct skill find rust\n  construct skill find --source vercel-labs/skills --json"
+    )]
+    Find(FindArgs),
+
+    /// Print selected skills' prompts to stdout without installing.
+    #[command(
+        after_help = "Examples:\n  construct skill use --skills spacecraft-rust-guidelines\n  construct skill use vercel-labs/skills --skills find-skills"
+    )]
+    Use(UseArgs),
+
+    /// Scaffold a new skill directory with a SKILL.md template.
+    #[command(
+        after_help = "Examples:\n  construct skill init my-skill\n  construct skill init my-skill --dir ./skills"
+    )]
+    Init(InitArgs),
+
     /// Update the Construct flake input in a consuming flake (no rebuild).
     #[command(
         after_help = "Examples:\n  construct skill sync\n  construct skill sync --json\n  construct skill sync --flake-dir /etc/nixos --dry-run"
@@ -233,6 +252,10 @@ pub(crate) struct AddArgs {
     /// Target every known agent (not just detected ones).
     #[arg(long)]
     pub(crate) all: bool,
+
+    /// Re-clone a cached remote source before installing.
+    #[arg(long)]
+    pub(crate) refresh: bool,
 }
 
 /// Arguments for `construct skill list`.
@@ -290,6 +313,44 @@ pub(crate) struct SyncArgs {
     pub(crate) flake_dir: Option<PathBuf>,
 }
 
+/// Arguments for `construct skill find`.
+#[derive(Debug, Args)]
+pub(crate) struct FindArgs {
+    /// Filter skills whose name or description contains this query.
+    pub(crate) query: Option<String>,
+
+    /// Source to browse (local path, git URL, or owner/repo; default Construct).
+    #[arg(long, value_name = "SRC")]
+    pub(crate) source: Option<String>,
+}
+
+/// Arguments for `construct skill use`.
+#[derive(Debug, Args)]
+pub(crate) struct UseArgs {
+    /// Source (local path, git URL, or owner/repo); default the Construct clone.
+    pub(crate) source: Option<String>,
+
+    /// Skills whose prompts to print (comma-separated); default all in source.
+    #[arg(
+        short = 's',
+        long = "skills",
+        value_delimiter = ',',
+        value_name = "NAME[,NAME...]"
+    )]
+    pub(crate) skills: Vec<String>,
+}
+
+/// Arguments for `construct skill init`.
+#[derive(Debug, Args)]
+pub(crate) struct InitArgs {
+    /// Name (directory) of the new skill.
+    pub(crate) name: String,
+
+    /// Parent directory to create the skill under (default: current dir).
+    #[arg(long, value_name = "DIR")]
+    pub(crate) dir: Option<PathBuf>,
+}
+
 /// Arguments for `construct skill ship`.
 #[derive(Debug, Args)]
 pub(crate) struct ShipArgs {

construct-cli/src/commands/mod.rs

@@ -33,6 +33,9 @@ pub(crate) fn dispatch(cli: &Cli, ctx: &Context) -> Result<Option<CommandOutput>
             SkillCommand::List(args) => skill::list(ctx, args).map(Some),
             SkillCommand::Remove(args) => skill::remove(ctx, args).map(Some),
             SkillCommand::Update(args) => skill::update(ctx, args).map(Some),
+            SkillCommand::Find(args) => skill::find(ctx, args).map(Some),
+            SkillCommand::Use(args) => skill::use_prompt(ctx, args).map(Some),
+            SkillCommand::Init(args) => skill::init(ctx, args).map(Some),
             SkillCommand::Sync(args) => sync::run(ctx, args).map(Some),
             SkillCommand::Ship(args) => ship::run(ctx, args).map(Some),
         },

construct-cli/src/commands/skill.rs

@@ -1,19 +1,20 @@
 // SPDX-FileCopyrightText: 2026 Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! `construct skill add | list | remove | update` — the imperative installer's
-//! command surface. These build options from the parsed args and delegate to
-//! [`crate::install`], then wrap the structured report into a [`CommandOutput`].
+//! `construct skill add | list | remove | update | find | use | init` — the
+//! skill command surface. These build options from the parsed args and delegate
+//! to [`crate::install`] / [`crate::sources`], then wrap the result.
 
 use std::path::PathBuf;
 
-use serde_json::Value;
+use serde_json::{json, Value};
 
-use crate::cli::{AddArgs, RemoveArgs, ScopeQueryArgs};
+use crate::cli::{AddArgs, FindArgs, InitArgs, RemoveArgs, ScopeQueryArgs, UseArgs};
 use crate::context::Context;
 use crate::install::{self, plan::AddOptions, plan::Scope, InstallReport, RemoveOptions};
-use crate::output::error::AppError;
+use crate::output::error::{AppError, ErrorCode};
 use crate::output::{CommandOutput, HumanRender};
+use crate::sources::{self, skillmd};
 
 /// Map the `--global` flag to a [`Scope`].
 fn scope_of(global: bool) -> Scope {
@@ -24,20 +25,24 @@ fn scope_of(global: bool) -> Scope {
     }
 }
 
+/// Resolve the source spec, defaulting to the local Construct catalogue.
+fn source_spec(explicit: Option<&String>) -> String {
+    explicit
+        .cloned()
+        .unwrap_or_else(|| install::plan::DEFAULT_SOURCE.to_owned())
+}
+
 /// Build [`AddOptions`] from parsed args; `force` is set true for `update`.
 fn add_options(args: &AddArgs, force: bool) -> AddOptions {
-    let source = args
-        .source
-        .clone()
-        .unwrap_or_else(|| install::plan::DEFAULT_SOURCE.to_owned());
     AddOptions {
-        source: PathBuf::from(source),
+        source: source_spec(args.source.as_ref()),
         skills: args.skills.clone(),
         agents: args.agents.clone(),
         all_agents: args.all,
         scope: scope_of(args.global),
         copy: args.copy,
         force,
+        refresh: args.refresh,
     }
 }
 
@@ -71,6 +76,82 @@ pub(crate) fn remove(ctx: &Context, args: &RemoveArgs) -> Result<CommandOutput,
     Ok(report_output(&report))
 }
 
+/// `construct skill find` — browse a source's catalogue (name + description).
+pub(crate) fn find(ctx: &Context, args: &FindArgs) -> Result<CommandOutput, AppError> {
+    let root = sources::resolve_source(ctx, &source_spec(args.source.as_ref()), false)?;
+    let query = args.query.as_deref().map(str::to_lowercase);
+
+    let mut records = Vec::new();
+    let mut rows = Vec::new();
+    for skill in sources::discover(&root) {
+        let desc = skill.description.clone().unwrap_or_default();
+        if let Some(q) = &query {
+            if !format!("{} {desc}", skill.name).to_lowercase().contains(q) {
+                continue;
+            }
+        }
+        rows.push(vec![skill.name.clone(), truncate(&desc, 80)]);
+        records.push(json!({ "name": skill.name, "description": skill.description }));
+    }
+    let human = HumanRender::Table {
+        headers: vec!["SKILL".to_owned(), "DESCRIPTION".to_owned()],
+        rows,
+    };
+    Ok(CommandOutput::new(Value::Array(records), human))
+}
+
+/// `construct skill use` — print selected skills' prompts without installing.
+pub(crate) fn use_prompt(ctx: &Context, args: &UseArgs) -> Result<CommandOutput, AppError> {
+    let root = sources::resolve_source(ctx, &source_spec(args.source.as_ref()), false)?;
+    let selected = sources::select_skills(ctx, &root, &args.skills)?;
+
+    let mut records = Vec::new();
+    let mut sections = Vec::new();
+    for skill in &selected {
+        let content = skillmd::body(&skill.dir.join("SKILL.md"));
+        sections.push(format!("# {}\n\n{content}", skill.name));
+        records.push(json!({ "skill": skill.name, "content": content }));
+    }
+    let human = HumanRender::Message(sections.join("\n\n---\n\n"));
+    Ok(CommandOutput::new(Value::Array(records), human))
+}
+
+/// `construct skill init` — scaffold a new skill directory with a `SKILL.md`.
+pub(crate) fn init(ctx: &Context, args: &InitArgs) -> Result<CommandOutput, AppError> {
+    let dir = args.dir.clone().unwrap_or_else(|| PathBuf::from("."));
+    let skill_dir = dir.join(&args.name);
+    let skill_md = skill_dir.join("SKILL.md");
+
+    if skill_md.exists() {
+        return Err(AppError::new(
+            ctx,
+            ErrorCode::Conflict,
+            5,
+            format!("'{}' already exists", skill_md.display()),
+            "construct skill init <other-name>",
+        ));
+    }
+
+    let path = skill_md.display().to_string();
+    if ctx.dry_run {
+        let human = HumanRender::Message(format!("[dry-run] would create {path}"));
+        return Ok(CommandOutput::new(
+            json!({ "created": false, "path": path }),
+            human,
+        ));
+    }
+
+    std::fs::create_dir_all(&skill_dir).map_err(|e| io_error(ctx, &skill_md, &e))?;
+    std::fs::write(&skill_md, template(&args.name)).map_err(|e| io_error(ctx, &skill_md, &e))?;
+    let human = HumanRender::Message(format!("created {path}"));
+    Ok(CommandOutput::new(
+        json!({ "created": true, "path": path }),
+        human,
+    ))
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────-
+
 /// Wrap an [`InstallReport`] into machine `data` plus a human table.
 fn report_output(report: &InstallReport) -> CommandOutput {
     let rows = report
@@ -97,3 +178,30 @@ fn report_output(report: &InstallReport) -> CommandOutput {
     let data = serde_json::to_value(report).unwrap_or(Value::Null);
     CommandOutput::new(data, human)
 }
+
+/// Truncate to `n` characters, appending an ellipsis when shortened.
+fn truncate(s: &str, n: usize) -> String {
+    if s.chars().count() <= n {
+        s.to_owned()
+    } else {
+        let head: String = s.chars().take(n).collect();
+        format!("{head}…")
+    }
+}
+
+/// The house-style `SKILL.md` scaffold.
+fn template(name: &str) -> String {
+    format!(
+        "---\nname: {name}\ndescription: >\n  TODO: one paragraph (<= 1000 chars) describing what this skill does and\n  when an agent should use it.\nlicense: GPL-3.0-or-later\n---\n\n# {name}\n\nTODO: skill body.\n"
+    )
+}
+
+/// Map a filesystem error to a structured `AppError`.
+fn io_error(ctx: &Context, path: &std::path::Path, err: &std::io::Error) -> AppError {
+    AppError::general(
+        ctx,
+        ErrorCode::InternalError,
+        format!("filesystem error at '{}': {err}", path.display()),
+        "check permissions and retry",
+    )
+}

construct-cli/src/install/mod.rs

@@ -24,6 +24,7 @@ use serde::Serialize;
 use crate::context::Context;
 use crate::output::error::{AppError, ErrorCode};
 use crate::registry::{self, detect, Agent, SkillFormat};
+use crate::sources::{self, DiscoveredSkill};
 use plan::{AddOptions, Scope};
 
 /// One (agent, skill) outcome.
@@ -62,27 +63,11 @@ pub(crate) struct RemoveOptions {
 
 /// Install skills from a catalogue source into the selected agents.
 pub(crate) fn add(ctx: &Context, opts: &AddOptions) -> Result<InstallReport, AppError> {
-    let source_str = opts.source.to_string_lossy().into_owned();
-    if plan::looks_remote(&source_str) {
-        return Err(AppError::new(
-            ctx,
-            ErrorCode::FeatureUnavailable,
-            1,
-            "remote git sources are not supported yet",
-            "construct skill add /spacecraft-software/construct",
-        ));
-    }
-    let source = opts.source.canonicalize().map_err(|_| {
-        AppError::not_found(
-            ctx,
-            format!("source '{source_str}' does not exist"),
-            "construct skill add /spacecraft-software/construct",
-        )
-    })?;
-
+    // Resolve the source (local path, git URL, or owner/repo — cloned to cache).
+    let source = sources::resolve_source(ctx, &opts.source, opts.refresh)?;
     let registry = registry::all();
     let agents = plan::resolve_agents(ctx, opts, &registry)?;
-    let skills = plan::resolve_skills(ctx, &source, &opts.skills)?;
+    let skills = sources::select_skills(ctx, &source, &opts.skills)?;
     let root = plan::project_root();
 
     // Pre-flight: an explicit `--agents` + `--global` into an HM-managed dir is
@@ -110,7 +95,7 @@ pub(crate) fn add(ctx: &Context, opts: &AddOptions) -> Result<InstallReport, App
 
     let mut items = Vec::new();
     for agent in &agents {
-        place_agent(ctx, agent, &source, &skills, opts, &root, &mut items)?;
+        place_agent(ctx, agent, &skills, opts, &root, &mut items)?;
     }
 
     Ok(InstallReport {
@@ -125,8 +110,7 @@ pub(crate) fn add(ctx: &Context, opts: &AddOptions) -> Result<InstallReport, App
 fn place_agent(
     ctx: &Context,
     agent: &Agent,
-    source: &Path,
-    skills: &[String],
+    skills: &[DiscoveredSkill],
     opts: &AddOptions,
     root: &Path,
     items: &mut Vec<ItemResult>,
@@ -164,9 +148,9 @@ fn place_agent(
         for skill in skills {
             items.push(ItemResult {
                 agent: agent.id.clone(),
-                skill: skill.clone(),
+                skill: skill.name.clone(),
                 scope,
-                target: base.join(skill).display().to_string(),
+                target: base.join(&skill.name).display().to_string(),
                 action: "refused_hm_managed",
                 detail: Some("symlinked to ~/.agents/skills by Home Manager".to_owned()),
             });
@@ -179,12 +163,11 @@ fn place_agent(
     }
 
     for skill in skills {
-        let target = base.join(skill);
-        let skill_source = source.join(skill);
-        let (action, detail) = place(ctx, &skill_source, &target, opts.copy, opts.force)?;
+        let target = base.join(&skill.name);
+        let (action, detail) = place(ctx, &skill.dir, &target, opts.copy, opts.force)?;
         items.push(ItemResult {
             agent: agent.id.clone(),
-            skill: skill.clone(),
+            skill: skill.name.clone(),
             scope,
             target: target.display().to_string(),
             action,
@@ -379,7 +362,7 @@ pub(crate) fn remove(ctx: &Context, opts: &RemoveOptions) -> Result<InstallRepor
 fn push_all(
     items: &mut Vec<ItemResult>,
     agent: &Agent,
-    skills: &[String],
+    skills: &[DiscoveredSkill],
     scope: &'static str,
     target: &str,
     action: &'static str,
@@ -388,7 +371,7 @@ fn push_all(
     for skill in skills {
         items.push(ItemResult {
             agent: agent.id.clone(),
-            skill: skill.clone(),
+            skill: skill.name.clone(),
             scope,
             target: target.to_owned(),
             action,