skilldex 0.1.0__py3-none-any.whl

skilldex/__init__.py

@@ -0,0 +1,3 @@
+"""skilldex — search, install, validate, and audit Claude Code skills, subagents, and MCP servers."""
+
+__version__ = "0.1.0"

skilldex/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m skilldex`."""
+
+from .cli import app
+
+app()

skilldex/audit.py

@@ -0,0 +1,62 @@
+"""Audit local Claude Code configuration for common problems."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .validator import looks_like_secret, validate_agent_md, validate_skill_md
+
+
+def audit(project_root: Path | None = None, home: Path | None = None) -> list[tuple[str, str]]:
+    """Scan local Claude Code config. Returns (path, problem) findings."""
+    root = project_root or Path.cwd()
+    home = home or Path.home()
+    findings: list[tuple[str, str]] = []
+
+    mcp_file = root / ".mcp.json"
+    if mcp_file.exists():
+        findings.extend(_audit_mcp_config(mcp_file))
+
+    for skills_dir in (home / ".claude" / "skills", root / ".claude" / "skills"):
+        if skills_dir.is_dir():
+            for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
+                findings.extend((str(skill_md), error) for error in validate_skill_md(skill_md))
+
+    for agents_dir in (home / ".claude" / "agents", root / ".claude" / "agents"):
+        if agents_dir.is_dir():
+            for agent_md in sorted(agents_dir.rglob("*.md")):
+                findings.extend((str(agent_md), error) for error in validate_agent_md(agent_md))
+
+    return findings
+
+
+def _audit_mcp_config(mcp_file: Path) -> list[tuple[str, str]]:
+    findings: list[tuple[str, str]] = []
+    try:
+        config = json.loads(mcp_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        return [(str(mcp_file), f"cannot parse: {exc}")]
+    for name, server in (config.get("mcpServers") or {}).items():
+        if not isinstance(server, dict):
+            findings.append((str(mcp_file), f"server {name!r}: definition is not an object"))
+            continue
+        for key, value in (server.get("env") or {}).items():
+            if looks_like_secret(value):
+                findings.append(
+                    (
+                        str(mcp_file),
+                        f"server {name!r}: env {key} contains what looks like a plaintext "
+                        "secret — .mcp.json is usually committed; use a ${VAR} placeholder",
+                    )
+                )
+        for header, value in (server.get("headers") or {}).items():
+            if looks_like_secret(value):
+                findings.append(
+                    (
+                        str(mcp_file),
+                        f"server {name!r}: header {header} contains what looks like a "
+                        "plaintext secret — use a ${VAR} placeholder",
+                    )
+                )
+    return findings

skilldex/cli.py

@@ -0,0 +1,196 @@
+"""skilldex command-line interface."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .audit import audit as run_audit
+from .installer import agent_dest, install_mcp, install_source, skill_dest
+from .registry import fetch_index, get_entry_fresh
+from .registry import search as search_index
+from .validator import check_skill_md, validate_agent_md, validate_entry
+
+app = typer.Typer(
+    help="Search, install, validate, and audit Claude Code skills, subagents, and MCP servers.",
+    no_args_is_help=True,
+)
+console = Console()
+
+TYPE_COLORS = {"skill": "green", "agent": "magenta", "mcp": "cyan"}
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"skilldex {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show version."
+    ),
+) -> None:
+    pass
+
+
+def _load_index(refresh: bool = False) -> dict:
+    try:
+        return fetch_index(force=refresh)
+    except (httpx.HTTPError, json.JSONDecodeError) as exc:
+        console.print(f"[red]Could not fetch registry index:[/] {exc}")
+        raise typer.Exit(2) from exc
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search terms, e.g. 'pdf' or 'github issues'."),
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter: skill, agent, or mcp."),
+    refresh: bool = typer.Option(False, "--refresh", help="Bypass the local index cache."),
+) -> None:
+    """Search the registry."""
+    results = search_index(_load_index(refresh), query, type)
+    if not results:
+        console.print("[yellow]No matches.[/]")
+        raise typer.Exit(1)
+    table = Table(box=None, pad_edge=False)
+    table.add_column("ID", style="bold")
+    table.add_column("Type")
+    table.add_column("Description", overflow="fold")
+    for entry in results:
+        etype = entry.get("type", "?")
+        table.add_row(
+            entry.get("id", "?"),
+            f"[{TYPE_COLORS.get(etype, 'white')}]{etype}[/]",
+            entry.get("description", ""),
+        )
+    console.print(table)
+
+
+@app.command()
+def show(entry_id: str = typer.Argument(..., help="Registry entry id.")) -> None:
+    """Show the full registry entry."""
+    entry = get_entry_fresh(_load_index(), entry_id)
+    if entry is None:
+        console.print(f"[red]No entry with id {entry_id!r}.[/] Try: skilldex search {entry_id}")
+        raise typer.Exit(1)
+    console.print_json(json.dumps(entry))
+
+
+@app.command()
+def install(
+    entry_id: str = typer.Argument(..., help="Registry entry id."),
+    project: bool = typer.Option(
+        False, "--project", "-p", help="Install into ./.claude instead of ~/.claude."
+    ),
+) -> None:
+    """Install a skill, subagent, or MCP server."""
+    entry = get_entry_fresh(_load_index(), entry_id)
+    if entry is None:
+        console.print(f"[red]No entry with id {entry_id!r}.[/] Try: skilldex search {entry_id}")
+        raise typer.Exit(1)
+
+    etype = entry.get("type")
+    if etype == "skill":
+        dest = install_source(entry, skill_dest(project))
+        console.print(f"[green]Installed skill[/] {entry_id} → {dest}")
+    elif etype == "agent":
+        dest = install_source(entry, agent_dest(project))
+        console.print(f"[green]Installed agent[/] {entry_id} → {dest}")
+    elif etype == "mcp":
+        config_path = install_mcp(entry)
+        console.print(f"[green]Added MCP server[/] {entry_id} → {config_path}")
+        env = entry.get("mcp", {}).get("env") or {}
+        placeholders = [k for k, v in env.items() if isinstance(v, str) and v.startswith("${")]
+        if placeholders:
+            console.print(
+                f"[yellow]Set these environment variables:[/] {', '.join(placeholders)}"
+            )
+    else:
+        console.print(f"[red]Unknown entry type {etype!r}.[/]")
+        raise typer.Exit(2)
+
+
+@app.command()
+def validate(
+    path: Path = typer.Argument(..., exists=True, help="SKILL.md, agent .md, entry .json, or a skill directory."),
+) -> None:
+    """Validate a SKILL.md, subagent file, or registry entry."""
+    target = path / "SKILL.md" if path.is_dir() and (path / "SKILL.md").exists() else path
+    warnings: list[str] = []
+    if target.suffix == ".json":
+        try:
+            entry = json.loads(target.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            console.print(f"[red]{target}: invalid JSON:[/] {exc}")
+            raise typer.Exit(1) from exc
+        errors = validate_entry(entry, filename=str(target))
+    elif target.name == "SKILL.md":
+        errors, warnings = check_skill_md(target)
+    elif target.suffix == ".md":
+        errors = validate_agent_md(target)
+    else:
+        console.print(f"[red]Don't know how to validate {target}[/] (expected .md or .json)")
+        raise typer.Exit(2)
+
+    for warning in warnings:
+        console.print(f"[yellow]![/] {target}: {warning}")
+    if errors:
+        for error in errors:
+            console.print(f"[red]✗[/] {target}: {error}")
+        raise typer.Exit(1)
+    console.print(f"[green]✓[/] {target} is valid")
+
+
+@app.command()
+def audit() -> None:
+    """Audit local Claude Code config (skills, agents, .mcp.json) for problems."""
+    findings = run_audit()
+    if not findings:
+        console.print("[green]✓ No problems found.[/]")
+        return
+    for location, problem in findings:
+        console.print(f"[red]✗[/] {location}: {problem}")
+    raise typer.Exit(1)
+
+
+@app.command("list")
+def list_installed() -> None:
+    """List locally installed skills, agents, and project MCP servers."""
+    table = Table(box=None, pad_edge=False)
+    table.add_column("Type")
+    table.add_column("Name", style="bold")
+    table.add_column("Location")
+    rows = 0
+    for scope, base in (("user", Path.home()), ("project", Path.cwd())):
+        skills = base / ".claude" / "skills"
+        if skills.is_dir():
+            for skill in sorted(p for p in skills.iterdir() if (p / "SKILL.md").exists()):
+                table.add_row("[green]skill[/]", skill.name, f"{scope}: {skill}")
+                rows += 1
+        agents = base / ".claude" / "agents"
+        if agents.is_dir():
+            for agent in sorted(agents.rglob("*.md")):
+                table.add_row("[magenta]agent[/]", agent.stem, f"{scope}: {agent}")
+                rows += 1
+    mcp_file = Path.cwd() / ".mcp.json"
+    if mcp_file.exists():
+        try:
+            config = json.loads(mcp_file.read_text(encoding="utf-8"))
+            for name in config.get("mcpServers") or {}:
+                table.add_row("[cyan]mcp[/]", name, f"project: {mcp_file}")
+                rows += 1
+        except json.JSONDecodeError:
+            console.print(f"[yellow]Warning: {mcp_file} is not valid JSON.[/]")
+    if rows == 0:
+        console.print("[yellow]Nothing installed yet.[/] Try: skilldex search <topic>")
+        return
+    console.print(table)

skilldex/installer.py

@@ -0,0 +1,67 @@
+"""Install skills/agents from GitHub and MCP servers into .mcp.json."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import httpx
+
+GITHUB_API = "https://api.github.com"
+
+MCP_SERVER_KEYS = ("type", "command", "args", "env", "url", "headers")
+
+
+def skill_dest(project: bool) -> Path:
+    base = Path.cwd() if project else Path.home()
+    return base / ".claude" / "skills"
+
+
+def agent_dest(project: bool) -> Path:
+    base = Path.cwd() if project else Path.home()
+    return base / ".claude" / "agents"
+
+
+def install_source(entry: dict, dest_root: Path) -> Path:
+    """Download the entry's source directory from GitHub into dest_root/<id>."""
+    source = entry["source"]
+    dest = dest_root / entry["id"]
+    dest.mkdir(parents=True, exist_ok=True)
+    _download_dir(source["repo"], source["path"], source.get("ref"), dest)
+    return dest
+
+
+def _list_contents(repo: str, path: str, ref: str | None) -> list[dict]:
+    response = httpx.get(
+        f"{GITHUB_API}/repos/{repo}/contents/{path}",
+        params={"ref": ref} if ref else None,
+        headers={"Accept": "application/vnd.github+json"},
+        follow_redirects=True,
+        timeout=30,
+    )
+    response.raise_for_status()
+    data = response.json()
+    return data if isinstance(data, list) else [data]
+
+
+def _download_dir(repo: str, path: str, ref: str | None, dest: Path) -> None:
+    for item in _list_contents(repo, path, ref):
+        if item["type"] == "dir":
+            subdir = dest / item["name"]
+            subdir.mkdir(exist_ok=True)
+            _download_dir(repo, item["path"], ref, subdir)
+        elif item["type"] == "file" and item.get("download_url"):
+            response = httpx.get(item["download_url"], follow_redirects=True, timeout=30)
+            response.raise_for_status()
+            (dest / item["name"]).write_bytes(response.content)
+
+
+def install_mcp(entry: dict, config_path: Path | None = None) -> Path:
+    """Merge the entry's MCP server definition into the project's .mcp.json."""
+    config_path = config_path or Path.cwd() / ".mcp.json"
+    config = json.loads(config_path.read_text(encoding="utf-8")) if config_path.exists() else {}
+    servers = config.setdefault("mcpServers", {})
+    mcp = entry["mcp"]
+    servers[entry["id"]] = {key: mcp[key] for key in MCP_SERVER_KEYS if mcp.get(key)}
+    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    return config_path

skilldex/registry.py

@@ -0,0 +1,98 @@
+"""Fetching, caching, and searching the skilldex registry index."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+import httpx
+
+# GitHub Pages is primary — raw.githubusercontent's CDN can pin stale variants
+# for a long time, which made freshly merged entries invisible to the CLI.
+DEFAULT_INDEX_URL = "https://drewn-ed.github.io/skilldex-registry/index.json"
+FALLBACK_INDEX_URL = (
+    "https://raw.githubusercontent.com/drewn-ed/skilldex-registry/main/index.json"
+)
+CACHE_TTL_SECONDS = 3600
+CACHE_PATH = Path.home() / ".cache" / "skilldex" / "index.json"
+
+
+def index_url() -> str:
+    return os.environ.get("SKILLDEX_REGISTRY_URL", DEFAULT_INDEX_URL)
+
+
+def fetch_index(force: bool = False) -> dict:
+    """Return the registry index, using a local cache with a 1-hour TTL.
+
+    SKILLDEX_REGISTRY_URL may point at an alternative index — either an
+    https:// URL or a local file path (useful for registry development).
+    """
+    url = index_url()
+    local = Path(url)
+    if not url.startswith(("http://", "https://")) and local.exists():
+        return json.loads(local.read_text(encoding="utf-8"))
+
+    if (
+        not force
+        and CACHE_PATH.exists()
+        and time.time() - CACHE_PATH.stat().st_mtime < CACHE_TTL_SECONDS
+    ):
+        try:
+            return json.loads(CACHE_PATH.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass  # fall through to a fresh fetch
+
+    try:
+        response = httpx.get(url, follow_redirects=True, timeout=15)
+        response.raise_for_status()
+        data = response.json()
+    except (httpx.HTTPError, json.JSONDecodeError):
+        if url != DEFAULT_INDEX_URL:  # custom URL: no fallback, surface the error
+            raise
+        response = httpx.get(FALLBACK_INDEX_URL, follow_redirects=True, timeout=15)
+        response.raise_for_status()
+        data = response.json()
+    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CACHE_PATH.write_text(json.dumps(data), encoding="utf-8")
+    return data
+
+
+def search(index: dict, query: str, etype: str | None = None) -> list[dict]:
+    """Case-insensitive all-tokens-match search over id, name, description, and tags."""
+    tokens = query.lower().split()
+    results = []
+    for entry in index.get("entries", []):
+        if etype and entry.get("type") != etype:
+            continue
+        haystack = " ".join(
+            [
+                entry.get("id", ""),
+                entry.get("name", ""),
+                entry.get("description", ""),
+                " ".join(entry.get("tags", [])),
+            ]
+        ).lower()
+        if all(token in haystack for token in tokens):
+            results.append(entry)
+    return results
+
+
+def get_entry(index: dict, entry_id: str) -> dict | None:
+    for entry in index.get("entries", []):
+        if entry.get("id") == entry_id:
+            return entry
+    return None
+
+
+def get_entry_fresh(index: dict, entry_id: str, refetch=fetch_index) -> dict | None:
+    """Like get_entry, but on a miss refetch the index once — the local cache
+    (or a CDN edge) may predate a just-merged entry."""
+    entry = get_entry(index, entry_id)
+    if entry is None:
+        try:
+            entry = get_entry(refetch(force=True), entry_id)
+        except (httpx.HTTPError, json.JSONDecodeError, OSError):
+            return None
+    return entry

skilldex/validator.py

@@ -0,0 +1,187 @@
+"""Validation for registry entries, SKILL.md files, and subagent definition files."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+ENTRY_TYPES = {"skill", "agent", "mcp"}
+ID_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+REPO_RE = re.compile(r"^[\w.-]+/[\w.-]+$")
+
+REQUIRED_COMMON = ("id", "type", "name", "description")
+MAX_NAME = 64
+MAX_DESCRIPTION = 1024
+MAX_BODY_WORDS = 5000
+
+# Common credential shapes: OpenAI/Anthropic-style keys, GitHub tokens, Slack tokens,
+# AWS access keys, and JWTs.
+SECRET_RE = re.compile(
+    r"(sk-[A-Za-z0-9_-]{8,}"
+    r"|ghp_[A-Za-z0-9]{20,}"
+    r"|github_pat_[A-Za-z0-9_]{20,}"
+    r"|xox[baprs]-[A-Za-z0-9-]{10,}"
+    r"|AKIA[A-Z0-9]{12,}"
+    r"|eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{5,})"
+)
+
+FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?(.*)\Z", re.S)
+
+
+def looks_like_secret(value: object) -> bool:
+    return isinstance(value, str) and bool(SECRET_RE.search(value))
+
+
+def parse_frontmatter(text: str) -> tuple[dict | None, str]:
+    """Split a markdown document into (frontmatter dict, body).
+
+    Returns (None, text) when there is no frontmatter block.
+    Raises ValueError on malformed YAML or a non-mapping frontmatter.
+    """
+    match = FRONTMATTER_RE.match(text)
+    if not match:
+        return None, text
+    try:
+        data = yaml.safe_load(match.group(1))
+    except yaml.YAMLError as exc:
+        raise ValueError(f"invalid YAML frontmatter: {exc}") from exc
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise ValueError("frontmatter must be a YAML mapping")
+    return data, match.group(2)
+
+
+def validate_entry(entry: dict, *, filename: str | None = None) -> list[str]:
+    """Validate a skilldex registry entry. Returns a list of error strings."""
+    errors: list[str] = []
+    for field in REQUIRED_COMMON:
+        if not entry.get(field):
+            errors.append(f"missing required field: {field}")
+
+    etype = entry.get("type")
+    if etype and etype not in ENTRY_TYPES:
+        errors.append(f"invalid type {etype!r}, must be one of: {', '.join(sorted(ENTRY_TYPES))}")
+
+    eid = entry.get("id")
+    if eid:
+        if not ID_RE.match(str(eid)):
+            errors.append(f"id {eid!r} must be kebab-case (lowercase letters, digits, hyphens)")
+        if filename and Path(filename).stem != eid:
+            errors.append(f"id {eid!r} must match filename {Path(filename).name!r}")
+
+    description = entry.get("description") or ""
+    if len(description) > MAX_DESCRIPTION:
+        errors.append(f"description longer than {MAX_DESCRIPTION} characters")
+
+    tags = entry.get("tags")
+    if tags is not None and not (isinstance(tags, list) and all(isinstance(t, str) for t in tags)):
+        errors.append("tags must be a list of strings")
+
+    if etype in ("skill", "agent"):
+        source = entry.get("source") or {}
+        repo = source.get("repo")
+        if not repo:
+            errors.append(f"{etype} entries need source.repo ('owner/repo')")
+        elif not REPO_RE.match(repo):
+            errors.append(f"source.repo {repo!r} must look like 'owner/repo'")
+        if not source.get("path"):
+            errors.append(f"{etype} entries need source.path (directory within the repo)")
+
+    if etype == "mcp":
+        mcp = entry.get("mcp") or {}
+        transport = mcp.get("type", "stdio")
+        if transport == "stdio":
+            if not mcp.get("command"):
+                errors.append("mcp stdio entries need mcp.command")
+        elif transport in ("http", "sse"):
+            if not mcp.get("url"):
+                errors.append(f"mcp {transport} entries need mcp.url")
+        else:
+            errors.append(f"mcp.type {transport!r} must be stdio, http, or sse")
+        for key, value in (mcp.get("env") or {}).items():
+            if looks_like_secret(value):
+                errors.append(
+                    f"mcp.env.{key} looks like a hardcoded secret — use a ${{VAR}} placeholder"
+                )
+
+    return errors
+
+
+def validate_skill_md(path: Path) -> list[str]:
+    """Validate a Claude Code SKILL.md file. Returns hard errors only."""
+    return check_skill_md(path)[0]
+
+
+def check_skill_md(path: Path) -> tuple[list[str], list[str]]:
+    """Full SKILL.md check. Returns (errors, warnings).
+
+    Errors break the skill (Claude won't load or trigger it correctly);
+    warnings are best-practice advice.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return [f"cannot read file: {exc}"], []
+    try:
+        frontmatter, body = parse_frontmatter(text)
+    except ValueError as exc:
+        return [str(exc)], []
+    if frontmatter is None:
+        return ["missing YAML frontmatter ('---' block) at the top of SKILL.md"], []
+
+    errors: list[str] = []
+    warnings: list[str] = []
+    name = frontmatter.get("name")
+    if not name:
+        errors.append("frontmatter missing 'name'")
+    else:
+        name = str(name)
+        if not ID_RE.match(name):
+            errors.append(f"name {name!r} should be kebab-case")
+        if len(name) > MAX_NAME:
+            errors.append(f"name longer than {MAX_NAME} characters")
+
+    description = frontmatter.get("description")
+    if not description:
+        errors.append(
+            "frontmatter missing 'description' — Claude uses it to decide when to load the skill"
+        )
+    elif len(str(description)) > MAX_DESCRIPTION:
+        errors.append(f"description longer than {MAX_DESCRIPTION} characters")
+
+    if not body.strip():
+        errors.append("SKILL.md body is empty")
+    elif len(body.split()) > MAX_BODY_WORDS:
+        warnings.append(
+            f"body over {MAX_BODY_WORDS} words — consider moving details into files "
+            "the skill references"
+        )
+    return errors, warnings
+
+
+def validate_agent_md(path: Path) -> list[str]:
+    """Validate a Claude Code subagent definition (.md with frontmatter)."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return [f"cannot read file: {exc}"]
+    try:
+        frontmatter, body = parse_frontmatter(text)
+    except ValueError as exc:
+        return [str(exc)]
+    if frontmatter is None:
+        return ["missing YAML frontmatter ('---' block) at the top of the agent file"]
+
+    errors: list[str] = []
+    if not frontmatter.get("name"):
+        errors.append("frontmatter missing 'name'")
+    if not frontmatter.get("description"):
+        errors.append(
+            "frontmatter missing 'description' — Claude uses it to decide when to delegate"
+        )
+    if not body.strip():
+        errors.append("agent file has no system prompt body")
+    return errors

skilldex-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: skilldex
+Version: 0.1.0
+Summary: Search, install, validate, and audit Claude Code skills, subagents, and MCP servers from a community registry.
+Project-URL: Homepage, https://github.com/drewn-ed/skilldex
+Project-URL: Registry, https://github.com/drewn-ed/skilldex-registry
+Author-email: David Cecko <ceckodavid@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,cli,mcp,registry,skills,subagents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# skilldex
+
+[![CI](https://github.com/drewn-ed/skilldex/actions/workflows/ci.yml/badge.svg)](https://github.com/drewn-ed/skilldex/actions/workflows/ci.yml)
+
+**Search, install, validate, and audit Claude Code skills, subagents, and MCP servers — from one community registry.**
+
+Claude Code extensions live scattered across hundreds of repos. skilldex gives you a package-manager-style workflow for all three extension types:
+
+```bash
+# no install needed
+uvx skilldex search pdf
+uvx skilldex install pdf              # → ~/.claude/skills/pdf
+uvx skilldex install fetch            # MCP server → ./.mcp.json
+uvx skilldex install code-reviewer -p # subagent → ./.claude/agents (project scope)
+```
+
+Entries come from the community-maintained [skilldex-registry](https://github.com/drewn-ed/skilldex-registry) — every entry is CI-validated before it's merged. Browse it in your browser at [drewn-ed.github.io/skilldex-registry](https://drewn-ed.github.io/skilldex-registry/).
+
+## Install
+
+```bash
+pip install skilldex        # or: uv tool install skilldex
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `skilldex search <query> [-t skill\|agent\|mcp]` | Search the registry |
+| `skilldex show <id>` | Full registry entry as JSON |
+| `skilldex install <id> [--project]` | Install a skill/agent (user or project scope) or add an MCP server to `.mcp.json` |
+| `skilldex list` | Everything installed locally |
+| `skilldex validate <path>` | Lint a `SKILL.md`, subagent `.md`, or registry entry `.json` |
+| `skilldex audit` | Scan local Claude Code config for problems (broken frontmatter, plaintext secrets in `.mcp.json`, …) |
+
+## Why validate/audit?
+
+- A skill with a bad `description` silently never triggers — `validate` catches the common frontmatter mistakes before you wonder why.
+- `.mcp.json` is usually committed to git; `audit` flags API keys pasted where a `${VAR}` placeholder belongs.
+
+## Registry
+
+Want your skill, subagent, or MCP server listed? Open a PR adding one JSON file to
+[skilldex-registry](https://github.com/drewn-ed/skilldex-registry) — CI validates it automatically,
+and `skilldex validate` runs the same checks locally.
+
+Point the CLI at a different (or local) index with `SKILLDEX_REGISTRY_URL`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+MIT licensed. Not affiliated with Anthropic.

skilldex-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+skilldex/__init__.py,sha256=pC6sy16PemVhydZCFsIjURLqmZSpcQ9cRerqxBfcDDc,127
+skilldex/__main__.py,sha256=gBinljzlCpfT7P987YhgW8nT_zAe4rlYTmyFkrd9fDA,74
+skilldex/audit.py,sha256=EO5jmJXC_k6WTN44PJhoy7tnVxQSkje4KVtZAB-wiZQ,2549
+skilldex/cli.py,sha256=RuVgJpR64hDKejbqUWpmkzSK2FqlA5oyCpebatuEgCw,7113
+skilldex/installer.py,sha256=UsoQnYU_hKQ4JyajpBv-d7-W_B52lYEUDOM4FTWKOOI,2436
+skilldex/registry.py,sha256=pUgOB2W4jDSNwLpVZt7SveON3RCBo0zCVgNqq051RZM,3400
+skilldex/validator.py,sha256=Mzie7Fox7sltnTBBNHdWrgp3ICZT5VR73uPKfXFvas8,6729
+skilldex-0.1.0.dist-info/METADATA,sha256=9WR8K7060GAAB0GEDkyeTEiaMzgPjMbOMvR4rJH3FX4,3569
+skilldex-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+skilldex-0.1.0.dist-info/entry_points.txt,sha256=A5ozl-jtsUswj_Ak20HxAcvl1yeY9f4D-CFAvJU7km0,46
+skilldex-0.1.0.dist-info/licenses/LICENSE,sha256=j17hvurdyFCR3-s_NXj2Zf-CmKRWPzAocPyn3WJRxSM,1068
+skilldex-0.1.0.dist-info/RECORD,,

skilldex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

skilldex-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skilldex = skilldex.cli:app

skilldex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Cecko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.