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
| Option | Type | Default | Description |
|---|---|---|---|
complexity | int | 10 | Maximum cyclomatic complexity before flagging a function |
nesting | int | 3 | Maximum nesting depth before flagging |
max_args | int | 5 | Maximum function arguments before flagging |
max_lines | int | 50 | Maximum function length in lines |
Analysis Options
| Option | Type | Default | Description |
|---|---|---|---|
exclude | list | [] | Folders to exclude. Applies to the main scan and to commands such as skylos debt and skylos clean; see Exclude And Include |
include_generated | bool | false | Also scan generated and vendored files that a full scan skips; see Generated And Vendored Files |
ignore | list | [] | List of rule IDs to suppress (e.g., ["SKY-L002", "SKY-Q301"]) |
model | string | "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:
| Option | Type | Default | Description |
|---|---|---|---|
extra_phantom_names | list | [] | Local fake-auth or security helper names, such as verify_enterprise_auth |
extra_phantom_decorators | list | [] | Local auth decorator names, such as tenant_admin_required |
extra_credential_names | list | [] | Project credential names, such as tenant_signing_secret |
extra_sensitive_file_keywords | list | [] | Project-specific sensitive-file keywords |
extra_network_timeout_calls | list | [] | 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.
| Option | Type | Default | Description |
|---|---|---|---|
collect_local_signals | bool | false | Record local structural accept/dismiss/learn events |
contribute_public_corpus | bool | false | Reserved for public corpus contribution; keep disabled unless you explicitly opt in |
structural_signatures_only | bool | true | Store rule/category/severity/file extension/line bucket/hashes instead of source text |
include_source | bool | false | Always 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:
| Option | Type | Default | Description |
|---|---|---|---|
fail_on_critical | bool | true | Block deployment if CRITICAL security issues or secrets are found |
max_security | int | 0 | Maximum allowed security findings before gate fails |
max_reliability | int | 0 | Maximum allowed deployment/runtime Reliability findings before the gate fails; evaluated separately from max_security |
max_quality | int | 10 | Maximum allowed quality findings before gate fails |
strict | bool | false | When 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:
| Option | Type | Default | Description |
|---|---|---|---|
block_malware | bool | true | The install hook blocks versions reported as malware; false asks instead |
min_release_age_hours | int | unset | The 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_provenance | bool | true | The install hook blocks npm versions that lost the provenance earlier versions had |
internal_packages | list | [] | 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_registries | list | [] | 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_registries | list | [] | 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"
| Key | Value | Effect |
|---|---|---|
| package name | non-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 pattern | skylos whitelist 'handle_*' or add to names = [] |
| Document why | skylos whitelist x --reason "why" or add to [tool.skylos.whitelist.documented] |
| Temporary whitelist | Add to [tool.skylos.whitelist.temporary] with expires date |
| Per-folder rules | Add [tool.skylos.overrides."path/*"] section |
| View all whitelists | skylos 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:
.skylos.tomlskylos.tomlpyproject.tomlwith a[tool.skylos]table (apyproject.tomlwithout 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