Skip to main content

Configuration

Skylos reads the [tool.skylos] table in pyproject.toml, or the same keys at the top level of skylos.toml or .skylos.toml, so TypeScript, Go and Java repositories need no pyproject.toml. Run skylos init to add a [tool.skylos] section with thresholds, ignores, and vibe dictionary extensions to pyproject.toml, or add the section to an existing file. See Where Settings Come From for how Skylos finds and merges these files.

Configuration File​

[tool.skylos]
# Quality thresholds
complexity = 10
nesting = 3
max_args = 5
max_lines = 50
duplicate_strings = 3

# Folders to skip in the main scan, skylos debt and skylos clean
exclude = ["node_modules", "dist"]

# Rules to ignore (by rule ID)
ignore = []

# AI model for --fix and --audit
model = "gpt-4.1"

[tool.skylos.whitelist]
# Glob patterns to ignore as unused
names = [
"handle_*",
"visit_*",
"*Plugin",
]

[tool.skylos.whitelist.documented]
# Patterns with reasons (recommended for teams)
"dark_logic" = "Called via globals() string manipulation"
"BasePlugin" = "Discovered via __subclasses__()"

[tool.skylos.whitelist.temporary]
# Temporary whitelist - warns when expired
"legacy_handler" = { reason = "Migration - JIRA-123", expires = "2026-03-01" }

[tool.skylos.overrides."src/plugins/*"]
# Per-path whitelist rules
whitelist = ["*Plugin", "*Handler"]

[tool.skylos.vibe]
# Teach Skylos about project-specific AI-code mistakes
extra_phantom_names = ["verify_enterprise_auth"]
extra_phantom_decorators = ["tenant_admin_required"]
extra_credential_names = ["tenant_signing_secret"]
extra_network_timeout_calls = ["vendor_sdk.fetch"]

[tool.skylos.dead_code]
entrypoints = []

[[tool.skylos.dead_code.entrypoints]]
type = "method"
name = ["create", "pre_hook", "post_hook"]
parent = { name = "Main", base_classes = ["Application"] }
path = "src/**"
reason = "project framework lifecycle hook"

[tool.skylos.languages.typescript]
# Language-specific overrides
complexity = 15
nesting = 4

[tool.skylos.languages.java]
complexity = 12

[tool.skylos.gate]
# Quality gate settings
fail_on_critical = true
max_security = 0
max_reliability = 0
max_quality = 10
strict = false

[tool.skylos.contribution]
# Off by default. Stores structural accept/dismiss/learn signals locally only.
collect_local_signals = false
contribute_public_corpus = false
structural_signatures_only = true
include_source = false

Configuration Options​

Quality Thresholds​

OptionTypeDefaultDescription
complexityint10Maximum cyclomatic complexity before flagging a function
nestingint3Maximum nesting depth before flagging
max_argsint5Maximum function arguments before flagging
max_linesint50Maximum function length in lines

Analysis Options​

OptionTypeDefaultDescription
excludelist[]Folders to exclude. Applies to the main scan and to commands such as skylos debt and skylos clean; see Exclude And Include
include_generatedboolfalseAlso scan generated and vendored files that a full scan skips; see Generated And Vendored Files
ignorelist[]List of rule IDs to suppress (e.g., ["SKY-L002", "SKY-Q301"])
modelstring"gpt-4.1"LLM model for AI-powered features

Vibe Dictionary Extensions​

The [tool.skylos.vibe] section lets teams teach Skylos about local fake-auth helpers, project credential names, sensitive files, and network calls that must set timeouts. skylos init writes these keys with empty lists:

OptionTypeDefaultDescription
extra_phantom_nameslist[]Local fake-auth or security helper names, such as verify_enterprise_auth
extra_phantom_decoratorslist[]Local auth decorator names, such as tenant_admin_required
extra_credential_nameslist[]Project credential names, such as tenant_signing_secret
extra_sensitive_file_keywordslist[]Project-specific sensitive-file keywords
extra_network_timeout_callslist[]Network calls that must set a timeout, such as vendor_sdk.fetch
[tool.skylos.vibe]
extra_phantom_names = ["verify_enterprise_auth"]
extra_phantom_decorators = ["tenant_admin_required"]
extra_credential_names = ["tenant_signing_secret"]
extra_network_timeout_calls = ["vendor_sdk.fetch"]

