Configuration

skill-issue can be configured with a .skill-issue.toml file in your skill directory. This allows you to customize rule behavior, set default options, and create allowlists for known-safe patterns.

Configuration File

Create .skill-issue.toml in the root of your skill directory:

[settings]
severity = "warning"
format = "json"
error_on = "warning"
ignore = ["SL-NET-001", "SL-FS-004"]

[rules.SL-SEC-001]
severity = "warning"      # Override default severity
enabled = false           # Disable specific rule

[[allowlist]]
rule = "SL-NET-001"
file = "docs/examples.md" # Only allow in specific file
reason = "Legitimate URLs in documentation"

Settings

The [settings] section mirrors CLI options. CLI flags override config file values.

[settings]
# Minimum severity to report (info | warning | error)
severity = "warning"

# Output format (table | json | sarif)
format = "table"

# Minimum severity for non-zero exit code
error_on = "error"

# Rule IDs to ignore globally
ignore = ["SL-NET-001", "SL-FS-004"]

Rule Overrides

Override individual rule behavior in the [rules.<RULE_ID>] section:

# Downgrade API key detection to warning
[rules.SL-SEC-001]
severity = "warning"

# Disable shell command detection entirely
[rules.SL-EXEC-001]
enabled = false

# Upgrade URL detection to error
[rules.SL-NET-001]
severity = "error"

Allowlists

Use [[allowlist]] entries to suppress specific findings in specific files. This is more targeted than ignore — it only suppresses the rule for the specified file pattern.

# Allow URLs in documentation files
[[allowlist]]
rule = "SL-NET-001"
file = "docs/*.md"
reason = "Documentation contains example URLs"

# Allow file operations in the build script
[[allowlist]]
rule = "SL-FS-005"
file = "scripts/build.sh"
reason = "Build script legitimately writes files"

# Allow eval in test fixtures
[[allowlist]]
rule = "SL-EXEC-002"
file = "tests/fixtures/*"
reason = "Test fixtures for eval detection"

Allowlist Fields

Field	Required	Description
rule	Yes	The rule ID to allowlist (e.g., SL-NET-001)
file	Yes	File path or glob pattern to match
reason	No	Human-readable reason for the allowlist

Remote Scans

When using --remote, config file loading is skipped entirely. There is no local .skill-issue.toml to read. All options must be passed as CLI flags:

skill-issue --remote owner/repo --severity warning --error-on error --format json

Precedence

Configuration is resolved in this order (later overrides earlier):

1. Built-in defaults
2. .skill-issue.toml in the scanned directory (skipped for --remote)
3. Config file specified with --config
4. CLI flags (--severity, --format, --ignore, etc.)

Example: Strict Security Config

For maximum security, use a strict configuration:

[settings]
severity = "info"
error_on = "warning"

# No rules disabled — scan everything

Example: CI-Friendly Config

For CI/CD pipelines, use JSON output and focused rules:

[settings]
severity = "warning"
format = "json"
error_on = "error"

# Ignore informational rules in CI
ignore = ["SL-NET-001", "SL-NET-008", "SL-FS-004", "SL-FS-009", "SL-EXEC-005"]