Add missing docs-skills skill descriptions

Signed-off-by: Aidan Reilly <aireilly@redhat.com>

Signed-off-by: Aidan Reilly <aireilly@redhat.com>

Signed-off-by: Aidan Reilly <aireilly@redhat.com>

rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED

Auto-discover docs-skills from source repo via GitHub API

Replace the manually-maintained skills list for docs-skills in
registry.yaml with automatic discovery from the source repository.
generate_site.py --fetch-remote-skills fetches SKILL.md frontmatter
in parallel and caches results in _discovered.yaml (gitignored).
The deploy workflow runs with the flag so the published site always
shows the full skills table with links to the source repo.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED

Author: aireilly

.github/workflows/deploy-site.yml

@@ -25,7 +25,12 @@ jobs:
           python-version: '3.12'
 
       - name: Install dependencies
-        run: pip install -r site/requirements.txt
+        run: |
+          pip install -r site/requirements.txt
+          pip install pyyaml
+
+      - name: Generate site content with remote skill discovery
+        run: python3 scripts/generate_site.py --fetch-remote-skills
 
       - name: Build site
         working-directory: site

.gitignore

@@ -1,9 +1,2 @@
-.venv/
-site/_site/
-__pycache__/
-*.pyc
-.idea/
-.cache/skills-registry/
-.tmp/
-site/docs/plugins/*/artifacts/
-*.DS_Store
+scripts/__pycache__/
+site/docs/plugins/*/_discovered.yaml

scripts/generate_site.py