LLM Prompt Templates​

LLM prompt templates are not read from the repository: pass a trusted file with --prompt-template KIND=PATH to skylos agent scan, agent audit, agent security-quick or agent security-deep (KIND is security, quality, security_audit or review). A template extends Skylos' built-in prompt; it does not replace the JSON-only output contract or untrusted-code safety rules.

Installed Type Checker (Unreleased)​

The unreleased source implementation discovers a checker from its own project configuration. If several are declared, choose one explicitly:

[tool.skylos.type_check]
checker = "mypy"

Supported choices are mypy, pyright, pyrefly, tsc and auto. This selection alone does not execute the checker: request --type-check on a scan or verify. Done uses separate trusted baseline policy:

[tool.skylos.done]
type_checker = "mypy"
type_check_timeout_seconds = 120

[tool.skylos.done.checks]
type_check = "block" # off (default), advise, or block

See Type Checking for execution boundaries, baseline requirements and diagnostic origins.

Contribution Signals​

The [tool.skylos.contribution] section controls AI-code defect signal capture. It is explicit, opt-in, and off by default.

OptionTypeDefaultDescription
collect_local_signalsboolfalseRecord local structural accept/dismiss/learn events
contribute_public_corpusboolfalseReserved for public corpus contribution; keep disabled unless you explicitly opt in
structural_signatures_onlybooltrueStore rule/category/severity/file extension/line bucket/hashes instead of source text
include_sourceboolfalseAlways sanitized to false; raw source is not captured

When local signal capture is enabled, Skylos stores bounded local events at:

.skylos/contribution/events.json

Events are generated from agent-service accept, dismiss, and learn actions. They include structural hashes and message hashes, not raw code. The file is local project state and should normally be gitignored.

[tool.skylos.contribution]
collect_local_signals = true
contribute_public_corpus = false
structural_signatures_only = true
include_source = false

Gate Configuration​

The [tool.skylos.gate] section controls the quality gate behavior when using --gate:

OptionTypeDefaultDescription
fail_on_criticalbooltrueBlock deployment if CRITICAL security issues or secrets are found
max_securityint0Maximum allowed security findings before gate fails
max_reliabilityint0Maximum allowed deployment/runtime Reliability findings before the gate fails; evaluated separately from max_security
max_qualityint10Maximum allowed quality findings before gate fails
strictboolfalseWhen true, prevents bypassing a failed gate interactively

Release Reliability findings have their own JSON bucket, count, and gate threshold. See Release Reliability for the Kubernetes and GPU rule contracts.

Supply Chain​

The [tool.skylos.supply_chain] section controls dependency supply-chain checks in scans (--sca, -a), in pull request checks and in the agent hooks:

