skilldex 0.1.0__tar.gz

skilldex-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

skilldex-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing — no tokens or passwords
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

skilldex-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

skilldex-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+Initial release.
+
+- `skilldex search / show` — query the community registry of Claude Code skills,
+  subagents, and MCP servers
+- `skilldex install <id> [--project]` — install skills into `~/.claude/skills`
+  (or `./.claude`), subagents into `agents/`, MCP servers into `./.mcp.json`
+- `skilldex list` — everything installed locally
+- `skilldex validate` — lint SKILL.md files, subagent files, and registry entries
+- `skilldex audit` — scan local Claude Code config for broken frontmatter and
+  plaintext secrets in `.mcp.json`
+- Registry index served from GitHub Pages with CDN-stale fallback and
+  refetch-on-miss, cached locally for 1 hour (`--refresh` to bypass,
+  `SKILLDEX_REGISTRY_URL` to override)

skilldex-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to skilldex
+
+PRs welcome — this project is intentionally small and readable.
+
+## Setup
+
+```bash
+git clone https://github.com/drewn-ed/skilldex
+cd skilldex
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"   # plain `pip install .` also works
+.venv/bin/pytest                     # tests run straight from src/
+.venv/bin/ruff check .
+```
+
+## Layout
+
+| File | What it does |
+|---|---|
+| `src/skilldex/cli.py` | Typer commands, Rich output |
+| `src/skilldex/registry.py` | index fetch/cache/search |
+| `src/skilldex/installer.py` | GitHub downloads, `.mcp.json` merging |
+| `src/skilldex/validator.py` | all validation rules + secret detection |
+| `src/skilldex/audit.py` | local config scanning |
+
+## Ground rules
+
+- Every behavior change comes with a test.
+- `ruff check .` and `pytest` must pass (CI runs them on 3.10/3.12/3.13).
+- Keep dependencies minimal — currently typer, rich, httpx, pyyaml.
+- Want to list your skill/agent/MCP server? That PR goes to
+  [skilldex-registry](https://github.com/drewn-ed/skilldex-registry), not here.

skilldex-0.1.0/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.

skilldex-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,57 @@
+# 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/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skilldex"
+version = "0.1.0"
+description = "Search, install, validate, and audit Claude Code skills, subagents, and MCP servers from a community registry."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "David Cecko", email = "ceckodavid@gmail.com" }]
+keywords = ["claude", "claude-code", "skills", "subagents", "mcp", "registry", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.0",
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+skilldex = "skilldex.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/drewn-ed/skilldex"
+Registry = "https://github.com/drewn-ed/skilldex-registry"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

skilldex-0.1.0/src/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-0.1.0/src/skilldex/__main__.py

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

skilldex-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_registry.py

@@ -0,0 +1,71 @@
+import json
+
+import httpx
+
+from skilldex.registry import fetch_index, get_entry, get_entry_fresh, search
+
+INDEX = {
+    "entries": [
+        {
+            "id": "pdf",
+            "type": "skill",
+            "name": "PDF Toolkit",
+            "description": "Extract text and tables from PDF files",
+            "tags": ["documents"],
+        },
+        {
+            "id": "fetch",
+            "type": "mcp",
+            "name": "Fetch",
+            "description": "Fetch web pages as markdown",
+            "tags": ["web", "http"],
+        },
+    ]
+}
+
+
+def test_search_matches_description():
+    assert [e["id"] for e in search(INDEX, "tables")] == ["pdf"]
+
+
+def test_search_matches_tags():
+    assert [e["id"] for e in search(INDEX, "http")] == ["fetch"]
+
+
+def test_search_all_tokens_must_match():
+    assert search(INDEX, "pdf web") == []
+
+
+def test_search_type_filter():
+    assert [e["id"] for e in search(INDEX, "f", etype="mcp")] == ["fetch"]
+
+
+def test_get_entry():
+    assert get_entry(INDEX, "pdf")["name"] == "PDF Toolkit"
+    assert get_entry(INDEX, "nope") is None
+
+
+def test_get_entry_fresh_hit_needs_no_refetch():
+    def boom(force=False):
+        raise AssertionError("should not refetch on a hit")
+
+    assert get_entry_fresh(INDEX, "pdf", refetch=boom)["name"] == "PDF Toolkit"
+
+
+def test_get_entry_fresh_refetches_on_miss():
+    fresh = {"entries": INDEX["entries"] + [{"id": "brand-new", "type": "skill", "name": "New"}]}
+    assert get_entry_fresh(INDEX, "brand-new", refetch=lambda force: fresh)["name"] == "New"
+
+
+def test_get_entry_fresh_miss_with_failing_refetch():
+    def fail(force=False):
+        raise httpx.ConnectError("offline")
+
+    assert get_entry_fresh(INDEX, "nope", refetch=fail) is None
+
+
+def test_fetch_index_local_path(tmp_path, monkeypatch):
+    index_file = tmp_path / "index.json"
+    index_file.write_text(json.dumps(INDEX))
+    monkeypatch.setenv("SKILLDEX_REGISTRY_URL", str(index_file))
+    assert fetch_index() == INDEX

skilldex-0.1.0/tests/test_validator.py

@@ -0,0 +1,151 @@
+from pathlib import Path
+
+from skilldex.validator import (
+    check_skill_md,
+    looks_like_secret,
+    parse_frontmatter,
+    validate_agent_md,
+    validate_entry,
+    validate_skill_md,
+)
+
+VALID_SKILL_ENTRY = {
+    "id": "pdf",
+    "type": "skill",
+    "name": "PDF Toolkit",
+    "description": "Work with PDFs.",
+    "source": {"repo": "anthropics/skills", "path": "skills/pdf"},
+}
+
+VALID_MCP_ENTRY = {
+    "id": "fetch",
+    "type": "mcp",
+    "name": "Fetch",
+    "description": "Fetch web pages.",
+    "mcp": {"type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"]},
+}
+
+
+def test_valid_skill_entry():
+    assert validate_entry(VALID_SKILL_ENTRY) == []
+
+
+def test_valid_mcp_entry():
+    assert validate_entry(VALID_MCP_ENTRY) == []
+
+
+def test_missing_fields():
+    errors = validate_entry({"id": "x"})
+    assert any("type" in e for e in errors)
+    assert any("name" in e for e in errors)
+    assert any("description" in e for e in errors)
+
+
+def test_bad_id_format():
+    entry = {**VALID_SKILL_ENTRY, "id": "Bad_ID"}
+    assert any("kebab-case" in e for e in validate_entry(entry))
+
+
+def test_id_must_match_filename():
+    errors = validate_entry(VALID_SKILL_ENTRY, filename="registry/skills/other.json")
+    assert any("match filename" in e for e in errors)
+    assert validate_entry(VALID_SKILL_ENTRY, filename="registry/skills/pdf.json") == []
+
+
+def test_skill_requires_source_repo():
+    entry = {**VALID_SKILL_ENTRY, "source": {"path": "skills/pdf"}}
+    assert any("source.repo" in e for e in validate_entry(entry))
+
+
+def test_mcp_http_requires_url():
+    entry = {**VALID_MCP_ENTRY, "mcp": {"type": "http"}}
+    assert any("mcp.url" in e for e in validate_entry(entry))
+
+
+def test_mcp_entry_rejects_hardcoded_secret():
+    entry = {
+        **VALID_MCP_ENTRY,
+        "mcp": {
+            "type": "stdio",
+            "command": "uvx",
+            "env": {"API_KEY": "sk-abcdefghijklmnop1234"},
+        },
+    }
+    assert any("secret" in e for e in validate_entry(entry))
+
+
+def test_looks_like_secret():
+    assert looks_like_secret("ghp_" + "a" * 30)
+    assert not looks_like_secret("${GITHUB_TOKEN}")
+
+
+def test_parse_frontmatter_roundtrip():
+    fm, body = parse_frontmatter("---\nname: x\n---\nbody here")
+    assert fm == {"name": "x"}
+    assert body == "body here"
+
+
+def test_parse_frontmatter_absent():
+    fm, body = parse_frontmatter("just a doc")
+    assert fm is None
+    assert body == "just a doc"
+
+
+def _write(tmp_path: Path, name: str, content: str) -> Path:
+    p = tmp_path / name
+    p.write_text(content, encoding="utf-8")
+    return p
+
+
+def test_valid_skill_md(tmp_path):
+    p = _write(
+        tmp_path,
+        "SKILL.md",
+        "---\nname: my-skill\ndescription: Does a thing when asked.\n---\n# Usage\nDo it.\n",
+    )
+    assert validate_skill_md(p) == []
+
+
+def test_skill_md_missing_frontmatter(tmp_path):
+    p = _write(tmp_path, "SKILL.md", "# No frontmatter here\n")
+    assert any("frontmatter" in e for e in validate_skill_md(p))
+
+
+def test_skill_md_bad_name(tmp_path):
+    p = _write(
+        tmp_path,
+        "SKILL.md",
+        "---\nname: My Skill\ndescription: ok\n---\nbody\n",
+    )
+    assert any("kebab-case" in e for e in validate_skill_md(p))
+
+
+def test_skill_md_long_body_is_warning_not_error(tmp_path):
+    body = "word " * 5001
+    p = _write(
+        tmp_path,
+        "SKILL.md",
+        f"---\nname: my-skill\ndescription: ok\n---\n{body}",
+    )
+    errors, warnings = check_skill_md(p)
+    assert errors == []
+    assert any("5000 words" in w for w in warnings)
+
+
+def test_skill_md_empty_body(tmp_path):
+    p = _write(tmp_path, "SKILL.md", "---\nname: my-skill\ndescription: ok\n---\n")
+    assert any("body is empty" in e for e in validate_skill_md(p))
+
+
+def test_agent_md_valid(tmp_path):
+    p = _write(
+        tmp_path,
+        "reviewer.md",
+        "---\nname: reviewer\ndescription: Reviews code.\n---\nYou are a code reviewer.\n",
+    )
+    assert validate_agent_md(p) == []
+
+
+def test_agent_md_missing_description(tmp_path):
+    p = _write(tmp_path, "reviewer.md", "---\nname: reviewer\n---\nprompt\n")
+    assert any("description" in e for e in validate_agent_md(p))