From 6a6a4e5eec4fb15981933dbff92870333f3f239d Mon Sep 17 00:00:00 2001 From: oritwoen <18102267+oritwoen@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:22:22 +0100 Subject: [PATCH] feat(cli): add --limit to search --- README.md | 4 ++ crates/skilld-command/src/lib.rs | 32 ++++++++-- crates/skilld-command/tests/output.rs | 72 +++++++++++++++++++++- crates/skilld-command/tests/v2_commands.rs | 2 +- crates/skilld-native/src/main.rs | 2 +- skills/skilld/SKILL.md | 3 + 6 files changed, 106 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 856c4ce6..cd4e6d4c 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,10 @@ npx skilld search vue npx skilld trending ``` +Search prints up to 20 Skills, which can be a lot to scan. +Ask for fewer with `npx skilld search vue --limit 5`. +The limit goes from 1 to 50. + Every Skill page credits its author and links the source file on GitHub. [Curators](https://skilld.dev/community) publish collections of the Skills they use. diff --git a/crates/skilld-command/src/lib.rs b/crates/skilld-command/src/lib.rs index 43f839db..5f829b3c 100644 --- a/crates/skilld-command/src/lib.rs +++ b/crates/skilld-command/src/lib.rs @@ -69,6 +69,17 @@ use output::{ /// that answers in JSON; a test keeps it in step with `supports_json`. const JSON_COMMANDS_HELP: &str = "Agents: add --json to doctor, sync, search, run, update --check, view with a registry ref,\nbrowse, trending, tracks, index, curators, account, like, unlike, likes, watch,\nunwatch, watches, changes, stars, collection, and tokens. Read data when _tag is Success.\nOther commands answer in text. Add --plain to them for stable text."; +/// How many Skills `skilld search` asks for without `--limit`. +const DEFAULT_SEARCH_LIMIT: u8 = 20; + +/// Refuses a `--limit` skilld.dev would reject, before any request. +fn search_limit(value: &str) -> Result { + match value.parse() { + Ok(limit @ 1..=50) => Ok(limit), + _ => Err("give a number from 1 to 50"), + } +} + const DIRECT_SOURCE_GUIDANCE: &str = "--direct requires a github:OWNER/REPOSITORY/SKILL_PATH source or a GitHub tree URL. Remove --direct, then run the same command again."; #[derive(Debug, Parser)] @@ -115,7 +126,12 @@ enum Command { global: bool, }, /// Search for Skills. - Search { query: Vec }, + Search { + query: Vec, + /// Skills to show, from 1 to 50. The default is 20. + #[arg(long, value_name = "N", value_parser = search_limit)] + limit: Option, + }, /// Install a Skill, or restore the Skills in your lockfile. #[command( long_about = "Install a Skill, or restore the Skills in your lockfile.\n\nGive SOURCE as:\n OWNER/REPOSITORY/SKILL\n Install a hosted Artifact.\n github:OWNER/REPOSITORY/SKILL_PATH\n github:OWNER/REPOSITORY/SKILL_PATH#branch:BRANCH\n github:OWNER/REPOSITORY/SKILL_PATH#tag:TAG\n github:OWNER/REPOSITORY/SKILL_PATH#commit:SHA\n https://github.com/OWNER/REPOSITORY/tree/REF/SKILL_PATH\n Install a hosted Artifact from an explicit GitHub selector.\n Add --direct to fetch a public GitHub Repository instead.\n ./RELATIVE_PATH or ABSOLUTE_PATH\n Install a local Skill.\n skilld\n Install the skilld-maintained Skill with --global.\n\nRun skilld install without SOURCE to restore .skills/skilld-lock.yaml.\nVerified remote Skills restore the exact locked Git commit.", @@ -668,7 +684,11 @@ pub trait Host { )) } - fn search(&self, _query: &str) -> Result { + fn search( + &self, + _query: &str, + _limit: u8, + ) -> Result { Err(CommandError::unsupported_host( "Skill search is unavailable on this host", )) @@ -1966,7 +1986,7 @@ fn dispatch( } => host .config_list() .map(|lines| CommandOutput::Screen(Screen::new(lines))), - Command::Search { query } => { + Command::Search { query, limit } => { let query = query.join(" ").trim().to_owned(); if query.is_empty() || query.len() > 200 { return Err(CommandError::usage( @@ -1974,7 +1994,7 @@ fn dispatch( "Skill search needs a query up to 200 bytes", )); } - let response = host.search(&query)?; + let response = host.search(&query, limit.unwrap_or(DEFAULT_SEARCH_LIMIT))?; let items = response .items .into_iter() @@ -3463,9 +3483,9 @@ impl Host for LocalHost { .ok_or_else(|| CommandError::service("the skilld.dev API is unavailable in this build")) } - fn search(&self, query: &str) -> Result { + fn search(&self, query: &str, limit: u8) -> Result { self.remote_provider()? - .search(query, 20) + .search(query, limit) .map_err(CommandError::remote) } diff --git a/crates/skilld-command/tests/output.rs b/crates/skilld-command/tests/output.rs index 1b2db155..9dfce600 100644 --- a/crates/skilld-command/tests/output.rs +++ b/crates/skilld-command/tests/output.rs @@ -5,6 +5,7 @@ use skilld_core::{ InstallScope, InstallSource, RemoteError, SearchResponse, SearchResult, SourceProvider, SourceRequest, SourceSelector, }; +use std::cell::RefCell; use std::io::{self, Write}; use unicode_width::UnicodeWidthStr; @@ -26,11 +27,49 @@ impl Host for SearchHost { unreachable!("install is outside this test") } - fn search(&self, _query: &str) -> Result { + fn search(&self, _query: &str, _limit: u8) -> Result { self.response.clone() } } +/// Records the limit each search asks the registry for. +struct LimitHost { + limits: RefCell>, +} + +impl Host for LimitHost { + fn list(&self, _scope: InstallScope) -> Result, CommandError> { + unreachable!("list is outside this test") + } + + fn install( + &self, + _source: InstallSource, + _scope: InstallScope, + ) -> Result { + unreachable!("install is outside this test") + } + + fn search(&self, _query: &str, limit: u8) -> Result { + self.limits.borrow_mut().push(limit); + Ok(response()) + } +} + +fn run_limits(args: &[&str]) -> (u8, String, Vec) { + let host = LimitHost { + limits: RefCell::new(Vec::new()), + }; + let mut stdout = Vec::new(); + let mut stderr = Vec::new(); + let result = run_with_output(args, &host, PLAIN, &mut stdout, &mut stderr); + ( + result.exit_code, + String::from_utf8(stderr).unwrap(), + host.limits.into_inner(), + ) +} + fn response() -> SearchResponse { SearchResponse { items: vec![SearchResult { @@ -613,6 +652,37 @@ fn json_parse_errors_keep_the_typed_error_contract_for_untrusted_arguments() { ); } +#[test] +fn search_asks_the_registry_for_twenty_skills_unless_limit_says_otherwise() { + assert_eq!( + run_limits(&["skilld", "search", "grill"]), + (0, String::new(), vec![20]) + ); + assert_eq!( + run_limits(&["skilld", "search", "grill", "--limit", "1"]), + (0, String::new(), vec![1]) + ); + assert_eq!( + run_limits(&["skilld", "search", "--limit=50", "grill", "me"]), + (0, String::new(), vec![50]) + ); +} + +#[test] +fn search_refuses_a_limit_the_registry_would_reject_before_asking_it() { + for limit in ["0", "51", "256", "+5x", "ten", ""] { + let (exit, stderr, limits) = run_limits(&["skilld", "search", "grill", "--limit", limit]); + + assert_eq!(exit, 2, "{limit}"); + assert!(stderr.starts_with("INVALID_ARGUMENT:"), "{limit}: {stderr}"); + assert!( + stderr.contains("'--limit ': give a number from 1 to 50"), + "{limit}: {stderr}" + ); + assert!(limits.is_empty(), "{limit}"); + } +} + #[test] fn empty_json_search_is_a_tagged_usage_error() { let (exit, stdout, stderr) = run(&["skilld", "search", "--json"], PLAIN); diff --git a/crates/skilld-command/tests/v2_commands.rs b/crates/skilld-command/tests/v2_commands.rs index 58eb3486..0f39c003 100644 --- a/crates/skilld-command/tests/v2_commands.rs +++ b/crates/skilld-command/tests/v2_commands.rs @@ -19,7 +19,7 @@ impl Host for V2Host { unreachable!("install is outside this test") } - fn search(&self, _query: &str) -> Result { + fn search(&self, _query: &str, _limit: u8) -> Result { unreachable!("search is outside this test") } diff --git a/crates/skilld-native/src/main.rs b/crates/skilld-native/src/main.rs index c41f7ea9..5cef1199 100644 --- a/crates/skilld-native/src/main.rs +++ b/crates/skilld-native/src/main.rs @@ -550,7 +550,7 @@ impl Host for SearchOutputProbe { unreachable!("install is outside the search output probe") } - fn search(&self, _query: &str) -> Result { + fn search(&self, _query: &str, _limit: u8) -> Result { Ok(SearchResponse { items: vec![SearchResult { name: "output-probe".to_owned(), diff --git a/skills/skilld/SKILL.md b/skills/skilld/SKILL.md index 618318ad..d7d2f47b 100644 --- a/skills/skilld/SKILL.md +++ b/skills/skilld/SKILL.md @@ -64,6 +64,9 @@ skilld search --json Read `data.items` before choosing a Skill. Use each item's `selector` for a Skill run. Refine the query when several Skills cover different tasks. +Add `--limit N`, from 1 to 50, when the top few Skills are enough. +The default is 20. +`data.total` still counts every match. Do not guess a selector from the Skill name. Do not install a search result before reading its description.