Skip to content

Create, Evaluate, and Connect AI Skills

fix(search): expose source identity in SDK and CLI (refs #36)

Icarus-Chen82f3cda6f2ac
diff --git a/skillnet-ai/README.md b/skillnet-ai/README.md
index fecf2f4..deec285 100644
--- a/skillnet-ai/README.md
+++ b/skillnet-ai/README.md
@@ -116,8 +116,10 @@ endpoints are configured separately.
### Search
Query the hosted SkillNet catalog and return a list of skill records. Keyword
-search defaults to sorting by stars. Vector search uses the hosted service's
-embeddings; `EMBEDDING_*` settings apply to local analysis and routing.
+search works with short names/keywords and defaults to sorting by repository stars.
+For natural-language tasks, use vector search, which returns results in similarity
+order using the hosted service's embeddings. `EMBEDDING_*` settings apply to local
+analysis and routing.
```python
results = client.search(
@@ -131,6 +133,27 @@ for skill in results:
print(skill.skill_name, skill.stars, skill.skill_url)
```
+**Names and sources.** `skill_name` is not unique: different repositories or version
+directories can contain skills with the same name. `stars` is the source repository's
+star count at collection time, not a rating of the individual skill.
+
+With skillnet-ai 0.1.3+, search records also expose nullable source fields:
+
+| Field | Meaning | Example |
+| :-- | :-- | :-- |
+| `repo_name` | Source repository | `owner/repository` |
+| `skill_dir` | Source directory, including the repository prefix | `owner/repository/releases/v2/skills/example` |
+
+The CLI shows the repository and directory below each skill name; `--json` preserves
+the full fields. Missing metadata is `null` (`None` in Python), including responses
+from older servers. Older SDK releases ignore these fields; upgrade with
+`pip install -U skillnet-ai` to read them in Python or CLI output.
+
+Use `skill_url` to distinguish returned source links and download the selected entry.
+For grouping a collected source directory, use `skill_dir` when available. A directory
+can receive content updates, and its commit-specific `skill_url` can change; neither
+the name nor name plus repository uniquely identifies all source directories.
+
<details>
<summary><b>Search parameters</b></summary>
diff --git a/skillnet-ai/pyproject.toml b/skillnet-ai/pyproject.toml
index d9640e9..0428d10 100644
--- a/skillnet-ai/pyproject.toml
+++ b/skillnet-ai/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "skillnet-ai"
-version = "0.1.2"
+version = "0.1.3"
description = "Official Python SDK for SkillNet: Create, Evaluate, and Connect AI Skills."
readme = "README.md"
authors = [{ name = "SkillNet Team", email = "[email protected]" }]
diff --git a/skillnet-ai/src/skillnet_ai/core/models.py b/skillnet-ai/src/skillnet_ai/core/models.py
index 8e4d5b0..c643a14 100644
--- a/skillnet-ai/src/skillnet_ai/core/models.py
+++ b/skillnet-ai/src/skillnet_ai/core/models.py
@@ -9,7 +9,7 @@ from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
class SkillModel(BaseModel):
- """Represents a Skill object returned from the search API."""
+ """A source record; names are not unique and stars belong to the repository."""
skill_name: str
skill_description: str | None = None
@@ -18,6 +18,13 @@ class SkillModel(BaseModel):
skill_url: str | None = None
category: str | None = None
evaluation: dict[str, Any] | None = None
+ repo_name: str | None = Field(
+ default=None, description="Source repository in owner/repository form, when known."
+ )
+ skill_dir: str | None = Field(
+ default=None,
+ description="Source directory including the owner/repository prefix, when known.",
+ )
class MetaModel(BaseModel):
diff --git a/skillnet-ai/src/skillnet_ai/interfaces/cli.py b/skillnet-ai/src/skillnet_ai/interfaces/cli.py
index 7c5196b..e602dfa 100644
--- a/skillnet-ai/src/skillnet_ai/interfaces/cli.py
+++ b/skillnet-ai/src/skillnet_ai/interfaces/cli.py
@@ -15,6 +15,7 @@ from rich.columns import Columns
from rich.console import Console
from rich.panel import Panel
from rich.table import Table
+from rich.text import Text
from skillnet_ai.core.config import config_path, redact, resolve_settings, save_config
from skillnet_ai.core.llm import error_details
@@ -133,9 +134,26 @@ def search(
console.print("No results found.")
else:
table = Table(title="Search Results", show_lines=True)
- for name in ("Name", "Category", "Stars", "Description", "Evaluation", "URL"):
+ for name in (
+ "Skill / Source",
+ "Category",
+ "Repo Stars",
+ "Description",
+ "Evaluation",
+ "URL",
+ ):
table.add_column(name)
for item in results:
+ identity = Text(item.skill_name, style="bold", overflow="fold")
+ if item.repo_name:
+ identity.append(f"\n{item.repo_name}", style="default")
+ if item.skill_dir:
+ directory = item.skill_dir
+ if item.repo_name:
+ directory = directory.removeprefix(item.repo_name + "/")
+ if item.skill_dir.rstrip("/") == item.repo_name:
+ directory = "."
+ identity.append(f"\n{directory}", style="default")
ratings = (
"\n".join(
f"{d}: {item.evaluation.get(d, {}).get('level', 'N/A')}" for d in DIMENSIONS
@@ -144,7 +162,7 @@ def search(
else "N/A"
)
table.add_row(
- item.skill_name,
+ identity,
item.category or "",
str(item.stars),
item.skill_description or "",
diff --git a/skillnet-ai/src/skillnet_ai/searcher.py b/skillnet-ai/src/skillnet_ai/searcher.py
index 243b790..27eb8c4 100644
--- a/skillnet-ai/src/skillnet_ai/searcher.py
+++ b/skillnet-ai/src/skillnet_ai/searcher.py
@@ -16,7 +16,7 @@ class SkillNetSearcher:
self.skillnet_api_url = resolve_settings(skillnet_api_url=skillnet_api_url).skillnet_api_url.rstrip("/")
self.session = requests.Session()
self.session.headers.update({
- "User-Agent": "SkillNet-Python-SDK/0.1.2"
+ "User-Agent": "SkillNet-Python-SDK/0.1.3"
})
def search(
diff --git a/skillnet-ai/tests/test_sdk_search_sources.py b/skillnet-ai/tests/test_sdk_search_sources.py
new file mode 100644
index 0000000..f444bb3
--- /dev/null
+++ b/skillnet-ai/tests/test_sdk_search_sources.py
@@ -0,0 +1,113 @@
+"""Search source metadata is usable in Python, JSON and terminal output."""
+
+import json
+from unittest.mock import Mock
+
+import pytest
+import requests
+from rich.console import Console
+from typer.testing import CliRunner
+
+from skillnet_ai.core.models import SkillModel
+from skillnet_ai.interfaces import cli
+from skillnet_ai.interfaces.client import SkillNetClient
+
+
+def search_response(monkeypatch):
+ rows = [
+ {
+ "skill_name": "example",
+ "repo_name": "owner/repo",
+ "skill_dir": f"owner/repo/releases/{version}/example",
+ "skill_url": f"https://github.com/owner/repo/tree/commit/releases/{version}/example",
+ "stars": 10,
+ }
+ for version in ("v1", "v2")
+ ]
+ # Old servers omit the fields; local/non-GitHub records may return null.
+ rows.extend(
+ [{"skill_name": "legacy"}, {"skill_name": "local", "repo_name": None, "skill_dir": None}]
+ )
+ response = requests.Response()
+ response.status_code = 200
+ response._content = json.dumps({"success": True, "data": rows, "meta": {}}).encode()
+ get = Mock(return_value=response)
+ monkeypatch.setattr(requests.Session, "get", get)
+ return rows, get
+
+
+def test_sdk_and_cli_json_preserve_source_identity(search_response):
+ rows, get = search_response
+ result = SkillNetClient().search("example")
+ assert [(r.repo_name, r.skill_dir) for r in result] == [
+ (r.get("repo_name"), r.get("skill_dir")) for r in rows
+ ]
+ assert get.call_count == 1
+ assert "repo_name" not in get.call_args.kwargs["params"]
+ assert "skill_dir" not in get.call_args.kwargs["params"]
+ output = CliRunner().invoke(cli.app, ["search", "example", "--json"])
+ assert output.exit_code == 0, output.output
+ data = json.loads(output.stdout)["data"]
+ assert [(r["repo_name"], r["skill_dir"]) for r in data] == [
+ (r.get("repo_name"), r.get("skill_dir")) for r in rows
+ ]
+ assert [r["skill_url"] for r in data] == [r.get("skill_url") for r in rows]
+
+
+def test_cli_displays_sources_without_changing_download_urls(search_response, monkeypatch):
+ monkeypatch.setattr(cli, "console", Console(width=180, force_terminal=False, highlight=False))
+ output = CliRunner().invoke(cli.app, ["search", "example"])
+ assert output.exit_code == 0, output.output
+ assert "Source" in output.stdout
+ assert "Repo Stars" in output.stdout
+ assert "owner/repo" in output.stdout
+ assert "releases/v1/example" in output.stdout
+ assert "releases/v2/example" in output.stdout
+ assert "legacy" in output.stdout and "local" in output.stdout
+
+
+def test_cli_treats_source_metadata_as_literal_text(search_response, monkeypatch):
+ rows, _ = search_response
+ rows[0]["repo_name"] = "owner/[demo]"
+ rows[0]["skill_dir"] = "owner/[demo]/[red]example[/red]"
+ monkeypatch.setattr(SkillNetClient, "search", lambda *a, **k: [SkillModel(**rows[0])])
+ monkeypatch.setattr(cli, "console", Console(width=180, force_terminal=False, highlight=False))
+ output = CliRunner().invoke(cli.app, ["search", "example"])
+ assert output.exit_code == 0, output.output
+ assert "[demo]" in output.stdout
+ assert "[red]example[/red]" in output.stdout
+
+
+def test_cli_keeps_long_sources_readable_in_a_narrow_terminal(monkeypatch):
+ repo = "danielmiessler/Personal_AI_Infrastructure"
+ directory = "Releases/v4.0.2/.claude/skills/Security/PromptInjection"
+ row = SkillModel(
+ skill_name="PromptInjection",
+ repo_name=repo,
+ skill_dir=f"{repo}/{directory}",
+ skill_description="Prompt injection testing.",
+ skill_url=f"https://github.com/{repo}/tree/commit/{directory}",
+ )
+ monkeypatch.setattr(SkillNetClient, "search", lambda *a, **k: [row])
+ monkeypatch.setattr(cli, "console", Console(width=80, force_terminal=False, highlight=False))
+ output = CliRunner().invoke(cli.app, ["search", "prompt injection"])
+ assert output.exit_code == 0, output.output
+ # Reassemble the wrapped source cell; truncation would lose real characters.
+ identity = "".join(
+ line.split("│")[1].strip() for line in output.stdout.splitlines() if line.startswith("│")
+ )
+ assert repo in identity and directory in identity
+
+
[email protected]("directory", ["owner/repo", "owner/repo/"])
+def test_cli_displays_repository_root_as_dot(directory, monkeypatch):
+ row = SkillModel(skill_name="example", repo_name="owner/repo", skill_dir=directory)
+ monkeypatch.setattr(SkillNetClient, "search", lambda *a, **k: [row])
+ monkeypatch.setattr(cli, "console", Console(width=140, force_terminal=False, highlight=False))
+ output = CliRunner().invoke(cli.app, ["search", "example"])
+ assert output.exit_code == 0, output.output
+ cells = [
+ line.split("│")[1].strip() for line in output.stdout.splitlines() if line.startswith("│")
+ ]
+ assert cells.count("owner/repo") == 1 and "." in cells
diff --git a/skills/skillnet/references/api-reference.md b/skills/skillnet/references/api-reference.md
index b83a528..c9319ca 100644
--- a/skills/skillnet/references/api-reference.md
+++ b/skills/skillnet/references/api-reference.md
@@ -47,6 +47,19 @@ Business results use one JSON document on stdout:
| analyze | `index_dir`, `skill_count`, `relation_counts`, `cache_hits`; the full graph is in the analysis directory |
| route | `skills` with IDs, names, original paths and reasons; available `usage` |
+Search records include nullable `repo_name` (`owner/repository`) and `skill_dir`
+(the source directory including that repository prefix). SDK/CLI 0.1.3+ versions
+preserve these fields; older SDK versions ignore them, and older servers may omit
+them. The CLI displays the repository and directory below the skill name.
+
+`skill_name` is not unique: repositories and version directories may share names.
+Do not merge results by name or name plus repository. Use `skill_url` to distinguish
+returned source links and select a download; use `skill_dir`, when available, to
+group a source directory across updates. It is not a content-version identifier.
+`stars` belongs to the source repository at collection time. Short keywords work
+with `--mode keyword`; use `--mode vector` for natural-language tasks and similarity
+ordering.
+
A failed operation has `ok: false`, `error: {code, message, hint}` and exits 1.
Partial creation data remains available. Empty search results are successful.
CLI usage errors (invalid flags or argument types) use exit 2 and stderr; stdout