Add skill suggestions for npx-style two-part handles

Kasper Junge · claude · Kasper Junge · commit 00060d4f464a · 2026-03-02T13:53:03.000+01:00
When `agr add owner/repo` fails to find a skill, probes the repo and lists available skills with correct three-part handles. This helps users coming from `npx skills` who expect two-part handle format. Fixes #62 Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,7 @@
 .codex/
 .github/skills/
 .agr/
+.opencode/
 
 
 # Python
diff --git a/.opencode/skill/brainstorm-solutions/.agr.json b/.opencode/skill/brainstorm-solutions/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/brainstorm-solutions",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/brainstorm-solutions",
   "tool": "opencode",
   "installed_name": "brainstorm-solutions",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/brainstorm-solutions"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/brainstorm-solutions"
 }
diff --git a/.opencode/skill/code-review/.agr.json b/.opencode/skill/code-review/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/code-review",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/code-review",
   "tool": "opencode",
   "installed_name": "code-review",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/code-review"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/code-review"
 }
diff --git a/.opencode/skill/commit-work/.agr.json b/.opencode/skill/commit-work/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/commit-work",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/commit-work",
   "tool": "opencode",
   "installed_name": "commit-work",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/commit-work"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/commit-work"
 }
diff --git a/.opencode/skill/create-plan/.agr.json b/.opencode/skill/create-plan/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/create-plan",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/create-plan",
   "tool": "opencode",
   "installed_name": "create-plan",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/create-plan"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/create-plan"
 }
diff --git a/.opencode/skill/design-solution/.agr.json b/.opencode/skill/design-solution/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/design-solution",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/design-solution",
   "tool": "opencode",
   "installed_name": "design-solution",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/design-solution"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/design-solution"
 }
diff --git a/.opencode/skill/discover-codebase-enhancements/.agr.json b/.opencode/skill/discover-codebase-enhancements/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/codebase-maintenance/discover-codebase-enhancements",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/codebase-maintenance/discover-codebase-enhancements",
   "tool": "opencode",
   "installed_name": "discover-codebase-enhancements",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/codebase-maintenance/discover-codebase-enhancements"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/codebase-maintenance/discover-codebase-enhancements"
 }
diff --git a/.opencode/skill/enhance-docs/.agr.json b/.opencode/skill/enhance-docs/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/codebase-maintenance/enhance-docs",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/codebase-maintenance/enhance-docs",
   "tool": "opencode",
   "installed_name": "enhance-docs",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/codebase-maintenance/enhance-docs"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/codebase-maintenance/enhance-docs"
 }
diff --git a/.opencode/skill/make-release/.agr.json b/.opencode/skill/make-release/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/make-release",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/make-release",
   "tool": "opencode",
   "installed_name": "make-release",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/make-release"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/make-release"
 }
diff --git a/.opencode/skill/migrate-to-skills/.agr.json b/.opencode/skill/migrate-to-skills/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/agr/migrate-to-skills",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/agr/migrate-to-skills",
   "tool": "opencode",
   "installed_name": "migrate-to-skills",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/agr/migrate-to-skills"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/agr/migrate-to-skills"
 }
diff --git a/.opencode/skill/refactor-for-determinism/.agr.json b/.opencode/skill/refactor-for-determinism/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/skill-development/refactor-for-determinism",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/skill-development/refactor-for-determinism",
   "tool": "opencode",
   "installed_name": "refactor-for-determinism",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/skill-development/refactor-for-determinism"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/skill-development/refactor-for-determinism"
 }
