SkillSpector Input Formats: Handling Git, URLs, ZIP Archives, and Local Files

SkillSpector accepts five distinct input formats—Git repository URLs, raw file URLs, local ZIP archives, single Markdown files, and local directories—normalizing each into a local directory via the InputHandler.resolve() method.

SkillSpector, NVIDIA's open-source static analysis tool, ingests code from diverse sources through a unified normalization layer. The InputHandler class in src/skillspector/input_handler.py automatically detects the input type and prepares a local directory for scanning. Understanding these SkillSpector input formats ensures you can analyze repositories regardless of whether they live on GitHub, in a ZIP file, or on your local filesystem.

Supported SkillSpector Input Formats

The resolve method (lines 55-84 in src/skillspector/input_handler.py) implements detection logic for each source type. Here is how SkillSpector categorizes and handles each format.

Git Repository URLs

SkillSpector detects Git repositories by analyzing URL patterns. The _is_git_url logic (lines 105-117) identifies standard repository URLs such as https://github.com/user/repo or SSH-style git@github.com:user/repo formats. When detected, SkillSpector clones the repository to a temporary directory and returns the local path with the source type identifier "git".

Raw File URLs

Direct HTTP or HTTPS links to individual files are recognized by the _is_file_url method (lines 119-124). This format handles single-file sources like raw Markdown or script files hosted on GitHub's raw content domain or any direct file link. The handler downloads the file via _download_file (lines 150-168) and returns the temporary directory path with type "url".

Local ZIP Archives

Any path ending with .zip triggers archive processing. For local ZIP files, SkillSpector validates the path and extracts contents using _extract_zip (lines 173-188). If the ZIP resides at a remote URL, the handler first downloads it via _download_file before extraction. Both paths return a directory containing the decompressed contents and the type identifier "zip".

Single Markdown Files

Local or downloaded .md files receive special handling. When resolve detects the .endswith(".md") condition, it invokes _wrap_single_file (lines 191-199) to prepare the file for analysis. This ensures standalone documentation files are processed correctly, returning type "file".

Local Directories

Existing filesystem directories pass through unchanged. The Path(input_path).is_dir() branch in resolve validates the directory exists and returns the original path with type "directory". No copying or extraction occurs for this format.

Working with the InputHandler API

The InputHandler class provides a consistent interface for consuming all SkillSpector input formats. Each call to resolve() returns a tuple containing a Path object pointing to a scan-ready directory and a string indicating the detected source type.

from skillspector.input_handler import InputHandler

handler = InputHandler()

# 1. Git repository URL

repo_path, src_type = handler.resolve("https://github.com/example/project")
print(repo_path, src_type)   # → <temp>/repo  "git"

# 2. Raw file URL (markdown)

file_path, src_type = handler.resolve("https://raw.githubusercontent.com/example/project/main/README.md")
print(file_path, src_type)   # → <temp>  "url"

# 3. Local ZIP archive

zip_path, src_type = handler.resolve("/home/user/project.zip")
print(zip_path, src_type)    # → <temp>/extracted  "zip"

# 4. Single markdown file on disk

md_path, src_type = handler.resolve("/home/user/notes.md")
print(md_path, src_type)     # → <temp>  "file"

# 5. Local directory

dir_path, src_type = handler.resolve("/home/user/source-code")
print(dir_path, src_type)    # → /home/user/source-code  "directory"

# Clean up any temporary files created during the run

handler.cleanup()

The cleanup() method removes temporary directories created for Git clones, downloaded files, and extracted ZIP archives. Local directories and files passed by path are never deleted by this operation.

Input Processing Implementation Details

The module docstring (lines 19-25) documents the high-level flow: normalize any supported source into a local directory that can be scanned. The resolve method orchestrates this by sequentially checking conditions—Git URL, file URL, ZIP extension, Markdown extension, and directory existence—until a match occurs.

Once normalized, the returned path feeds into src/skillspector/graph.py for static and semantic analysis. The CLI entry point in src/skillspector/cli.py leverages this same InputHandler interface to accept user-provided paths from command-line arguments.

Unit tests in tests/unit/test_input_handler.py verify detection accuracy for each format, ensuring that URL parsing, archive extraction, and file wrapping behave correctly across platform variations.

Summary

• SkillSpector input formats include Git URLs, raw file URLs, ZIP archives, Markdown files, and local directories.
• The InputHandler.resolve() method in src/skillspector/input_handler.py normalizes all sources into scan-ready local directories.
• Git repositories are cloned to temporary storage using _is_git_url detection (lines 105-117).
• ZIP files are extracted via _extract_zip (lines 173-188) after potential download via _download_file (lines 150-168).
• Single Markdown files are wrapped using _wrap_single_file (lines 191-199) to ensure proper processing.
• Always invoke handler.cleanup() to remove temporary artifacts after analysis completes.

Frequently Asked Questions

Does SkillSpector support private Git repositories?

SkillSpector's InputHandler detects private repository URLs using the same _is_git_url logic as public repositories, but authentication depends on your system's Git configuration. If your SSH keys or Git credentials are configured locally, SkillSpector will clone private repositories during the resolve() call just like standard Git operations.

Can SkillSpector process ZIP files downloaded from URLs?

Yes. When you pass a URL ending in .zip to handler.resolve(), the _download_file method (lines 150-168) fetches the archive to a temporary location before _extract_zip (lines 173-188) decompresses it. This allows you to analyze compressed project archives hosted on any HTTP-accessible server without manual download steps.

What happens to temporary files after processing?

Temporary directories created for Git clones, downloaded files, and extracted ZIP archives persist until you explicitly call handler.cleanup(). Local directories and existing files passed by path are never modified or deleted. Always invoke cleanup() at the end of your analysis session to prevent disk space accumulation.

How does SkillSpector distinguish between a Git URL and a raw file URL?

The _is_git_url method (lines 105-117) checks for repository-specific patterns like github.com/user/repo or SSH git@ prefixes, while _is_file_url (lines 119-124) identifies direct file links including raw content domains. Raw file URLs typically contain /raw/ paths or point directly to file extensions, whereas Git URLs point to repository roots without blob or raw path segments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}