Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
32 changes: 26 additions & 6 deletions crates/skilld-command/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<u8, &'static str> {
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)]
Expand Down Expand Up @@ -115,7 +126,12 @@ enum Command {
global: bool,
},
/// Search for Skills.
Search { query: Vec<String> },
Search {
query: Vec<String>,
/// Skills to show, from 1 to 50. The default is 20.
#[arg(long, value_name = "N", value_parser = search_limit)]
limit: Option<u8>,
},
/// 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.",
Expand Down Expand Up @@ -668,7 +684,11 @@ pub trait Host {
))
}

fn search(&self, _query: &str) -> Result<skilld_core::SearchResponse, CommandError> {
fn search(
&self,
_query: &str,
_limit: u8,
) -> Result<skilld_core::SearchResponse, CommandError> {
Err(CommandError::unsupported_host(
"Skill search is unavailable on this host",
))
Expand Down Expand Up @@ -1966,15 +1986,15 @@ fn dispatch<H: Host>(
} => 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(
"INVALID_SEARCH",
"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()
Expand Down Expand Up @@ -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<skilld_core::SearchResponse, CommandError> {
fn search(&self, query: &str, limit: u8) -> Result<skilld_core::SearchResponse, CommandError> {
self.remote_provider()?
.search(query, 20)
.search(query, limit)
.map_err(CommandError::remote)
}

Expand Down
72 changes: 71 additions & 1 deletion crates/skilld-command/tests/output.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -26,11 +27,49 @@ impl Host for SearchHost {
unreachable!("install is outside this test")
}

fn search(&self, _query: &str) -> Result<SearchResponse, CommandError> {
fn search(&self, _query: &str, _limit: u8) -> Result<SearchResponse, CommandError> {
self.response.clone()
}
}

/// Records the limit each search asks the registry for.
struct LimitHost {
limits: RefCell<Vec<u8>>,
}

impl Host for LimitHost {
fn list(&self, _scope: InstallScope) -> Result<Vec<String>, CommandError> {
unreachable!("list is outside this test")
}

fn install(
&self,
_source: InstallSource,
_scope: InstallScope,
) -> Result<InstalledSkill, CommandError> {
unreachable!("install is outside this test")
}

fn search(&self, _query: &str, limit: u8) -> Result<SearchResponse, CommandError> {
self.limits.borrow_mut().push(limit);
Ok(response())
}
}

fn run_limits(args: &[&str]) -> (u8, String, Vec<u8>) {
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 {
Expand Down Expand Up @@ -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 <N>': 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);
Expand Down
2 changes: 1 addition & 1 deletion crates/skilld-command/tests/v2_commands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ impl Host for V2Host {
unreachable!("install is outside this test")
}

fn search(&self, _query: &str) -> Result<SearchResponse, CommandError> {
fn search(&self, _query: &str, _limit: u8) -> Result<SearchResponse, CommandError> {
unreachable!("search is outside this test")
}

Expand Down
2 changes: 1 addition & 1 deletion crates/skilld-native/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -550,7 +550,7 @@ impl Host for SearchOutputProbe {
unreachable!("install is outside the search output probe")
}

fn search(&self, _query: &str) -> Result<SearchResponse, CommandError> {
fn search(&self, _query: &str, _limit: u8) -> Result<SearchResponse, CommandError> {
Ok(SearchResponse {
items: vec![SearchResult {
name: "output-probe".to_owned(),
Expand Down
3 changes: 3 additions & 0 deletions skills/skilld/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,9 @@ skilld search <query> --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.
Expand Down