Create, Evaluate, and Connect AI Skills
Python ai-agentsai-skillsartificial-intelligenceknowledge-graphlarge-language-modelsnatural-language-processingopenkgskillnetskills
fix(search): expose source identity in SDK and CLI (refs #36)
Icarus-Chen82f3cda6f2ac
diff --git a/skillnet-ai/README.md b/skillnet-ai/README.mdindex fecf2f4..deec285 100644--- a/skillnet-ai/README.md+++ b/skillnet-ai/README.md@@ -116,8 +116,10 @@ endpoints are configured separately.### SearchQuery 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.```pythonresults = 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.tomlindex 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.pyindex 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_validatorclass 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: strskill_description: str | None = None@@ -18,6 +18,13 @@ class SkillModel(BaseModel):skill_url: str | None = Nonecategory: str | None = Noneevaluation: 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.pyindex 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 Columnsfrom rich.console import Consolefrom rich.panel import Panelfrom rich.table import Table+from rich.text import Textfrom skillnet_ai.core.config import config_path, redact, resolve_settings, save_configfrom 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.pyindex 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.pynew file mode 100644index 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 cellsdiff --git a/skills/skillnet/references/api-reference.md b/skills/skillnet/references/api-reference.mdindex 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