claude-skill-forge 0.1.0__py3-none-any.whl

claude_skill_forge-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: claude-skill-forge
+Version: 0.1.0
+Summary: Turn a codebase, package, or doc into a valid Claude SKILL.md — offline, deterministic, and valid by construction. Optional Claude refinement. Zero runtime dependencies.
+Project-URL: Homepage, https://github.com/shaxzodbek-uzb/skill-forge
+Project-URL: Repository, https://github.com/shaxzodbek-uzb/skill-forge
+Project-URL: Issues, https://github.com/shaxzodbek-uzb/skill-forge/issues
+Author-email: Shaxzodbek Sobirov <shaxzodbek@blaze.uz>
+License: MIT
+License-File: LICENSE
+Keywords: agent,anthropic,claude,cli,codegen,linter,mcp,scaffold,skill-md,skills
+Classifier: Development Status :: 4 - Beta
+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 :: Code Generators
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# skill-forge
+
+**Point it at your code. Get a valid Claude skill. No API key required.**
+
+`skill-forge` turns a codebase, package, or doc into a well-formed Claude
+[`SKILL.md`](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) — and the
+skill it writes is **valid by construction**.
+
+```bash
+pip install claude-skill-forge       # the CLI it installs is `skill-forge`
+skill-forge forge ./my-tool          # writes .claude/skills/my-tool/SKILL.md
+```
+
+[![CI](https://github.com/shaxzodbek-uzb/skill-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/shaxzodbek-uzb/skill-forge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/claude-skill-forge)](https://pypi.org/project/claude-skill-forge/)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Dependencies](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
+
+---
+
+## Why
+
+Writing a good skill is fiddly: the frontmatter has to be exactly right, the `name` has to
+match its directory, and the `description` — the one field an agent actually reads to
+decide *whether to load the skill* — has to say **when** to trigger, inside a tight
+character budget. Get any of it wrong and the skill is silently undiscoverable.
+
+Most "ask an LLM to write my SKILL.md" approaches are non-reproducible, need an API key,
+and still emit invalid frontmatter. `skill-forge` is different on two axes:
+
+1. **Offline & deterministic by default.** It reads your source with static analysis — no
+   code execution, no network, no key — and emits the skill. Same input → same output.
+   The optional `--llm` flag only *refines* the prose; it never owns the structure.
+2. **Valid by construction.** Every generated skill passes the built-in linter (the same
+   rules a skill must satisfy to be discoverable). `skill-forge` refuses to write a skill
+   that doesn't lint clean, so you never ship a broken one.
+
+It's the *forge* half of a pair: **forge generates, `skillcheck` checks.** The linter is
+bundled here too (`skill-forge lint`) so the tool stands alone.
+
+## Install
+
+The package is published on PyPI as **`claude-skill-forge`**; it installs a CLI named
+`skill-forge` (and the import package is `skill_forge`).
+
+```bash
+pip install claude-skill-forge               # core: zero runtime dependencies
+pip install 'claude-skill-forge[anthropic]'  # adds the optional --llm refiner
+```
+
+## Quickstart (30 seconds)
+
+```bash
+# From a Python/Node project, a package, or a single doc:
+skill-forge forge ./my-tool                 # -> .claude/skills/my-tool/SKILL.md
+skill-forge forge ./README.md               # generate from docs
+skill-forge forge ./pkg --name my-skill     # override the skill name
+skill-forge forge ./my-tool --stdout        # preview, don't write
+skill-forge forge ./my-tool --llm           # sharpen the prose with Claude
+
+# Validate any skill / folder of skills (the bundled checker):
+skill-forge lint .claude/skills
+
+# CI drift guard — fail if the skill no longer matches the code:
+skill-forge check ./my-tool --name my-tool
+```
+
+### What it extracts
+
+| Source | What it reads |
+| --- | --- |
+| **Python** | `pyproject.toml` / `setup.cfg` (name, description, keywords, `[project.scripts]`), `__all__` and public defs/classes via `ast`, and argparse / click / typer subcommands — **never importing or running your code** |
+| **Node** | `package.json` (name, description, keywords, `bin`), TS/JS detection, README |
+| **Docs** | A markdown/rst/txt file: H1 title, first paragraph, section headings, fenced code blocks |
+| **Any directory** | README + a language histogram of the file tree |
+| **A CLI tool** | `skill-forge forge --from-cli "mytool"` captures and parses `mytool --help` |
+
+The result is a complete `SKILL.md`: trigger-oriented `description`, a `## When to use`
+section, an overview, and `## Commands` / `## API` / `## Usage` sections built from what was
+found.
+
+## Use it from Python
+
+```python
+from skill_forge import forge, render_skill, write_skill
+
+draft = forge("./my-tool")          # a validated SkillDraft
+print(render_skill(draft))          # the SKILL.md text
+write_skill(draft, ".claude/skills")
+```
+
+## The `--llm` refiner (optional)
+
+`--llm` sends the *extracted signals* (not your source) to Claude to sharpen the
+description's trigger phrasing and tighten the body. It is fail-safe: if the model is
+unavailable it tells you how to fix it, and if its output is anything but a valid
+improvement, `skill-forge` keeps the deterministic draft. You never get a worse skill than
+the offline path. Set `ANTHROPIC_API_KEY` and install the extra to use it.
+
+## CI: catch stale skills
+
+`skill-forge check` regenerates the skill in memory and diffs it against the one on disk,
+exiting non-zero if they differ — so a skill that drifted from the code it describes fails
+the build:
+
+```yaml
+- run: pip install claude-skill-forge
+- run: skill-forge check ./my-tool --name my-tool
+```
+
+## What this is **not**
+
+- **Not a replacement for judgment.** Generated skills are a strong *first draft*. The body
+  is assembled from your structure, not written from deep understanding — read it, trim it,
+  and add the hard-won "do this, not that" guidance only you know.
+- **Not a runtime.** It writes `SKILL.md` files; it does not execute skills.
+- **Not magic prose.** The offline path is deterministic and a little formulaic by design.
+  Reach for `--llm` when you want the description polished.
+- **It does not run your code.** The only time it executes anything is the explicit
+  `--from-cli` flag, which runs `<cmd> --help` with no shell and a timeout.
+
+## Configuration
+
+Environment overrides (all optional):
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SKILL_FORGE_OUTDIR` | `.claude/skills` | Default output directory |
+| `SKILL_FORGE_VERSION` | `0.1.0` | Version stamped on generated skills |
+| `SKILL_FORGE_MODEL_ID` | `claude-haiku-4-5` | Model used by `--llm` |
+| `ANTHROPIC_API_KEY` | — | Required for `--llm` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest -q
+```
+
+The design is pinned in [`SPEC.md`](SPEC.md) — the single source of truth for the public
+API and behavior. See [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a PR.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

claude_skill_forge-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+skill_forge/__init__.py,sha256=7-E4iGGc7xl6g9j3_m5iju1l5FeUEeSpDkezAK39AdA,1401
+skill_forge/cli.py,sha256=GzgSBneJ8GC_PW4WkgSEoVkfuU7on6zre9EDedV9nL0,6174
+skill_forge/config.py,sha256=qMMiFX9Abj2plW_JwH7FtxbEtig5L8JGqn6My2Qlp3M,1067
+skill_forge/describe.py,sha256=zyUqZJb7aVWTWQLsa8J5bvlm77_PYDvdi29efbpEauM,3518
+skill_forge/errors.py,sha256=qobC-rCE8q7tVTgDxnVxdTQfIygazVkyvGGGT_nSMuE,809
+skill_forge/frontmatter.py,sha256=YFjSBpZh1nnmIhlYxXIfDDxEIp5EOf_krXyrBeb9A_8,2722
+skill_forge/generate.py,sha256=QttjLf_M7vgbcfFhnM6vQSuRjaBsUmPLDa_VeoSM9y4,2735
+skill_forge/llm.py,sha256=fgx0H8OTuVM0_tgRK-bx9gSmvq-cRj06O28foXrTb14,4163
+skill_forge/models.py,sha256=VqVFo5IIn_BELp1X5wxACL-OvAdeai2HpdFgzirjewE,1661
+skill_forge/skill.py,sha256=FNmYUsGgr0pJWEsivXVmxBsXEhZANgUO_TK05y6ya_c,1488
+skill_forge/slug.py,sha256=imTrlcTtIFLRp9_mZ0oiEA1LbTkJpuI7wZGQs1JWCAk,1541
+skill_forge/templates.py,sha256=RIszOb1vMxQoYmvUIV9w0Rcy27NETDnazz8bjNKNsOQ,5228
+skill_forge/validate.py,sha256=jT2R9TPmLH-uTR2dsrYxN5xTWHlgwKA3hxA3fIlgvc0,4911
+skill_forge/analyzers/__init__.py,sha256=muIf5Ndzh_k32WB0xlODihZhcf0INMiqRPB2A44cw0k,2158
+skill_forge/analyzers/base.py,sha256=vu780bnqFUdBGHNi-WDbRh8nE7tI4ohrQZP69pN3wj8,6542
+skill_forge/analyzers/cli_help.py,sha256=29waB_5VHelSNrI9v6L13h1xE6bmNf-kOVsgNrXtsto,3602
+skill_forge/analyzers/docs.py,sha256=YPFRTPgLc7l8JuAjNUuOS3WjTvQGlGFFIxkU7DNWsMw,1130
+skill_forge/analyzers/generic.py,sha256=Qmz6XN9dvgGBxI-HkQ2LoJ1VicPskshzbBbG4EehY-c,1208
+skill_forge/analyzers/node.py,sha256=wBYOh4pvgJr_YrRG4nYyAJ5Ni9X5uJqCaRBSV86ovGs,2296
+skill_forge/analyzers/python.py,sha256=S2XMZ3Rym5rnLT6Dl037sKbjQojPxmQbLjyLguKcWAg,11877
+claude_skill_forge-0.1.0.dist-info/METADATA,sha256=u6_K-BEDxJgWPegoxT42tmQV82QToK8MxYMnn5CG9j0,7771
+claude_skill_forge-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+claude_skill_forge-0.1.0.dist-info/entry_points.txt,sha256=NqV9C-Qsp50k254PqKe5qyI-LgPBsoTXlD0pLUMIjZQ,53
+claude_skill_forge-0.1.0.dist-info/licenses/LICENSE,sha256=xuVZOvGxq8qpZlpQ_VjFMSwc44vsEidNj65gBKDY7Fs,1083
+claude_skill_forge-0.1.0.dist-info/RECORD,,

claude_skill_forge-0.1.0.dist-info/WHEEL

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

claude_skill_forge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skill-forge = skill_forge.cli:main

claude_skill_forge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaxzodbek Sobirov / Blaze
+
+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.

skill_forge/__init__.py

@@ -0,0 +1,56 @@
+"""skill-forge — turn a codebase, package, or doc into a valid Claude SKILL.md.
+
+The deterministic path (analyze → draft → validate) is offline and dependency-free; the
+optional ``--llm`` refinement is the only thing that needs the ``anthropic`` extra.
+"""
+
+from __future__ import annotations
+
+from .analyzers import analyze, detect
+from .config import Settings
+from .describe import build_description
+from .errors import (
+    AnalyzerError,
+    InvalidSkill,
+    LLMUnavailable,
+    SkillForgeError,
+    SourceNotFound,
+)
+from .generate import draft_from_signals, forge
+from .llm import refine_with_llm
+from .models import Command, SkillDraft, SourceSignals
+from .skill import render_skill, write_skill
+from .slug import is_kebab_case, slugify
+from .templates import build_body
+from .validate import LintResult, Problem, lint_path, lint_skill_file, lint_text
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "forge",
+    "draft_from_signals",
+    "SkillDraft",
+    "SourceSignals",
+    "Command",
+    "Settings",
+    "render_skill",
+    "write_skill",
+    "analyze",
+    "detect",
+    "build_description",
+    "build_body",
+    "lint_text",
+    "lint_skill_file",
+    "lint_path",
+    "LintResult",
+    "Problem",
+    "slugify",
+    "is_kebab_case",
+    "refine_with_llm",
+    "SkillForgeError",
+    "SourceNotFound",
+    "AnalyzerError",
+    "InvalidSkill",
+    "LLMUnavailable",
+    "__version__",
+]

skill_forge/analyzers/__init__.py

@@ -0,0 +1,66 @@
+"""Source detection and analyzer dispatch.
+
+``detect()`` picks an analyzer kind from a path; ``analyze()`` runs it. The CLI-help
+capture lives in :mod:`cli_help` and is intentionally *not* wired into detection — it only
+runs on the explicit ``--from-cli`` flag.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..errors import AnalyzerError, SourceNotFound
+from ..models import SourceSignals
+from ..slug import slugify
+from . import docs, generic, node, python
+
+_DOC_SUFFIXES = {".md", ".markdown", ".rst", ".txt"}
+
+_ANALYZERS = {
+    "python": python.analyze,
+    "node": node.analyze,
+    "docs": docs.analyze,
+    "generic": generic.analyze,
+}
+
+
+def detect(source: str | Path) -> str:
+    """Return the analyzer kind for ``source`` (``python|node|docs|generic``)."""
+    p = Path(source)
+    if not p.exists():
+        raise SourceNotFound(f"source does not exist: {p}")
+    if p.is_file():
+        if p.suffix == ".py":
+            return "python"
+        if p.suffix.lower() in _DOC_SUFFIXES:
+            return "docs"
+        return "docs"
+    if (p / "package.json").is_file():
+        return "node"
+    if any((p / m).is_file() for m in ("pyproject.toml", "setup.py", "setup.cfg")):
+        return "python"
+    if list(p.glob("*.py")) or list(p.glob("*/*.py")):
+        return "python"
+    return "generic"
+
+
+def analyze(source: str | Path, *, kind: str | None = None) -> SourceSignals:
+    """Dispatch to the matching analyzer and return its signals."""
+    p = Path(source)
+    if not p.exists():
+        raise SourceNotFound(f"source does not exist: {p}")
+    chosen = kind or detect(p)
+    func = _ANALYZERS.get(chosen)
+    if func is None:
+        raise AnalyzerError(f"unknown analyzer kind: {chosen!r}")
+    signals = func(p)
+    if not signals.name or not signals.name.strip():
+        raise AnalyzerError(f"could not determine a name from {p}")
+    try:
+        slugify(signals.name)
+    except ValueError as exc:
+        raise AnalyzerError(
+            f"could not derive a usable skill name from {p} (name {signals.name!r}); "
+            "pass --name to set one explicitly"
+        ) from exc
+    return signals

skill_forge/analyzers/base.py

@@ -0,0 +1,203 @@
+"""Shared, dependency-free helpers for the analyzers.
+
+Everything here is pure text processing over files already on disk — no network, no code
+execution.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+README_NAMES = [
+    "README.md",
+    "README.markdown",
+    "README.rst",
+    "README.txt",
+    "README",
+    "readme.md",
+]
+
+EXT_LANGUAGE = {
+    ".py": "Python",
+    ".js": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".jsx": "JavaScript",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".sh": "Shell",
+    ".c": "C",
+    ".cpp": "C++",
+    ".cs": "C#",
+}
+
+_STOPWORDS = {
+    "the", "a", "an", "and", "or", "for", "with", "to", "of", "in", "on", "is", "are",
+    "your", "you", "this", "that", "it", "as", "by", "be", "can", "from", "into", "via",
+    "using", "use", "used", "uses", "any", "all", "not", "no", "yes", "tool", "library",
+    "package", "project", "simple", "easy", "fast", "small", "based",
+    # Low-signal filler that tends to leak from prose summaries / headings.
+    "single", "source", "truth", "turns", "point", "required", "valid", "canonical",
+    "well", "formed", "make", "makes", "made", "just", "also", "new", "one", "first",
+    "more", "most", "very", "really", "over", "get", "gets", "why", "out", "only",
+    "such", "when", "what", "how", "we", "us", "its", "their",
+}
+
+# Headings that are structural/boilerplate, not real topics worth surfacing as triggers.
+STOP_HEADINGS = {
+    "install", "installation", "license", "licence", "contributing", "contribution",
+    "development", "configuration", "config", "why", "table of contents", "contents",
+    "changelog", "acknowledgements", "acknowledgments", "badges", "usage", "notes",
+    "getting started", "quickstart", "quick start", "overview", "requirements",
+    "features", "faq", "support", "credits", "authors", "roadmap", "todo", "examples",
+}
+
+_MD_MARKUP_RE = re.compile(r"[`*_]+")
+
+
+def strip_markdown(text: str) -> str:
+    """Remove inline emphasis/code markers and leading heading hashes; collapse whitespace."""
+    cleaned = _MD_MARKUP_RE.sub("", text or "")
+    cleaned = re.sub(r"^#+\s*", "", cleaned)
+    return re.sub(r"\s+", " ", cleaned).strip()
+
+
+def clean_section_titles(titles: list[str]) -> list[str]:
+    """Strip markup and drop boilerplate/duplicate section headings (for the Notes list)."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for title in titles:
+        cleaned = strip_markdown(title)
+        key = cleaned.lower()
+        if not cleaned or key in STOP_HEADINGS or key in seen:
+            continue
+        seen.add(key)
+        out.append(cleaned)
+    return out
+
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
+_FENCE_RE = re.compile(r"^\s*(```|~~~)")
+_WORD_RE = re.compile(r"[A-Za-z][A-Za-z0-9_+-]{1,}")
+
+
+def read_text(path: str | Path) -> str:
+    """Read a file as UTF-8, ignoring undecodable bytes; '' if unreadable."""
+    try:
+        return Path(path).read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ""
+
+
+def find_readme(directory: str | Path) -> Path | None:
+    """Return the first README-like file in ``directory``, or None."""
+    d = Path(directory)
+    for name in README_NAMES:
+        candidate = d / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _is_noise(line: str) -> bool:
+    """True for lines that should not seed a prose summary (badges, images, HTML, tables)."""
+    return (
+        line.startswith("![")
+        or line.startswith("[![")
+        or line.startswith("<")
+        or line.startswith("|")
+        or line.startswith(">")
+        or bool(re.fullmatch(r"[-=*_]{3,}", line))
+    )
+
+
+def parse_markdown(text: str) -> dict:
+    """Extract ``title``, ``summary``, ``headings`` (list of (level, text)), and
+    ``code_blocks`` (fenced block bodies) from markdown-ish text."""
+    title = ""
+    summary = ""
+    summary_done = False
+    headings: list[tuple[int, str]] = []
+    code_blocks: list[str] = []
+    para: list[str] = []
+    in_code = False
+    buf: list[str] = []
+
+    def flush_para() -> None:
+        nonlocal summary, summary_done
+        if para and not summary_done:
+            summary = " ".join(para).strip()
+            summary_done = True
+        para.clear()
+
+    for line in text.splitlines():
+        if _FENCE_RE.match(line):
+            if in_code:
+                code_blocks.append("\n".join(buf))
+                buf = []
+            in_code = not in_code
+            continue
+        if in_code:
+            buf.append(line)
+            continue
+
+        heading = _HEADING_RE.match(line)
+        if heading:
+            level = len(heading.group(1))
+            htext = heading.group(2).strip()
+            if level == 1 and not title:
+                title = htext
+            headings.append((level, htext))
+            flush_para()
+            continue
+
+        stripped = line.strip()
+        if stripped == "":
+            flush_para()
+            continue
+        if not summary_done and not _is_noise(stripped):
+            para.append(stripped)
+
+    if buf:
+        code_blocks.append("\n".join(buf))
+    flush_para()
+    return {"title": title, "summary": summary, "headings": headings, "code_blocks": code_blocks}
+
+
+def tokenize_keywords(*texts: str, limit: int = 12) -> list[str]:
+    """Pull distinct lowercase keyword tokens from free text, dropping stopwords."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for text in texts:
+        for match in _WORD_RE.findall(text or ""):
+            token = match.lower()
+            if token in _STOPWORDS or token in seen or len(token) < 3:
+                continue
+            seen.add(token)
+            out.append(token)
+            if len(out) >= limit:
+                return out
+    return out
+
+
+def guess_language(directory: str | Path) -> str | None:
+    """Guess the dominant language of a directory from its file extensions."""
+    skip = {".git", "node_modules", ".venv", "venv", "dist", "build"}
+    counts: dict[str, int] = {}
+    for path in Path(directory).rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in skip for part in path.parts):
+            continue
+        lang = EXT_LANGUAGE.get(path.suffix)
+        if lang:
+            counts[lang] = counts.get(lang, 0) + 1
+    if not counts:
+        return None
+    return max(counts, key=lambda k: counts[k])

skill_forge/analyzers/cli_help.py

@@ -0,0 +1,99 @@
+"""Build signals by capturing a CLI tool's ``--help`` output.
+
+This is the *one* place skill-forge runs an external process, and it only happens when the
+user explicitly passes ``--from-cli "<command>"``. The command is split with :func:`shlex.split`
+(no shell), ``--help`` is appended, and the call is timeout-guarded. We never auto-detect
+or auto-run anything.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+import subprocess
+
+from ..errors import AnalyzerError
+from ..models import Command, SourceSignals
+from .base import tokenize_keywords
+
+_USAGE_RE = re.compile(r"^\s*usage:", re.IGNORECASE)
+_SECTION_RE = re.compile(r"^\s*(commands|subcommands|available commands)\b", re.IGNORECASE)
+_ITEM_RE = re.compile(r"^\s{1,6}([a-z][\w-]*)\s{2,}(.+?)\s*$")
+_CHOICES_RE = re.compile(r"\{([a-z][\w,-]+)\}")
+
+
+def capture_cli_help(command: str, *, timeout: float = 10.0) -> SourceSignals:
+    """Run ``<command> --help`` (no shell) and parse it into signals."""
+    parts = shlex.split(command)
+    if not parts:
+        raise AnalyzerError("empty --from-cli command")
+    if parts[-1].startswith("-"):
+        raise AnalyzerError(
+            "--from-cli expects a program name, optionally a subcommand — not a flag: "
+            f"got {command!r}. Try `--from-cli \"{parts[0]}\"`."
+        )
+    try:
+        proc = subprocess.run(  # noqa: S603 - args are a parsed list, shell=False
+            [*parts, "--help"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise AnalyzerError(f"command not found: {parts[0]}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise AnalyzerError(f"`{parts[0]} --help` timed out after {timeout}s") from exc
+
+    text = (proc.stdout or "") + ("\n" + proc.stderr if proc.stderr else "")
+    if not text.strip():
+        raise AnalyzerError(f"`{parts[0]} --help` produced no output")
+
+    name = parts[-1] if len(parts) > 1 else parts[0].rsplit("/", 1)[-1]
+    summary, commands, notes = _parse_help(text)
+    keywords = tokenize_keywords(name, summary, " ".join(c.name for c in commands))
+
+    return SourceSignals(
+        name=name,
+        summary=summary,
+        kind="cli",
+        commands=commands,
+        keywords=keywords,
+        notes=notes,
+        usage=[text.strip()] if not commands else [],
+        source=f"`{command} --help`",
+    )
+
+
+def _parse_help(text: str) -> tuple[str, list[Command], list[str]]:
+    lines = text.splitlines()
+    summary = ""
+    commands: dict[str, Command] = {}
+    notes: list[str] = []
+    in_commands = False
+
+    for line in lines:
+        if _USAGE_RE.match(line):
+            in_commands = False
+            for group in _CHOICES_RE.findall(line):
+                for choice in group.split(","):
+                    choice = choice.strip()
+                    if choice:
+                        commands.setdefault(choice, Command(name=choice))
+            continue
+        if _SECTION_RE.match(line):
+            in_commands = True
+            continue
+        if in_commands:
+            item = _ITEM_RE.match(line)
+            if item:
+                name, help_text = item.group(1), item.group(2).strip()
+                commands.setdefault(name, Command(name=name, help=help_text))
+            elif line.strip() == "":
+                in_commands = False
+            continue
+        stripped = line.strip()
+        if not summary and stripped and not stripped.startswith("-"):
+            summary = stripped
+
+    return summary, list(commands.values()), notes