OptionTypeDefaultDescription
block_malwarebooltrueThe install hook blocks versions reported as malware; false asks instead
min_release_age_hoursintunsetThe agent hooks hold package installs and MCP servers younger than this (48 when unset; 0 turns it off). When set above 0, scans also report SKY-SCA-AGE001, which counts toward max_dependency_vulnerabilities (default 0), so --gate fails while a locked version is younger than this
check_provenancebooltrueThe install hook blocks npm versions that lost the provenance earlier versions had
internal_packageslist[]Package names or globs (acme-*, @acme/*) that must come from your private registries; enables SKY-SCA-SRC001. --review-upgrades never looks them up on a public registry
private_registrieslist[]Index or registry URLs that serve your internal packages; the install hook never sends packages from them to public lookups, and --review-upgrades skips lockfile entries downloaded from them
trusted_registrieslist[]More registries the install hook treats as trusted, added to [tool.skylos.hooks] trusted_registries

Skylos reads this section from pyproject.toml in the project root; under SKYLOS_POLICY_BASE (pull-request CI) it reads the base commit's configuration instead.

A synced Skylos Cloud policy never loosens a value the repository sets: when both set one, booleans combine with OR and the release age takes the larger value. A value only one side sets is used as it is. Cloud sends min_release_age_hours only when your workspace sets it; left empty, the CLI default applies (48 hours for installs, no age check in scans). See Configuration on the Supply Chain page.

[tool.skylos.supply_chain.hardening_exceptions]​

Packages that may weaken install hardening without failing a pull request (SKY-SCA-HRD001), each with a reason:

[tool.skylos.supply_chain.hardening_exceptions]
esbuild = "downloads its platform binary in postinstall"
KeyValueEffect
package namenon-empty string (the reason)SKY-SCA-HRD001 regressions that name this package are skipped and listed in analysis_summary.supply_chain_diff.checks.hardening.exceptions_applied

Skylos reads this table from the diff's merge base only, so a pull request cannot add an exception for itself. An entry with an empty reason is ignored. See Weakened Install Hardening.

Whitelist Configuration​

Suppress false positives permanently without cluttering your code with inline comments.

CLI Commands​

# Add a glob pattern
skylos whitelist 'handle_*'

# Add with reason (recommended for teams)
skylos whitelist dark_logic --reason "Called via globals() in dispatcher"

# View current whitelist
skylos whitelist --show

Whitelist Sections​

[tool.skylos.whitelist]​

Simple glob patterns for names to ignore:

[tool.skylos.whitelist]
names = [
"handle_*", # Event handlers called via getattr
"visit_*", # AST visitor methods
"*Plugin", # Plugin classes discovered via __subclasses__
"*_callback", # Callback functions
]

[tool.skylos.whitelist.documented]​

Patterns with reasons - shows up in skylos whitelist --show and helps teams understand why something is whitelisted:

[tool.skylos.whitelist.documented]
"dark_logic" = "Called via globals() string manipulation in trigger_blindspots()"
"BasePlugin" = "Discovered via __subclasses__() at runtime"
"legacy_api" = "Called by external service - do not remove"

[tool.skylos.whitelist.temporary]​

Patterns with expiration dates - Skylos warns when these expire to prevent whitelist rot:

[tool.skylos.whitelist.temporary]
"legacy_handler" = { reason = "Migration in progress - JIRA-123", expires = "2026-03-01" }
"old_api_v1" = { reason = "Deprecated, removing in Q2", expires = "2026-06-30" }

[tool.skylos.overrides."path/*"]​

Per-file or per-folder whitelist rules:

[tool.skylos.overrides."src/plugins/*"]
whitelist = ["*Plugin", "*Handler"]

[tool.skylos.overrides."src/events/*"]
whitelist = ["on_*", "*_listener"]

Dead-Code Entrypoints​

Use [[tool.skylos.dead_code.entrypoints]] when code is live because a project-specific framework, plugin loader, or decorator calls it implicitly. Dead-code entrypoints let teams mark proprietary framework classes, lifecycle methods, and decorator-registered functions as live. Entrypoint rules are more precise than broad whitelists because they can match definition type, name, path, decorator, base class, and parent class metadata.

[tool.skylos.dead_code]
entrypoints = []

[[tool.skylos.dead_code.entrypoints]]
type = "class"
name = "Main"
path = "**/main.py"
base_classes = ["Application"]
reason = "framework application entrypoint"

[[tool.skylos.dead_code.entrypoints]]
type = "method"
name = ["create", "pre_hook", "post_hook"]
parent = { name = "Main", base_classes = ["Application"] }
reason = "framework lifecycle method"

[[tool.skylos.dead_code.entrypoints]]
type = "function"
decorators = ["runtime_hook"]
path = "src/**"
reason = "registered by runtime_hook"

Supported match fields are type, name, full_name, module, path, decorator, decorators, base_class, base_classes, and parent. The parent rule can match the parent class by name, full_name, module, path, base_class, or base_classes. Rules must include a symbol selector such as name, decorators, base_classes, or parent; path, module, and type only narrow the match.

Inline Ignores​

For one-off exceptions, use inline comments instead of config:

# Single line ignore
def dynamic_handler(): # skylos: ignore
pass

# Alternative syntaxes (all equivalent)
def another(): # noqa: skylos
pass

def yet_another(): # pragma: no skylos
pass

# Block ignore (multiple functions)
# skylos: ignore-start
def block_one():
pass

def block_two():
pass
# skylos: ignore-end

Whitelist Summary​

Want to...Do this
Whitelist a patternskylos whitelist 'handle_*' or add to names = []
Document whyskylos whitelist x --reason "why" or add to [tool.skylos.whitelist.documented]
Temporary whitelistAdd to [tool.skylos.whitelist.temporary] with expires date
Per-folder rulesAdd [tool.skylos.overrides."path/*"] section
View all whitelistsskylos whitelist --show
Inline ignore# skylos: ignore comment
Block ignore# skylos: ignore-start ... # skylos: ignore-end

Language-Specific Overrides​

You can override global settings for specific languages under [tool.skylos.languages.<lang>]:

[tool.skylos.languages.typescript]
complexity = 15
nesting = 4

[tool.skylos.languages.java]
complexity = 12

Currently supported language overrides: typescript and java.

Where Settings Come From​

Skylos walks up from the scan path to the repository root (the folder with .git) and reads, in each folder, the first of these that exists:

  1. .skylos.toml
  2. skylos.toml
  3. pyproject.toml with a [tool.skylos] table (a pyproject.toml without one is skipped, so it no longer hides the settings above it)

If no configuration is found, Skylos applies the built-in defaults.

skylos.toml​

skylos.toml takes the same keys as [tool.skylos], at the top level, so TypeScript, Go and Java repositories need no pyproject.toml:

# skylos.toml
exclude = ["generated", "dist"]

[gate]
max_security = 0

[done]
test_command = "npm test"

Monorepos​

In a monorepo every file found on the way up applies: the repository root is the base and the file nearest the scanned folder wins per key. A key set in a package replaces the root's value (lists are replaced, not concatenated); tables such as [gate] merge key by key. Set root = true in a package's file to ignore everything above it:

# packages/api/skylos.toml
root = true

skylos doctor lists the files in use, nearest first, and the ones it ignored.

In PR CI, settings come from the base commit only, with the same rules, and skylos done reports an added or edited skylos.toml as a change to Skylos settings (SKY-A114). [done] and [approval] settings are read from the repository root's file.

One Explicit File​

To use one file instead of discovery, pass --config-file PATH or set SKYLOS_CONFIG_FILE; it may use [tool.skylos], [skylos], or (when named skylos.toml) top-level keys.

Skylos Cloud Policy​

Synced Skylos Cloud policy keeps its protected precedence over repository-controlled config. See Project Policy and Quality Gate.

Exclude And Include​

The top-level [tool.skylos].exclude list applies to the main scan and commands such as skylos debt and skylos clean. Pass --exclude for command-local additions or --include-folder to override an excluded folder.

[tool.skylos]
exclude = ["node_modules", "dist"]
skylos . --exclude tests --include-folder venv

Generated And Vendored Files​

A full scan skips generated and vendored files (Django migrations, static/**/lib/**, *.min.js, *.min.css, vendored-library banners) and says how many in one line of output. Set include_generated = true under [tool.skylos] (or pass --include-generated) to scan them:

[tool.skylos]
include_generated = true

See What a full scan leaves out.

Default Excluded Folders​

Skylos automatically excludes common non-source directories:

__pycache__
.git
.pytest_cache
.mypy_cache
.tox
htmlcov
.coverage
build
dist
*.egg-info
venv
.venv

To see the current exclusion list:

skylos . --list-default-excludes

To disable default exclusions:

skylos . --no-default-excludes

To force-include a normally excluded folder:

skylos . --include-folder venv