@@ -10,9 +10,12 @@
 """
 
 import argparse
+import json
 import os
 import shutil
 import sys
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 import yaml
@@ -421,6 +424,7 @@ def generate_plugin_page(plugin: dict, registry: dict, enrichment: dict | None,
 
     # Skills table
     if skills:
+        is_discovered = plugin.get("_discovered", False)
         lines.append("## Skills")
         lines.append("")
         lines.append("| Skill | Description | Invocable |")
@@ -430,7 +434,13 @@ def generate_plugin_page(plugin: dict, registry: dict, enrichment: dict | None,
             sdesc = " ".join(skill.get("description", "").split())
             invocable = skill.get("user-invocable", True)
             badge = ":material-check:" if invocable else ":material-close: internal"
-            lines.append(f"| [`/{sname}`]({sname}.md) | {sdesc} | {badge} |")
+            if is_discovered and repo:
+                ref = plugin.get("source", {}).get("ref", "main")
+                skill_path = skill.get("path", sname)
+                link = f"https://github.com/{repo}/tree/{ref}/{skill_path}"
+                lines.append(f"| [`/{sname}`]({link}) | {sdesc} | {badge} |")
+            else:
+                lines.append(f"| [`/{sname}`]({sname}.md) | {sdesc} | {badge} |")
         lines.append("")
 
     # Agents table
@@ -770,6 +780,93 @@ def load_enrichment(plugin_dir: Path) -> dict | None:
     return None
 
 
+def _parse_frontmatter(content: str) -> dict:
+    """Parse YAML frontmatter from a SKILL.md file."""
+    content = content.lstrip()
+    if not content.startswith("---"):
+        return {}
+    end = content.find("\n---", 3)
+    if end == -1:
+        return {}
+    try:
+        return yaml.safe_load(content[3:end]) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def _github_get(url: str) -> bytes:
+    """HTTP GET with optional GitHub token auth."""
+    headers = {}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return resp.read()
+
+
+def discover_remote_skills(repo: str, ref: str = "main") -> list[dict]:
+    """Discover skills from a GitHub repo by fetching SKILL.md frontmatter."""
+    tree_url = f"https://api.github.com/repos/{repo}/git/trees/{ref}?recursive=1"
+    tree_data = json.loads(_github_get(tree_url))
+
+    if tree_data.get("truncated"):
+        print(f"    Warning: tree for {repo} was truncated, some skills may be missed")
+
+    skill_entries = []
+    for item in tree_data.get("tree", []):
+        if item["type"] == "blob" and item["path"].endswith("/SKILL.md"):
+            parent = item["path"].rsplit("/", 1)[0]
+            skill_name = parent.rsplit("/", 1)[-1]
+            skill_entries.append((skill_name, parent, item["path"]))
+
+    if not skill_entries:
+        return []
+
+    def fetch_one(entry):
+        skill_name, parent_path, full_path = entry
+        raw_url = f"https://raw.githubusercontent.com/{repo}/{ref}/{full_path}"
+        try:
+            content = _github_get(raw_url).decode("utf-8", errors="replace")
+            fm = _parse_frontmatter(content)
+            return {
+                "name": fm.get("name", skill_name),
+                "description": fm.get("description", ""),
+                "user-invocable": fm.get("user-invocable", True),
+                "path": parent_path,
+            }
+        except Exception:
+            return {
+                "name": skill_name,
+                "description": "",
+                "user-invocable": True,
+                "path": parent_path,
+            }
+
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        skills = list(pool.map(fetch_one, sorted(skill_entries)))
+
+    return skills
+
+
+def load_discovered(plugin_dir: Path) -> list[dict] | None:
+    """Load cached discovered skills from _discovered.yaml."""
+    path = plugin_dir / "_discovered.yaml"
+    if path.exists():
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        if isinstance(data, list):
+            return data
+    return None
+
+
+def save_discovered(plugin_dir: Path, skills: list[dict]) -> None:
+    """Write discovered skills cache."""
+    path = plugin_dir / "_discovered.yaml"
+    with open(path, "w") as f:
+        yaml.dump(skills, f, default_flow_style=False, sort_keys=False)
+
+
 def generate_mkdocs_yml(registry: dict, categories: dict,
                         cat_plugins: dict[str, list]) -> str:
     """Generate complete mkdocs.yml with dynamic nav."""
@@ -787,9 +884,10 @@ def generate_mkdocs_yml(registry: dict, categories: dict,
         skills = plugin.get("skills", [])
         nav_lines.append(f"    - {name}:")
         nav_lines.append(f"      - plugins/{name}/index.md")
-        for skill in skills:
-            sname = skill["name"]
-            nav_lines.append(f"      - {sname}: plugins/{name}/{sname}.md")
+        if not plugin.get("_discovered"):
+            for skill in skills:
+                sname = skill["name"]
+                nav_lines.append(f"      - {sname}: plugins/{name}/{sname}.md")
 
     # Categories section — with index page
     nav_lines.append("  - Categories:")
@@ -823,21 +921,37 @@ def generate_llms_txt(registry: dict, site_url: str) -> str:
     lines.append("")
     for p in plugins:
         pname = p["name"]
+        is_discovered = p.get("_discovered", False)
+        repo = p.get("source", {}).get("repo", "")
+        ref = p.get("source", {}).get("ref", "main")
         for s in p.get("skills", []):
             sname = s["name"]
             sdesc = s.get("description", "").strip()
             if s.get("user-invocable", True):
-                lines.append(f"- [{sname}]({site_url}/plugins/{pname}/{sname}/): {sdesc}")
+                if is_discovered and repo:
+                    skill_path = s.get("path", sname)
+                    link = f"https://github.com/{repo}/tree/{ref}/{skill_path}"
+                else:
+                    link = f"{site_url}/plugins/{pname}/{sname}/"
+                lines.append(f"- [{sname}]({link}): {sdesc}")
     lines.append("")
     lines.append("## Optional")
     lines.append("")
     for p in plugins:
         pname = p["name"]
+        is_discovered = p.get("_discovered", False)
+        repo = p.get("source", {}).get("repo", "")
+        ref = p.get("source", {}).get("ref", "main")
         for s in p.get("skills", []):
             if not s.get("user-invocable", True):
                 sname = s["name"]
                 sdesc = s.get("description", "").strip()
-                lines.append(f"- [{sname}]({site_url}/plugins/{pname}/{sname}/): {sdesc} (internal)")
+                if is_discovered and repo:
+                    skill_path = s.get("path", sname)
+                    link = f"https://github.com/{repo}/tree/{ref}/{skill_path}"
+                else:
+                    link = f"{site_url}/plugins/{pname}/{sname}/"
+                lines.append(f"- [{sname}]({link}): {sdesc} (internal)")
     lines.append("")
     return "\n".join(lines)
 
@@ -915,11 +1029,36 @@ def generate_llms_full_txt(registry: dict, docs_dir: Path) -> str:
     return "\n".join(lines)
 
 
-def generate_site(registry: dict, output_dir: Path):
+def generate_site(registry: dict, output_dir: Path, *,
+                  fetch_remote: bool = False):
     docs = output_dir / "docs"
     categories = registry.get("categories", {})
     cat_plugins = build_category_plugins(registry)
 
+    # Auto-discover skills before generating any pages (counts need to be accurate)
+    for plugin in registry.get("plugins", []):
+        if not plugin.get("skills"):
+            name = plugin["name"]
+            plugin_dir = docs / "plugins" / name
+            plugin_dir.mkdir(parents=True, exist_ok=True)
+            repo = plugin.get("source", {}).get("repo", "")
+            ref = plugin.get("source", {}).get("ref", "main")
+            discovered = load_discovered(plugin_dir)
+            if fetch_remote and repo:
+                print(f"  Discovering skills for {name} from {repo}...")
+                try:
+                    discovered = discover_remote_skills(repo, ref)
+                    save_discovered(plugin_dir, discovered)
+                    print(f"    Found {len(discovered)} skills")
+                except Exception as e:
+                    print(f"    Warning: {e}")
+            if discovered:
+                plugin["skills"] = discovered
+                plugin["_discovered"] = True
+
+    # Rebuild category groups after discovery so counts are accurate
+    cat_plugins = build_category_plugins(registry)
+
     # Clean generated content
     clean_generated(output_dir)
 
@@ -945,6 +1084,8 @@ def generate_site(registry: dict, output_dir: Path):
             generate_plugin_page(plugin, registry, enrichment, plugin_dir))
 
         for skill in plugin.get("skills", []):
+            if plugin.get("_discovered"):
+                continue
             sname = skill["name"]
             (plugin_dir / f"{sname}.md").write_text(
                 generate_skill_page(skill, plugin, enrichment, plugin_dir))
@@ -978,11 +1119,14 @@ def main() -> None:
         formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument("--registry", default="registry.yaml")
     parser.add_argument("--output-dir", default="site")
+    parser.add_argument("--fetch-remote-skills", action="store_true",
+                        help="Discover skills from source repos via GitHub API")
     args = parser.parse_args()
 
     registry = load_registry(args.registry)
     output_dir = Path(args.output_dir)
-    generate_site(registry, output_dir)
+    generate_site(registry, output_dir,
+                  fetch_remote=args.fetch_remote_skills)
 
     plugins = registry.get("plugins", [])
     skills = sum(len(p.get("skills", [])) for p in plugins)

site/docs/categories/documentation.md

@@ -21,4 +21,4 @@ Autonomous knowledge management skills for keeping AI context files (CLAUDE.md,
 
 Documentation review, writing, and workflow tools for AsciiDoc and Markdown documentation. Includes an orchestrated multi-step pipeline, standalone review skills, codebase analysis for onboarding, and JIRA/PR integration.
 
-**0 skills** - v0.3.0
+**49 skills** - v0.3.0

site/docs/index.md

@@ -10,7 +10,7 @@ hide:
 
 # Skills and plugins for AI-assisted software engineering workflows
 
-14 plugins | 75 skills | 7 categories
+14 plugins | 124 skills | 7 categories
 
 [Getting Started](getting-started.md){ .md-button .md-button--primary }
 
@@ -114,7 +114,7 @@ hide:
 
     Documentation review, writing, and workflow tools for AsciiDoc and Markdown documentation. Includes an orchestrated m...
 
-    **0 skills** - Documentation - v0.3.0
+    **49 skills** - Documentation - v0.3.0
 
 </div>