Remote Scanning

New in v0.1.2

The --remote flag lets you scan skills hosted on GitHub without cloning the repository. skill-issue fetches the repo tree via the GitHub API and downloads file contents on the fly.

skill-issue --remote owner/repo

Specifier Formats

The --remote flag accepts several formats for targeting a repository, branch, or specific skill:

Short formats

# Scan all skills in a repo
skill-issue --remote owner/repo

# Scan a specific skill by name
skill-issue --remote owner/repo@skill-name

# Target a specific branch
skill-issue --remote owner/repo:branch

# Branch + specific skill
skill-issue --remote owner/repo:branch@skill-name

GitHub URLs

You can also paste a GitHub URL directly:

# Repository root
skill-issue --remote https://github.com/owner/repo

# Branch and path from a tree URL
skill-issue --remote https://github.com/owner/repo/tree/main/path/to/skill

URLs with .git suffixes and trailing slashes are handled automatically.

Format reference

Format	Example	Scans
owner/repo	vercel-labs/agent-skills	All skills in default branch
owner/repo@skill	vercel-labs/agent-skills@react-best-practices	Single skill in default branch
owner/repo:branch	vercel-labs/agent-skills:main	All skills on branch
owner/repo:branch@skill	vercel-labs/agent-skills:main@react-best-practices	Single skill on branch
GitHub URL	https://github.com/owner/repo	All skills in default branch
GitHub tree URL	https://github.com/owner/repo/tree/main/skill-name	Single skill on branch

Skill Discovery

skill-issue discovers skills by locating SKILL.md files in the repository tree. Each directory containing a SKILL.md is treated as a separate skill. When you specify a skill name with @, it matches against these directory names.

Authentication

The GitHub API has rate limits for unauthenticated requests (60/hour). For heavier usage, provide a token:

# Via CLI flag
skill-issue --remote owner/repo --github-token ghp_xxxxxxxxxxxx

# Via environment variable (recommended)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
skill-issue --remote owner/repo

A GitHub token also lets you scan private repositories you have access to.

Combining with Other Flags

All existing flags work with --remote. The only difference is that config file loading (.skill-issue.toml) is skipped for remote scans — all options must be passed as flags.

# JSON output with strict severity
skill-issue --remote owner/repo --format json --error-on warning

# Filter to errors only
skill-issue --remote owner/repo@my-skill --severity error

# Ignore specific rules
skill-issue --remote owner/repo --ignore SL-NET-001 SL-FS-004

# Verbose mode to see remote target resolution
skill-issue --remote owner/repo -v

Error Handling

Error	Cause	Fix
invalid remote specifier	Malformed --remote value	Check the format — must contain /
repository not found	Repo doesn't exist or is private	Verify the URL; provide --github-token for private repos
no skills found	No SKILL.md files in the repo	The repository may not contain Claude skills
skill 'x' not found	@skill-name didn't match any directory	Check the skill name — it matches directory names
GitHub API rate limit exceeded	Too many unauthenticated requests	Set GITHUB_TOKEN for higher limits (5,000/hour)
repository tree is too large	GitHub API truncated the tree	Specify a skill name with @ to narrow the scan

Examples

Scan a public skills repository:

skill-issue --remote vercel-labs/agent-skills

Scan one skill and get JSON output:

skill-issue --remote vercel-labs/agent-skills@react-best-practices -f json

Scan a private repo on a feature branch:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
skill-issue --remote my-org/internal-skills:feature-branch

Use in CI to audit a third-party skill before installing:

skill-issue --remote some-author/cool-skill --error-on warning --format sarif > results.sarif