diff --git a/.opencode/skill/research-codebase/.agr.json b/.opencode/skill/research-codebase/.agr.json
@@ -1,7 +1,7 @@
 {
-  "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/research-codebase",
+  "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/research-codebase",
   "tool": "opencode",
   "installed_name": "research-codebase",
   "type": "local",
-  "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/research-codebase"
+  "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/research-codebase"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+### Added
+- Helpful suggestions when a two-part handle (e.g. `agr add owner/repo`) fails: probes the repo and lists available skills with correct three-part handles
+- `list_remote_repo_skills` function to scan a remote repo for available skills
+- `discover_skills_in_repo_listing` function to extract all skill names from a git file listing
+- "Coming from npx skills?" section in README explaining handle format differences
+
+### Changed
+- Refactored `find_skill_in_repo_listing` to use shared `_iter_skill_dirs_in_listing` helper
+- Cleaned up `agr.toml` dependencies (removed duplicates and non-existent skills)
+- Added `.opencode/` to `.gitignore`
+
 ## [0.7.5] - 2026-02-07
 
 ### Added
diff --git a/README.md b/README.md
@@ -195,6 +195,24 @@ agr add madsnorgaard/drupal-expert
 
 ---
 
+## Coming from npx skills?
+
+agr uses a slightly different handle format than `npx skills`:
+
+| What you want | npx skills | agr |
+|---|---|---|
+| Skill from a repo | `npx skills add owner/repo` | `agr add owner/repo/skill-name` |
+| Skill from user's default repo | — | `agr add owner/skill-name` |
+
+The key difference: `agr` handles always point to a **specific skill**, not a
+repo to scan. Use the three-part format `owner/repo/skill-name` when the skill
+lives in a non-default repo.
+
+If you use a two-part handle and the skill isn't found, `agr` will check if a
+matching repository exists and suggest the correct handles.
+
+---
+
 <div align="center">
 
 [Documentation](https://kasperjunge.github.io/agent-resources/) · [MIT License](LICENSE)
diff --git a/agr.toml b/agr.toml
@@ -6,19 +6,12 @@ dependencies = [
     {path = "./skills/development/workflow/commit-work", type = "skill"},
     {path = "./skills/development/workflow/create-plan", type = "skill"},
     {path = "./skills/development/workflow/design-solution", type = "skill"},
-    {path = "./skills/product-strategy/discover-assumptions", type = "skill"},
     {path = "./skills/development/codebase-maintenance/discover-codebase-enhancements", type = "skill"},
-    {path = "./skills/product-strategy/discover-opportunities", type = "skill"},
-    {path = "./skills/product-strategy/discover-outcomes", type = "skill"},
     {path = "./skills/development/codebase-maintenance/enhance-docs", type = "skill"},
-    {path = "./skills/product-strategy/ideate-solutions", type = "skill"},
     {path = "./skills/development/workflow/make-release", type = "skill"},
     {path = "./skills/agr/migrate-to-skills", type = "skill"},
-    {path = "./skills/product-development/ost", type = "skill"},
     {path = "./skills/skill-development/refactor-for-determinism", type = "skill"},
     {path = "./skills/development/workflow/research-codebase", type = "skill"},
-    {path = "./skills/writing/skriv-som-kasper", type = "skill"},
-    {path = "skills/development/workflow/make-release", type = "skill"},
 ]
 
 [[source]]
diff --git a/agr/commands/add.py b/agr/commands/add.py
@@ -11,9 +11,10 @@
     find_repo_root,
     get_or_create_global_config,
 )
-from agr.exceptions import AgrError, InvalidHandleError
-from agr.fetcher import fetch_and_install_to_tools
-from agr.handle import parse_handle
+from agr.exceptions import AgrError, InvalidHandleError, SkillNotFoundError
+from agr.fetcher import fetch_and_install_to_tools, list_remote_repo_skills
+from agr.handle import ParsedHandle, parse_handle
+from agr.source import SourceResolver
 
 console = Console()
 
@@ -109,6 +110,9 @@ def run_add(
 
             results.append((ref, True, ", ".join(installed_paths)))
 
+        except SkillNotFoundError as e:
+            message = _maybe_suggest_repo_skills(ref, handle, resolver, source)
+            results.append((ref, False, message or str(e)))
         except InvalidHandleError as e:
             results.append((ref, False, str(e)))
         except FileExistsError as e:
@@ -143,3 +147,48 @@ def run_add(
     failures = [r for r in results if not r[1]]
     if failures:
         raise SystemExit(1)
+
+
+def _maybe_suggest_repo_skills(
+    ref: str,
+    handle: ParsedHandle,
+    resolver: SourceResolver,
+    source: str | None,
+) -> str | None:
+    """Try to suggest correct handles when a two-part handle fails.
+
+    When a handle like "owner/name" fails (no skill "name" in the default
+    "skills" repo), probes "owner/name" as a GitHub repo and lists
+    available skills to suggest three-part handles.
+
+    Returns:
+        A helpful error message with suggestions, or None to use the default.
+    """
+    # Only probe for two-part remote handles (no explicit repo)
+    if handle.is_local or handle.repo is not None:
+        return None
+
+    owner = handle.username
+    repo_name = handle.name
+    if not owner or not repo_name:
+        return None
+
+    try:
+        skills = list_remote_repo_skills(owner, repo_name, resolver, source)
+    except Exception:
+        return None
+
+    if not skills:
+        return None
+
+    lines = [
+        f"Skill '{repo_name}' not found. "
+        f"However, '{owner}/{repo_name}' exists as a repository "
+        f"with {len(skills)} skill(s):",
+        "",
+    ]
+    for skill in skills:
+        lines.append(f"  agr add {owner}/{repo_name}/{skill}")
+    lines.append("")
+    lines.append("Hint: agr handles use the format: owner/repo/skill-name")
+    return "\n".join(lines)
diff --git a/agr/fetcher.py b/agr/fetcher.py
@@ -21,6 +21,7 @@
 from agr.metadata import build_handle_id, read_skill_metadata, write_skill_metadata
 from agr.skill import (
     SKILL_MARKER,
+    discover_skills_in_repo_listing,
     find_skill_in_repo,
     find_skill_in_repo_listing,
     is_valid_skill_dir,
@@ -473,6 +474,37 @@ def prepare_repo_for_skills(repo_dir: Path, skill_names: list[str]) -> dict[str,
         return resolved
 
 
+def list_remote_repo_skills(
+    owner: str,
+    repo_name: str,
+    resolver: SourceResolver | None = None,
+    source: str | None = None,
+) -> list[str]:
+    """List all skill names in a remote repository.
+
+    Clones the repo and scans for SKILL.md files. Used to provide
+    helpful suggestions when a two-part handle fails.
+
+    Args:
+        owner: Repository owner/username
+        repo_name: Repository name
+        resolver: Source resolver for finding the repo
+        source: Explicit source name
+
+    Returns:
+        Sorted list of skill names found, or empty list on any error.
+    """
+    resolver = resolver or SourceResolver(default_sources(), DEFAULT_SOURCE_NAME)
+    for source_config in resolver.ordered(source):
+        try:
+            with downloaded_repo(source_config, owner, repo_name) as repo_dir:
+                paths = _git_list_files(repo_dir)
+                return discover_skills_in_repo_listing(paths)
+        except AgrError:
+            continue
+    return []
+
+
 def _build_handle_ids(
     handle: ParsedHandle,
     repo_root: Path | None,
diff --git a/agr/skill.py b/agr/skill.py
@@ -96,20 +96,19 @@ def find_skill_in_repo(repo_dir: Path, skill_name: str) -> Path | None:
     return min(matches, key=lambda p: len(p.parts))
 
 
-def find_skill_in_repo_listing(
-    paths: list[str], skill_name: str
-) -> PurePosixPath | None:
-    """Find a skill directory from a git file listing.
+def _iter_skill_dirs_in_listing(paths: list[str]) -> list[PurePosixPath]:
+    """Return valid skill directories from a git file listing.
+
+    Filters SKILL.md entries, excluding root-level markers and paths
+    within excluded directories (.git, node_modules, etc.).
 
     Args:
         paths: List of file paths from git (posix-style).
-        skill_name: Name of the skill to find.
 
     Returns:
-        Path to skill directory (posix-style, relative), or None if not found.
+        List of skill directory paths (parent of each valid SKILL.md).
     """
-    matches: list[PurePosixPath] = []
-
+    results: list[PurePosixPath] = []
     for rel in paths:
         rel_path = PurePosixPath(rel)
         if rel_path.name != SKILL_MARKER:
@@ -119,15 +118,42 @@ def find_skill_in_repo_listing(
             continue
         if any(part in EXCLUDED_DIRS for part in rel_path.parts):
             continue
-        if rel_path.parent.name == skill_name:
-            matches.append(rel_path.parent)
+        results.append(rel_path.parent)
+    return results
 
+
+def find_skill_in_repo_listing(
+    paths: list[str], skill_name: str
+) -> PurePosixPath | None:
+    """Find a skill directory from a git file listing.
+
+    Args:
+        paths: List of file paths from git (posix-style).
+        skill_name: Name of the skill to find.
+
+    Returns:
+        Path to skill directory (posix-style, relative), or None if not found.
+    """
+    matches = [d for d in _iter_skill_dirs_in_listing(paths) if d.name == skill_name]
     if not matches:
         return None
-
     return min(matches, key=lambda p: len(p.parts))
 
 
+def discover_skills_in_repo_listing(paths: list[str]) -> list[str]:
+    """Discover all skill names from a git file listing.
+
+    Returns all unique skill names found. Results are sorted alphabetically.
+
+    Args:
+        paths: List of file paths from git (posix-style).
+
+    Returns:
+        Sorted list of unique skill names found in the listing.
+    """
+    return sorted({d.name for d in _iter_skill_dirs_in_listing(paths)})
+
+
 def discover_skills_in_repo(repo_dir: Path) -> list[tuple[str, Path]]:
     """Discover all skills in a repository.
 
diff --git a/tests/test_commands.py b/tests/test_commands.py
diff --git a/tests/test_fetcher.py b/tests/test_fetcher.py
diff --git a/tests/test_skill.py b/tests/test_skill.py

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`		`- "id": "local:/Users/kasperjunge/projects/agent-resources/skills/development/workflow/brainstorm-solutions",`
	`2`	`+ "id": "local:/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/brainstorm-solutions",`
`3`	`3`	`"tool": "opencode",`
`4`	`4`	`"installed_name": "brainstorm-solutions",`
`5`	`5`	`"type": "local",`
`6`		`- "local_path": "/Users/kasperjunge/projects/agent-resources/skills/development/workflow/brainstorm-solutions"`
	`6`	`+ "local_path": "/Users/kasperjunge/Code/business/agent-resources/skills/development/workflow/brainstorm-solutions"`
`7`	`7`	`}`