Skylos is an open-source (Apache-2.0) CLI and pull-request gate for Python
projects that runs without an account. skylos . finds dead code: unused
functions, classes, imports and empty files. Add -a to check security bugs,
hard-coded secrets, vulnerable dependencies, code quality and AI-code
mistakes. Findings include source locations and supporting analysis;
skylos done checks whether a branch, often a coding agent's, is ready to
merge.
It is built for:
- Teams merging pull requests from AI coding agents such as Claude Code,
Codex and Cursor.
skylos doneruns your tests and flags deleted or skipped tests, loosened CI test steps, silenced lint or type checks, and test-only special cases. - Python maintainers who want framework-aware dead-code, security and secrets checks. Python has the deepest coverage; other languages are listed under Language Support.
pip install skylos
skylos . # find dead code
skylos . -a # add security, secrets, quality, dependency and AI-code checks
skylos done --base main # is this branch finished? runs your tests, compares with mainProof, including the misses: 10 Skylos-assisted dead-code cleanup PRs have been merged into the default branch in 9 open-source projects, including Black, NetworkX, Optuna, mitmproxy and pypdf. Real-World Results lists the 26 cleanup and quality-fix PRs in this ledger, including the ones that were closed, reverted or never reached the default branch. These are accepted cleanup PRs, not endorsements.
Website | Docs | Repo Map | Quick Start | GitHub Action | VS Code Extension | Real-World Results | Benchmarks | Roadmap | Contributing
English | Deutsch | 简体中文 | Translations
Skylos runs locally by default and can also gate pull requests in CI. Use it when you want one command to check a repo or pull request for:
- dead code and unused files
- security flaws and dangerous data flows
- secrets and dependency CVEs
- CI/CD and edge-device deployment misconfigurations
- quality regressions such as complexity, duplicate branches, and deep nesting
- common AI-generated code mistakes, including missing guards, fake helpers, invented package APIs, and impossible dependency versions
- LLM app risks such as unsafe tool use and missing output validation
Python has the deepest coverage. TypeScript/JavaScript and Java also get
dead-code, security and quality checks; PHP, Rust and Dart get dead-code and
security checks. Go dead-code and security checks need the separately built
skylos-go engine, which the container image and GitHub Action include but
the PyPI package does not. C# support is partial, Kotlin is dead code only,
C++ is limited to unused file-local functions, and Shell is security only.
Skylos also checks CI/CD and deployment config. See
Language Support.
Each command answers a different question. The source scan requires PATH.
Bracketed paths on verify, suite, defend, and clean default to the
current directory. suite and defend require a directory; verify and
clean also accept a file.
| Question | Command | Input checked |
|---|---|---|
| What problems are in this source tree? | skylos PATH |
Source files and project configuration; dead code by default, every main source analyzer with -a |
| Did the agent really finish this branch? | skylos done --base main |
The branch's changes since its merge base with main: Skylos runs your tests (pytest automatically; other runners need test_command in [tool.skylos.done]) and compares the tests, test settings and CI steps with the base; writes a receipt to .skylos/receipts/ |
| Does this code contain AI-code mistakes? | skylos verify [PATH] |
AI-defect checks over the selected file or tree, plus a separate Git HEAD behavior comparison for supported Python working changes |
| Should a model review static dead-code findings? | skylos agent verify [PATH] |
LLM by default; optional Jev-only or Jev-plus-LLM review |
| What does the combined repo suite report? | skylos suite [DIRECTORY] |
Static analysis, technical debt, AI defense, and provenance; local findings are report-only by default |
| Does an agent implementation have deployment guardrails? | skylos defend [DIRECTORY] |
Recognized Python and TypeScript/JavaScript LLM integrations; gating requires a threshold flag or policy |
| Which Python dead code can Skylos remove? | skylos clean [PATH] --dry-run |
Python import/function cleanup candidates; --dry-run never writes |
| Will this exact local GPU build fit the machines we ship to? | skylos preflight [ARTIFACT] |
A local built file or directory and .skylos/gpu-targets.yml; an OCI reference is identity-only and returns UNKNOWN in the CLI |
| What vulnerabilities are in this container image? | skylos image scan IMAGE@sha256:<digest> --platform os/arch |
A remote registry image scanned by a separately installed Trivy; --fail-on turns findings into a gate |
Run skylos --help for this chooser, skylos <command> --help for one
command, and skylos commands for the command-family map.
The report commands have different gate and network behavior:
image scanrequires Trivy on trustedPATHand uses Trivy's remote image source, so registry network access and any required registry credentials must already be available. Without--fail-on, a completed scan exits0even when it reports vulnerabilities.suiteruns in the local process and does not upload unless--uploadis set, but its dependency scan can query OSV. Findings are report-only: the command exits0regardless of their count. Operational and output failures are nonzero;--uploadcan also fail for an upload error or Cloud quality gate.defendreports guardrail findings by default. It becomes a gate with--fail-on,--min-score, or gate settings in an explicit policy.cleanwithout--dry-runor--applyis interactive and can write after the final confirmation. Its current codemods support Python imports and functions. An apply pass still exits0if an individual edit prints a failure, so review the completion output.doneexits0on pass,1when a blocking check fails or does not finish, and2when Skylos could not run (for example, the base is not fetched). It reads its settings from the base commit, so a change cannot loosen its own gate.
pip install skylos
skylos .Before 4.47.2, pip install skylos also installs a Dart parser that builds
from source and needs a C compiler. From 4.47.2, Dart support is the optional
skylos[dart] extra. If the install fails for lack of a compiler, use the
container image.
Optional Rust acceleration can be built from source. The standard installation uses Python fallbacks. See the build guide for accelerated operations and possible differences in findings.
The default scan focuses on dead code. Run every main source analyzer,
including security, secrets, quality, dependency, and AI-defect checks, with
-a:
skylos . -aCheck whether a branch, often an AI agent's, is really finished:
skylos done --base mainskylos done compares the branch with its merge base on main and runs your
tests. It flags deleted or skipped tests, loosened test settings and CI test
steps, silenced lint or type checks, and code that special-cases the tests,
then writes a receipt to .skylos/receipts/. It runs pytest automatically;
other test runners need one test_command line in [tool.skylos.done]. See
the done gate guide for every check and its limits.
Run only evidence-backed AI defect checks with:
skylos . --ai-defectsVerify a repository, file, or range before an agent hands it to review:
skylos verify . --file src/app.py --range 40:75 --project-contextFor a directory such as ., the AI-defect scan covers the selected tree. The
separate behavior result models supported Python working-tree changes against
Git HEAD; it is not the scope selector for the AI-defect scan. Dependency
hallucination checks are enabled for path targets and can query package
registries; use --no-dependency-hallucinations to disable those lookups.
High/critical security findings (category: "security") and hard-coded
secrets (category: "secret", value redacted) in the selected file/range also
fail verification; use --no-security for the AI-code-only verdict.
Interactive terminals get a human report. Redirected stdout and -o produce
the versioned JSON result.
skylos verify schema version 2 returns pass, fail, or incomplete.
incomplete means a requested proof could not be established, such as a
missing local TS/JS import, computed namespace member, unsupported language-local
API check, or parser surface that Skylos could not prove; it exits 2 unless
--no-fail is set. The coverage object lists detected languages, expected
checks, language support, missing checks, completed/skipped checks, checked
references, and deterministic skip reasons. Declared third-party dependencies
and recognized Node built-ins are outside the local TS/JS API proof; their
references are counted in out_of_scope_references and do not make a clean
verification incomplete. Unknown bare imports still require review.
Deterministic local/workspace API verification currently covers Python, TypeScript/JavaScript, Go, and Java without executing target code. PHP, Rust, Dart, C#, Kotlin, and Shell retain their existing static-analysis coverage, but their local API proof is reported as unsupported and therefore incomplete. See AI Code Verification Coverage.
Create a local AI hallucination contract for repo-specific generated-code
truth. skylos verify auto-discovers .skylos/ai-contract.yml:
skylos contract init
skylos contract inspect
skylos verify .Test a running agent against deterministic response and tool-use scenarios:
skylos agent init
skylos agent test --allow-contract-endpointCreate a project config with thresholds, ignores, template hooks, and vibe dictionary extensions:
skylos initCreate a starter local rule pack:
skylos rules init
skylos rules validate .skylos/rules/local.yml
skylos rules list --json
skylos rules list cross --json
skylos rules list --packs --json
skylos cache statsGate pull requests with GitHub Actions. No Skylos account or API key is needed:
git checkout -b add-skylos-gate
skylos cicd init --no-upload
git add .github/workflows/skylos.yml
git commit -m "Add Skylos pull request gate"
git push -u origin add-skylos-gate
gh pr create --fillThe generated workflow reviews changed lines on pull requests and adds a
skylos done job when it finds your tests. Without --no-upload, it also
adds a Skylos Cloud upload job for pushes to your default branch, which fails
until the Skylos GitHub App is installed on the repository.
Your first Skylos-gated pull request walks through
it in about 8 minutes, including making the checks required.
Need more commands? Read the CLI Reference.
Install local hooks so the agent is checked while it works, not after:
skylos agent install-hooks # Claude Code (.claude/settings.json)
skylos agent install-hooks --codex # Codex (.codex/hooks.json)
skylos agent install-hooks --cursor # Cursor (.cursor/hooks.json)- After each edit: verifies only the changed lines (security, secrets, AI-code mistakes) and tells the agent what to fix.
- Before a file read: blocks files that contain hard-coded secrets.
- Before a package install: blocks hallucinated or typosquatted packages.
- At stop: blocks "done" while issues the agent added are still open.
Hooks fail open, but never silently: if Skylos errors, the agent and you are
told the action was allowed without a check, and stop reports how many went
unchecked. They log to .skylos/hook.log and merge with your existing hooks.
--uninstall removes only the Skylos entries. See
Agent-loop hooks for the contract, latency, and
limits.
In Cursor, findings arrive at stop rather than after each edit. The hooks
are not a sandbox: they check edits, file reads and package installs, not
every command. See what they don't do.
| Goal | Command | What You Get | More Detail |
|---|---|---|---|
| First dead-code scan | skylos . |
Finds unused functions, classes, imports, files, and framework entrypoint mistakes | Dead code docs |
| Deterministic cleanup preview | skylos clean . --dry-run --types import,function --confidence 80 |
Shows planned Python import/function removals without writing; add --apply to edit files |
Dead code docs |
| Security and quality audit | skylos . -a |
Adds dangerous flow, secrets, dependency, config, quality, and AI-defect checks | Security docs |
| Combined repo report | skylos suite . |
Reports static findings, technical debt, AI defense, and provenance; SCA can query OSV, and findings alone exit 0 |
CLI Reference |
| Optional Python linting | pip install "skylos[lint]" && skylos lint . |
Runs Ruff with its native configuration, output, fixes, and exit codes through the Skylos CLI | Python linting |
| Agent branch done check | skylos done --base origin/main |
Runs your tests and flags deleted, skipped or weakened tests, loosened test settings and CI test steps, silenced checks, and test-only special cases; writes a receipt | Done gate |
| PR gate | skylos cicd init --no-upload |
Generates a GitHub Actions workflow that gates pull requests and runs skylos done when your tests can run. Drop --no-upload to also upload default-branch scans to Skylos Cloud with GitHub OIDC; that job fails until the Skylos GitHub App is installed on the repository |
First gated PR |
| GitLab merge request report | skylos . --format gitlab -o gl-code-quality-report.json |
Exports a native Code Quality report for GitLab CI artifacts | GitLab Code Quality |
| Offline dependency SBOM | skylos sbom . -o sbom.cdx.json |
Lists supported recorded dependencies as CycloneDX 1.6 JSON without network requests | Dependency scanning |
| SPDX SBOM + license policy | skylos sbom . --format spdx-json / license_deny = ["GPL-*"] |
SPDX 2.3 JSON with declared licenses; SKY-SCA-LIC001 flags denied licenses in -a scans |
License compliance |
| Signed verdict deploy gate | skylos verify-verdict verdict.json --commit "$SHA" --repository github.com/org/repo --require-repository-verified --require-trusted-upload --max-age 7d --require-passed |
Verifies a Skylos Cloud check verdict offline (Ed25519 DSSE, in-toto/SLSA) and fails unless it is a recent policy pass for that commit and repository; needs skylos[verdict] |
Verify a signed verdict |
| Readable terminal report | skylos . --format pretty |
Groups findings by file with severity badges, snippets, and copyable file:line locations |
CLI output modes |
| Single-rule review | skylos . --select SKY-L012 --format concise |
Enables the matching analyzer family and reports only that exact rule with its full message | CLI output modes |
| Selectable terminal triage | skylos . --tui |
Opens a keyboard-driven category list, finding list, and detail pane | CLI output modes |
| IDE/test-script output | skylos --format concise src/test.py |
Prints untruncated file:line RULE_ID message findings and exits non-zero when findings exist |
CLI Reference |
| In-loop AI-code verification | skylos verify . --file src/app.py --range 40:75 |
Reports a narrow set of hallucinated helpers, unfinished code, stale references, disabled controls, and API/dependency hallucinations; JSON is used for redirected or -o output |
AI features |
| AI hallucination contracts | skylos contract init && skylos verify . |
Auto-discovers .skylos/ai-contract.yml and verifies generated code against repo-specific symbols, dependencies, APIs, route guards, and test requirements |
AI Hallucination Contracts |
| Changed-lines review | skylos . -a --diff origin/main |
Keeps findings focused on active work instead of legacy debt. In this release --diff can drop removed-control findings (SKY-L021, such as a deleted auth decorator); run skylos . -a --diff-base origin/main without --diff to see them |
Quality gate docs |
| Incumbent scanner comparison | skylos compare . --against incumbent.sarif |
Runs Skylos beside the current scanner and produces a revision-aware scorecard: active overlap, raw unique findings by category, and eligible findings inside evidence-backed unused symbols, without replacing the current gate | Scanner comparison |
| Runtime-assisted dead-code check | skylos . --trace |
Uses runtime traces to reduce dynamic-code false positives | Smart tracing |
| Local rule pack | skylos rules init |
Scaffolds YAML rules for project-specific security and quality checks | Custom rules |
| Security agent quick scan | skylos agent security-quick . |
One-shot LLM security audit; compatibility alias for skylos agent scan . --security |
AI features |
| Security agent deep scan | skylos agent security-deep . |
Three-stage security workflow with threat-model context, static threat traces, discovery/validation, and remediation handoff | AI features |
| AI-assisted review | skylos agent scan . |
Static analysis plus optional LLM review and fix suggestions | AI features |
| Agent harness replay | skylos agent replay .skylos/runs/<run-id> |
Validates and summarizes saved agent verification phases, tool calls, decisions, and budgets | Agent harness artifacts |
| Runtime agent behavior test | skylos agent init && skylos agent test --allow-contract-endpoint |
Checks final responses, tool selection, explicit refusals, and source IDs against a versioned contract | Agent Behavior Testing |
| Verification-backed remediation | skylos agent remediate . |
Scans and fixes supported findings, then re-scans them and records proof-test metadata when available | AI features |
| Agent-loop hooks | skylos agent install-hooks [--codex|--cursor] |
Verifies every agent edit, blocks secret reads and hallucinated package installs, and holds "done" while new issues are open | Agent-loop hooks |
| Project standards for agents | skylos agent install-standards --enforce SKY-L002 |
Gives Codex, Claude Code, and Cursor a project skill and selects measurable quality rules for hook and CI checks | Project standards |
| MCP agent verification | verify_change MCP tool |
Lets Claude, Cursor, and other MCP clients verify an edited file/range with the same schema as skylos verify. Requires a free Skylos API key (SKYLOS_API_KEY). skylos verify and agent-loop hooks need no key |
MCP server |
| LLM integration inventory | skylos discover . |
Maps recognized LLM calls, agent tools, prompt sites, and input sources in Python and TypeScript/JavaScript | Agent verification |
| Pre-deployment agent verification | skylos defend . --format md -o evidence.md |
Verifies agent guardrails, scores OWASP LLM/Agentic coverage, and emits an attested evidence report | Agent verification |
| Agent verification CI gate | skylos defend . --fail-on critical |
Blocks deploys with unguarded LLM integrations; SARIF for code scanning via --format sarif |
Agent verification |
| MCP agent pre-flight | verify_agent MCP tool |
Lets coding agents statically verify the agents they build — scores, failed checks, attestation digest. Requires a free Skylos API key (SKYLOS_API_KEY). skylos defend needs no key |
MCP server |
| Technical debt triage | skylos debt . |
Ranks hotspots and debt trends | Technical debt |
| Category | Examples | Why It Matters |
|---|---|---|
| Dead code | unused functions, classes, imports, package entrypoints, route handlers | reduces maintenance cost without breaking dynamic frameworks |
| Security flaws | SQL injection, XSS, SSRF, path traversal, command injection, unsafe deserialization | catches exploitable flows before code reaches main |
| Secrets | API keys, tokens, private credentials, high-entropy strings | prevents credentials from leaking through commits and PRs |
| CI/CD workflows | GitHub Actions and GitLab CI dangerous triggers, unpinned actions/includes, broad tokens, OIDC misuse, cache poisoning, mutable images | reduces CI/CD supply-chain risk before release jobs run |
| Edge deployment config | Docker Compose privileged device access, host networking, systemd root services, broad capabilities, missing sandboxing | catches repo-controlled settings that turn app bugs into device compromise |
| Kubernetes deployment exposure | Explicitly external Ingress paths reaching a sensitive FastAPI/Flask route without its deployment-required guard, Flask --debug, or an application server using --reload |
reports only when the resources are in one rendered bundle and every deployment edge resolves unambiguously |
| GPU release compatibility | source/build contract mismatches plus built-artifact identity, selected CUDA architecture, packaged runtime, and fleet checks | catches declared intent errors early and verifies the resulting local artifact before release |
| Quality regressions | complexity, deep nesting, duplicate branches, long functions, inconsistent returns | keeps AI-assisted refactors from adding brittle code |
| AI code mistakes | phantom security calls, missing decorators, unfinished stubs, disabled controls, real packages called with invented APIs, impossible npm/Go versions | catches common hallucinated or incomplete code paths before they reach review |
| LLM app risks | unsafe tool use, prompt injection exposure, missing output validation, missing rate limits | helps teams ship AI features with guardrails |
See the full Rules Reference.
skylos sbom . writes declared dependency licenses into CycloneDX, and
skylos sbom . --format spdx-json writes an SPDX 2.3 SBOM. Licenses come from
lockfiles and installed package metadata, offline. Unknown or ambiguous values
(such as BSD) stay NOASSERTION rather than being guessed. --license-lookup
opts in to a deps.dev query. To block licenses in -a scans, set a policy:
[tool.skylos]
license_deny = ["GPL-*", "AGPL-3.0-only"]
license_severity = "HIGH"Violations are reported as SKY-SCA-LIC001. See
License compliance.
Create .skylos/standards.md with the guidance you want agents to follow:
# Coding standards
- Keep functions focused and handle exceptions explicitly.
- Add a focused test when changing behavior.Then install the project skill and choose any Skylos quality rules to enforce:
skylos agent install-standards --enforce SKY-L002
skylos agent install-hooks --codex # use --cursor for Cursor, or omit for Claude Code
skylos agent check-standards . # run this project-wide check in CIThe installer writes SKILL.md files for Codex, Cursor, and Claude Code.
Agent skills provide guidance; the hooks and project-wide check enforce the
selected built-in quality rules. See project standards
for the generated files, rule selection, and coverage limits.
Runtime guardrails are the WAF; Skylos is the SAST. skylos discover scans
Python and TypeScript/JavaScript for recognized LLM integrations (provider
SDKs, agent frameworks including the OpenAI Agents SDK, Claude Agent SDK, and
Google ADK, MCP servers and their tools, direct HTTP calls to LLM APIs or
OpenAI-compatible gateways, plus agent tools, prompt sites, and input
sources). skylos defend checks the guardrails around those detected
integrations deterministically, in the local process, with no model in the
loop. It emits evidence by default and becomes a CI gate only when a threshold
flag or policy supplies gate criteria.
skylos discover . # inventory LLM integrations and agent tools
skylos defend . # score guardrails (13 weighted checks)
skylos defend . --format md -o evidence.md # auditor evidence report + attestation
skylos defend . --format sarif -o defend.sarif # GitHub code scanning upload
skylos defend . --fail-on critical # CI gate: exit 1 on critical gaps
skylos defend . --owasp-framework agentic # report against OWASP Agentic ASI Top 10These commands do not inspect integrations in other languages. If discovery
finds no supported integration, defend returns an empty inventory; do not
treat the resulting score by itself as proof that an unsupported or
unrecognized agent implementation has guardrails.
Per integration it verifies: dangerous output sinks (eval/exec/subprocess), agent tool scope and typed schemas, prompt-injection exposure (delimiters, untrusted input paths, RAG context isolation), output validation, PII filtering, and model pinning — plus ops checks (logging, cost controls, rate limiting) scored separately so they never inflate the security score.
- OWASP mapping: LLM Top 10 (2024/2025) and Agentic ASI Top 10 (2026).
- Evidence report (
--format md): integration inventory, per-check results, OWASP coverage, regulatory framework evidence (EU AI Act, NIST AI RMF, ISO/IEC 42001 — "evidence toward" mappings, never compliance claims), and a remediation appendix. - Attestation: JSON/md/SARIF reports carry a reproducible SHA-256 digest over file contents, policy, plugin set, integration inventory, scores, and full check evidence — re-run on the same tree with the same flags and Skylos version, and the digest must match.
- CI-native:
skylos cicd init --defendgenerates the workflow step, theskylos-defendpre-commit hook gates locally, and$GITHUB_STEP_SUMMARYgets a score summary automatically in Actions. - Policy as code:
skylos-defend.yamlpins gate thresholds and severity overrides (--policy). - Agent-native: the
verify_agentMCP tool lets coding agents verify the agents they build — deterministic verification, not AI checking AI.
Static pre-deployment verification complements runtime controls (gateways, policy engines, human approval flows); it does not replace them. Full guide: docs/agent-verification.md.
Skylos separates generated-code truth, static agent guardrails, and observed runtime behavior:
| Command | Verification question |
|---|---|
skylos verify |
Did the agent generate valid, non-hallucinated code? |
skylos defend |
Does the agent implementation contain the required guardrails? |
skylos agent test |
Did the running agent behave according to its contract? |
Create .skylos/agent-test.yml, then test a live OpenAI-compatible endpoint:
skylos agent init
skylos agent test --allow-contract-endpointOr evaluate captured evidence without a network call:
skylos agent test --observations agent-observations.json
skylos agent test --observations agent-observations.json \
--format json --output agent-results.jsonVersion 1 deterministically checks exact response substrings, required,
allowed, and forbidden tool calls, tool arguments and sequence, maximum call
count, explicit refusals, and explicit source IDs. Missing typed evidence is
incomplete, never pass; exit codes are 0 pass, 1 violation, and 2
incomplete/invalid. Tool selection and final-answer source-ID checks are separate
one-turn scenarios: Skylos records local replayable evidence but never executes
tools returned by the target agent. Offline observations are marked as
unverified fixtures rather than runtime proof.
For an authenticated remote endpoint, keep the destination and secret choice in the trusted CLI invocation:
skylos agent test --endpoint https://agent.example.com/v1/chat/completions \
--allow-remote --auth-env MY_AGENT_API_KEYFull guide: docs/agent-behavior-testing.md.
Skylos is not a replacement for every specialized scanner. It is a local-first repo and PR checker that puts several common review checks behind one CLI.
- Framework-aware dead code detection: FastAPI, Django, Flask, pytest, SQLAlchemy, Next.js, React, package entrypoints, and common plugin patterns.
- PR-focused output: diff scanning, CI thresholds, GitHub annotations, and baselines for existing findings.
- Local-first operation: core analysis executes locally and does not upload source or call an LLM. Dependency/CVE checks can query OSV or package registries, and direct container scanning contacts a registry through Trivy.
- AI-assisted change review: checks for removed validation, auth, logging, CSRF, rate limiting, timeouts, real-package API hallucinations, and other guardrails in generated or edited code.
- Agent-loop verification:
skylos verifyand MCPverify_changeuse a versioned result schema for AI-code trust, security, and secret findings, so coding agents can self-correct before a human sees the change. The CLI renders a human report on a terminal and JSON when redirected or written with-o. - Evidence-backed AI defects:
--ai-defectsand full scans put strict AI-code failure checks underai_defects, including phantom references, fake package APIs, nonexistent packages, impossible dependency versions, and weakened test assertions. The category/tag isai_defect; several rules intentionally keep historicalSKY-LorSKY-DIDs for suppression and baseline compatibility, while new AI-defect-only checks useSKY-A. - Verification-backed remediation: security fixes are checked by re-running analysis, and supported findings can include targeted regression-test proof metadata.
- Project-specific rules: add local YAML rules and extend prompt, credential, sensitive-file, and timeout dictionaries from config.
- One command surface: dead code, security, secrets, dependency, quality, technical debt, agent review, and pre-deployment agent verification commands share the same CLI.
skylos agent verify . and skylos agent test record replayable artifacts
under .skylos/runs/<run-id> and print the run directory in table output. JSON
output includes the same harness summary under the harness key.
Use skylos agent replay .skylos/runs/<run-id> to validate and inspect a saved
run without making LLM calls. Add --format json when another agent or CI job
needs machine-readable status. A valid replay exits 0; an invalid or corrupt
artifact set exits 1 with issue codes. Replay output includes
schema_version so CI and agents can detect artifact-contract changes.
Replay checks internal consistency and corruption; artifacts are not signed and
are not proof against an actor that can rewrite the entire run directory.
Each run directory contains:
events.jsonl: chronological run, phase, and tool-call events.state.json: full observable state, including phases, tool calls, decisions, and budget usage.summary.json: compact status, counts, budget, and artifact paths.behavior-results.json: normalized runtime assertions, provenance, coverage, and a digest-bound evidence report forskylos agent testruns.
The current harness state is observable and replay-validated. It is not yet a resume mechanism for continuing interrupted verification runs.
# Core static analysis
pip install skylos
# LLM-powered agent workflows
pip install "skylos[llm]"
# Ruff Python linting through `skylos lint`
pip install "skylos[lint]"
# Ed25519 verification for `skylos verify-verdict`
pip install "skylos[verdict]"
# Dart analysis, 4.47.2 and later (builds the Dart parser from source; needs a C compiler)
pip install "skylos[dart]"
# All published optional extras
pip install "skylos[all]"Container image:
docker pull ghcr.io/duriantaco/skylos:latest
docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest . --json --no-provenanceThe unqualified image uses Python 3.14. Runtime-specific tags are also published for Python 3.11 through 3.14, so container scans can match a local or CI parser exactly:
docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest-python3.13 . --json --no-provenanceIf a Python file cannot be parsed, Skylos reports analysis_errors, omits the
grade, and exits with code 2 instead of treating the skipped file as clean.
See Installation for source installs, container usage, and optional dependencies.
Run skylos init to add these sections to pyproject.toml:
[tool.skylos]
exclude = ["node_modules", "dist"]
[tool.skylos.templates]
# security = ".skylos/templates/security.md"
# quality = ".skylos/templates/quality.md"
# security_audit = ".skylos/templates/security_audit.md"
# review = ".skylos/templates/review.md"
[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"]
[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.contribution]
collect_local_signals = false
contribute_public_corpus = false
structural_signatures_only = true
include_source = falseTemplate files extend Skylos' built-in prompts; they do not replace the
JSON-only output contract or untrusted-code safety rules. Vibe dictionary
extensions let teams teach Skylos about local fake-auth helpers, project
credential names, sensitive files, and network calls that must set timeouts.
Dead-code entrypoints let teams mark proprietary framework classes, lifecycle
methods, and decorator-registered functions as live using precise rules for
type, name, path, decorators, base classes, and parent classes.
Rules must include a symbol selector such as name, decorators,
base_classes, or parent; path and module only narrow the match.
Contribution signals are off by default; when enabled, Skylos records local
structural accept/dismiss/learn events under .skylos/contribution/ without raw
source.
By default Skylos discovers [tool.skylos] in pyproject.toml by walking up
from the scan path. To use a dedicated TOML config, pass --config-file PATH
or set SKYLOS_CONFIG_FILE; standalone files may use either [tool.skylos]
or top-level [skylos]. Synced Skylos Cloud policy keeps its protected
precedence over repository-controlled config. 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.
| Language | Dead Code | Security | Quality | Local API Proof (verify) |
Notes |
|---|---|---|---|---|---|
| Python | Yes | Yes | Yes | Supported | strongest coverage; framework-aware static analysis and optional tracing |
| TypeScript / JavaScript | Yes | Yes | Yes | Supported | Tree-sitter parsing, package graph reachability, framework conventions |
| Java | Yes | Yes | Yes | Supported | Tree-sitter parsing, structured security-flow analysis, conservative static-member proof |
| Go | Yes¹ | Partial¹ | Partial | Supported | native engine status remains separate from deterministic workspace API proof |
| PHP | Yes | Yes | No | Unsupported | PHP parser coverage plus taint-style security sinks and sources |
| Rust | Yes | Yes | No | Unsupported | Rust parser coverage plus security sink/source checks |
| Dart | Yes³ | Yes³ | No | Unsupported | Dart parser coverage plus selected security sinks and sources |
| C# | Partial | Partial | Partial | Partial | C# symbols, direct-block unreachable code, selected security sinks, and direct NuGet inventory |
| C++ | Partial | No | No | Unsupported | conservative unused file-local functions in .cpp, .cc, .cxx; C++ headers are parsed for references |
| Kotlin | Yes | No² | No | Unsupported | Kotlin symbol extraction with conservative static-analysis coverage |
| Shell | No | Yes | No | Unsupported | shell-script security checks for command injection, SSRF, and path traversal |
¹ Go dead-code and security checks need the separately built skylos-go
engine, which the PyPI package does not include (the container image includes
it and the official GitHub Action builds it). Without it only Go quality checks
run and the scan is reported incomplete; see the Go engine note below.
² No built-in Kotlin security rules; secret scanning still covers .kt and
.kts files.
³ From 4.47.2, Dart checks need the optional skylos[dart] extra
(pip install "skylos[dart]"); earlier releases install the Dart parser by
default. The parser has no prebuilt wheels, so installing it needs a C
compiler. Without it, a scan that includes .dart files reports
SKY-ANALYSIS-INCOMPLETE and exits with code 2 instead of skipping them
silently; skylos doctor shows whether Dart support is installed.
"No" means Skylos has no built-in rules of that kind for the language.
C# dead-code findings are conservative: in a complete executable or web
application scan, unreferenced public types and methods are low-confidence
candidates; library APIs, protected members, and known framework or configured
entry points remain externally reachable. C# source-file reachability is not
implemented. Quality scanning detects statements after unconditional
return, throw, break, or continue in a direct block; it is not full
control-flow analysis. Security coverage includes selected tainted-input
sinks and generic secret scanning of .cs files when --secrets or -a is
enabled. Interpolated raw-string expressions are not yet followed by C# taint
analysis. SCA inventories direct NuGet PackageReference entries in .csproj
files. Only unconditional exact Version pins ([version]) without local
Update/Remove mutations, not VersionOverride or centrally managed
versions, can be checked against
advisories. Ordinary NuGet version values are minimum bounds, so without a
resolved lockfile their installed versions and vulnerability status remain
unknown. Transitive packages are not inventoried.
Java security analysis follows directly implemented request-data helpers in same-package files or source files identified by exact imports or fully qualified names under a verified local source root. Helper reads are bounded and reject symlinks; no Java code or build scripts are executed. This is not full classpath or recursive helper analysis. Unknown helpers are not assumed to be request sources or sanitizers.
C++ analysis covers .cpp, .cc, .cxx, .hpp, .hh, and .hxx. The first
release reports only apparently unused file-local free functions. Without a
build configuration, it cannot fully resolve templates, overloads, macros, or
external usage; these findings are a conservative heuristic, not a proof of
C++ deadness. Ambiguous .h files and C files are not analyzed as C++.
Java weak-hash checks also follow local algorithm variables and values loaded
through java.util.Properties from literal classloader resources. Resource
lookup stays within the matching src/main/resources or src/test/resources
directory. Missing resources, unsupported loaders/layouts, conflicting branch
values, and unresolved mutations remain unknown. Properties are used only as
crypto evidence, never to prove a security guard or choose a safe branch. This
does not resolve arbitrary runtime classpaths, JAR resources, or environment
overrides.
TypeScript and JavaScript dead code analysis recognizes package.json entry
fields, including bin. For targets under dist/ or out/, it checks the
matching src/ location first, then the package root, before the declared
output. This also covers dist/bin/palee.js mapping to bin/palee.ts and
dist/src/index.js mapping to src/index.ts. If both source locations exist,
the src/ mapping keeps priority; unrelated files are not treated as entries.
For ESM build scripts invoked by package scripts, Skylos also follows top-level esbuild calls using unchanged constants, spreads, templates, Node path helpers, and simple literal-array maps. Build scripts are never executed. Nested build calls and filesystem-generated entry lists remain unsupported and may still produce unused-file findings.
VitePress configs at .vitepress/config.* and .vitepress/config/index.*
are recognised as development entrypoints for .js, .ts, .mjs and .mts.
Other files in .vitepress still need a reference or another entrypoint rule.
Existing directory conventions such as scripts/ work with native Windows
separators too; this does not add general discovery of commands in CI workflows.
Vue single file components (.vue) are skipped by source analysis, including
when passed explicitly. Skylos does not yet parse their <script> or
<script setup> blocks; separate JavaScript, TypeScript and backend source
files are still analyzed. Existing browser script and event references in
templates are unaffected.
Go dead-code and security checks require the native skylos-go engine. If
Skylos discovers Go files but cannot run that engine, the report is marked
incomplete, no grade or clean result is produced, and the CLI exits with status
2. Run skylos doctor to verify engine availability and configure
SKYLOS_GO_BIN when using a separately built engine. The official GitHub
Action builds the matching native engine automatically.
See Rules Reference for rule families and scanner scope.
| Surface | Files | Security Scope |
|---|---|---|
| GitHub Actions | .github/workflows/*.yml, .github/workflows/*.yaml, action.yml, action.yaml |
dangerous triggers, token permissions, unpinned actions, template injection, secrets, OIDC, cache, and artifact policy |
| GitLab CI | .gitlab-ci.yml |
mutable images, unpinned includes, literal secrets, untrusted eval, Docker-in-Docker, OIDC, cache, timeout, and runner-tag policy |
| Dockerfile | Dockerfile, Dockerfile.*, *.dockerfile |
dangerous RUN commands, remote ADD without checksum, and literal build ARG / ENV secrets |
| Edge Docker Compose | compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml |
privileged containers, broad host device/control mounts, GPU/device runtime, and host networking |
| Edge systemd | *.service |
root edge services, mutable ExecStart paths, missing sandboxing, broad capabilities, and broad device access |
| Rendered Kubernetes exposure | one multi-document *.yml or *.yaml bundle plus a contracted Python source file |
opt-in proof from an Ingress annotated skylos.dev/network-scope: external (or public) and skylos.dev/backend-protocol: http through its Service and workload; SKY-DEP001 checks direct top-level FastAPI/Flask routes against skylos.dev/source-file and skylos.dev/required-guards, SKY-DEP002 catches an effective Flask debugger, and SKY-DEP003 catches effective reload mode |
| GPU release contract | .skylos/gpu-targets.yml, Dockerfiles, CMake/CUDA build files, TensorRT source |
static target-fleet checks for driver, compute-architecture, and serialized-engine compatibility; no hardware probing |
These workflows cover narrower jobs: container images, Kubernetes deployment exposure, and GPU release artifacts.
| Goal | Command | What You Get | More Detail |
|---|---|---|---|
| Container-image scan | skylos image scan IMAGE@sha256:<digest> --platform linux/amd64 --fail-on high |
Uses separately installed Trivy, registry network/auth, and an explicit severity gate for a pinned remote image | Container-image scanning |
| Container-image report import | skylos ingest trivy --input trivy.json --sarif image.sarif |
Converts an existing Trivy image vulnerability report to Skylos JSON/SARIF; optional digest-bound severity check | Container-image scanning |
| Kubernetes exposure proof | skylos . --select SKY-DEP001,SKY-DEP002,SKY-DEP003 --format concise |
Checks an explicitly external, explicitly plain-HTTP Ingress chain inside one rendered multi-document bundle; route checks compare exact framework wiring with the workload's declared source file and required guards | Deployment exposure rules |
| GPU source/build intent gate | skylos . --select SKY-GPU000,SKY-GPU001,SKY-GPU002,SKY-GPU003 --gate --format concise |
Checks declared CUDA image, architecture, driver, and TensorRT packaging intent before the artifact is built | GPU target contract |
| Built GPU artifact preflight | skylos preflight build/app |
Verifies the exact local artifact identity, selected CUDA architectures, packaged runtime route, and declared fleet compatibility; returns PASS, FAIL, or UNKNOWN |
Release reliability |
skylos preflight checks the built artifact itself against the repository's
declared GPU fleet. This is separate from the SKY-GPU* source scan, which
checks Dockerfiles, CUDA build settings, and TensorRT packaging intent before
the artifact exists.
Declare every machine that receives the same release:
# .skylos/gpu-targets.yml
version: 1
targets:
- name: inference-t4
vendor: nvidia
driver: "535.104.05"
compute_capability: "7.5"
platform: "linux/amd64"The canonical filename is .skylos/gpu-targets.yml; the same schema is also
accepted as .skylos/gpu-targets.yaml.
Then inspect a local build. Skylos uses a trusted system cuobjdump, takes a
private snapshot, and never loads or executes the artifact:
skylos preflight build/appTo make the command argument-free in CI, bind it to a project-relative artifact with a strict release receipt:
{"version": 1, "artifact": "build/app"}Save that file as .skylos/release.json, then run skylos preflight.
For requests that reach report generation, terminal output is concise and
redirected output is schema-versioned JSON. Argument or adapter errors can be
plain text and exit 2.
| Status | Exit | Meaning |
|---|---|---|
PASS |
0 |
Every declared target is compatible within the stated static evidence scope, and the exact artifact identity is verified |
FAIL |
1 |
Artifact evidence proves at least one declared target incompatible |
UNKNOWN |
2 |
Required evidence is missing, ambiguous, unsupported, or incomplete; it never silently becomes a pass |
cuobjdump can report several code-object groups, identified by the producer
label in its selected executable fatbin. Skylos requires a compatible route
for every reported group. A PTX-only route stays UNKNOWN because static
inspection cannot prove that the deployment driver will JIT it successfully.
The overall result is FAIL if any target or required check fails; otherwise
it is UNKNOWN if any result is unknown, and PASS only when all results pass.
Version 1 proves the local artifact identity, Linux ELF platform, selected
executable-fatbin architecture routes, a static packaged $ORIGIN CUDA
runtime route, and documented CUDA driver-family compatibility. It does not
prove runtime execution, workload correctness, memory demand, performance,
nonselected or relocatable fatbins, or per-kernel symbol parity. Windows PE
runtime import proof is not implemented. Digest-pinned OCI references are
accepted as identities but are never pulled or started, so the CLI always
reports UNKNOWN for them; trusted callers can supply digest-bound inspection
facts through skylos.preflight.run_preflight(...).
Skylos has checked-in regression suites for dead code, security, quality, agent review and AI-code defects. They are regression gates, not independent benchmarks: we wrote the cases, so we don't quote their scores as accuracy. Case counts change as the suites grow; the manifests are the current source.
| Suite | Cases | How to run |
|---|---|---|
| Dead code | benchmarks/dead_code/manifest.json |
python scripts/dead_code_benchmark.py |
| Security | benchmarks/security/manifest.json |
python scripts/security_benchmark.py |
| Quality | benchmarks/quality/manifest.json |
python scripts/quality_benchmark.py; also runs in CI on every pull request |
| Agent review | benchmarks/agent_review/manifest.json |
python scripts/agent_review_benchmark.py (needs an LLM API key) |
| AI-code defects | benchmarks/ai_code_defects/manifest.json |
python scripts/ai_code_defect_benchmark.py |
For methodology, dated results, competitor baselines and caveats, including
the frozen golden-v0.2 suites, see BENCHMARK.md. The
done-gate benchmark replays published
agent runs and reports what the gate missed.
An experimental Jev runner can blindly score the pinned jev-1.13.0 typed
decision model against the checked-in dead-code labels or the frozen
skylos-benchmarks corpus. It withholds labels and review reasons from the
request, retains golden label IDs locally for exact classifier comparison, and
repeats the test with answer-signaling identifiers neutralized when that can be
done without changing fixture semantics. An offline comparator now reports
label-by-label corrections, regressions, abstentions, and unsafe removals
against a frozen Skylos result. Live mode sends
fixture source to TypeSafe, requires an explicit flag and a separate
TYPESAFE_API_KEY; it supports bounded, resumable runs and records request
versus local contract-validation latency. Normal Skylos scans need no Jev key.
The paid Jev runs so far are small development runs on synthetic suites, not
an independent holdout, and on some suites Jev did not improve
classification. The
dead-code benchmark guide
and the same-run comparison report those results with
their caveats.
Dead-code review is opt-in. A normal skylos . scan stays local and uses no
model. skylos agent verify . uses the LLM verifier by default; choose Jev
explicitly when you want it:
skylos agent verify . --format json # LLM only
skylos agent verify . --dead-code-review jev --format json # Jev only
skylos agent verify . --dead-code-review jev-llm --format json # Jev, then LLM if uncertainJev-only needs TYPESAFE_API_KEY, not an LLM key. Confident Jev "unused"
decisions retain a static finding and confident "used" decisions suppress it;
uncertain or unavailable decisions leave the finding visible as unverified.
Jev-plus-LLM also needs a configured LLM provider and sends uncertain
decisions to the LLM. Jev alone never authorizes --fix. If you select either
Jev mode without TYPESAFE_API_KEY, Skylos stops with setup instructions
instead of silently switching review modes. Get a key by signing in at the official
TypeSafe console (access may require an
invitation), then set TYPESAFE_API_KEY in your environment; do not put it in
source control or a command-line argument.
Jev sends a bounded project source snapshot to TypeSafe (currently at most
64 KB). Check it for embedded secrets and confirm sharing is authorized; the
local file guard is not a secret scanner. Oversized or unsafe snapshots cannot
be judged by Jev. The older --jev-judge and --jev-precheck flags remain
available for compatibility; use --dead-code-review for new workflows.
See the dead-code review guide for key setup,
fallback behavior, and limitations.
liveness_primer, created and maintained by Matthew Digman, is Skylos's official real-project regression testing tool. On every PR, it compares the base and proposed merge result against the same pinned Python projects and reports which findings were added, removed, or changed.
Read the Analyzer Blast Radius check for the comparison and downloadable reports. These results complement the labeled benchmarks above; a change in finding counts alone does not establish accuracy. See the liveness_primer guide for scope, review steps, and reproduction commands.
10 Skylos-assisted dead-code cleanup PRs have been merged into the default
branch in 9 open-source projects, including
Black,
NetworkX,
Optuna,
mitmproxy,
pypdf and
pdm. Of the other 16 PRs we
recorded, one was merged into a maintainer's staging branch but did not reach
main (Flagsmith), one was a merged quality fix rather than dead code, one was
merged and then reverted, four were closed by maintainers, seven were closed by
us and two are still open. These are accepted cleanup PRs, not endorsements or adoption.
Candidates came from Skylos static analysis, were often triaged with the
LLM-based skylos agent verify, and were checked by hand before each PR.
Real-World Results lists the 26 recorded cleanup and quality-fix PRs with their
outcomes and the maintainers' reasons.
| Integration | Link | Purpose |
|---|---|---|
| GitHub Action | GitHub Action | Repository PR gates or optional digest-pinned container-image gates |
| GitLab Code Quality | GitLab setup | merge request report artifacts; no comment-posting bot or API token |
| Bitbucket Pipelines / Azure Pipelines | Pipeline setup | detects pull request context for Skylos Cloud checks; --diff uses the PR target branch |
| VS Code extension | VS Code extension | in-editor findings and AI-assisted fixes |
| Claude Code / Codex / Cursor hooks | Agent-loop hooks | check each agent edit, file read, and package install locally |
| MCP server | MCP setup | expose Skylos scans to AI agents and coding assistants; analyze works without a key (five calls per rolling 24 hours), other tools need a free Skylos API key; authenticated scans can use credits |
| Ruff | Python linting | optional Python linting through skylos lint |
| Docker image | Installation | run Skylos without a local Python install |
| Skylos Cloud | Cloud workflow | optional upload and dashboard workflows |
Generate a GitHub Actions workflow from the CLI:
skylos cicd init --no-upload # without Skylos Cloud
skylos cicd init --no-upload --scan-path apps/api # a monorepo subproject
skylos cicd init # with Skylos Cloud uploadsThe generated workflow reviews changed lines on pull requests and adds a
skylos done job when it finds your tests. Without --no-upload it also
uploads full scans from default-branch pushes using GitHub OIDC; that upload
job fails until the Skylos GitHub App is installed on the repository. It
supports monorepo subprojects through --scan-path. See
Your first Skylos-gated pull request.
To scan a built image with the composite Action, install a pinned Trivy version
in the caller's job and set image to a trusted repository@sha256:<digest>
build output plus image-platform. This runs an image-only scan; mode: gate
uses image-fail-on (default high), while mode: scan only reports findings.
See container-image scanning.
| Need | Read This |
|---|---|
| Install options, source install, and Docker | Installation |
| First scan and core workflows | Quick Start |
| CLI commands, flags, and examples | CLI Reference |
| CLI output modes, pretty reports, and TUI controls | CLI Output Modes |
| Optional Ruff linting through the Skylos CLI | Python Linting |
| CI setup, PR gates, annotations, and branch protection | CI/CD |
| GitLab merge request reports and CI example | GitLab Code Quality |
| Bitbucket Pipelines and Azure Pipelines pull request checks | Bitbucket and Azure Pipelines |
| Dead-code behavior and framework awareness | Dead Code Detection |
| Security scanning and taint analysis | Security Analysis |
| Dependency CVEs, uv/npm/pnpm/Poetry/Yarn lockfiles, offline SBOM, and SCA in CI | Dependency Scanning |
| Dependency licenses, SPDX 2.3 SBOM, and license deny/allow policy | License Compliance |
| Digest-pinned container-image scanning and GitHub Action setup | Container-image scanning |
| Source GPU contracts and built-artifact preflight | Release Reliability |
| Rule ID prefixes and product terminology | Rule Dictionary |
| Agent scan, verification, remediation, and model setup | AI Features |
| AI defense checks and LLM guardrails | AI Defense |
| Claude Code, Codex, and Cursor hooks | Agent-loop hooks |
Done gate for agent changes (skylos done) |
Done gate |
| First gated pull request with GitHub Actions | Your first gated PR |
| MCP server setup | MCP Server |
| Every Skylos-assisted cleanup PR and its outcome | Real-World Results |
| Baselines, filtering, suppressions, and whitelists | Configuration |
| Smart tracing | Smart Tracing |
| Rule families and language support | Rules Reference |
| Cloud uploads and dashboard flow | CLI to Dashboard |
| VS Code extension | VS Code Extension |
| Benchmarks and methodology | BENCHMARK.md |
| Security policy | SECURITY.md |
| Release process | RELEASE_WORKFLOW.md |
| Contribution priorities | ROADMAP.md |
| Contributing | CONTRIBUTING.md |
Does Skylos replace Bandit, Semgrep, CodeQL, or Vulture?
No. Skylos can run alongside them. It focuses on framework-aware dead-code signal, PR gating, AI-era regression checks, and a combined workflow across dead code, security, secrets, quality, and AI-defect checks.
Does Skylos require an LLM?
No. Core static analysis runs locally without API keys. LLM features are
optional through skylos[llm] and agent commands.
Is Skylos free?
The Skylos CLI is free and open source (Apache-2.0). Skylos Cloud has a Free plan for one project and a Workspace plan; buying any one-time credit pack turns Workspace on for good, with no seats or subscriptions.
Does the MCP server need an account?
Without SKYLOS_API_KEY the MCP server only exposes analyze (dead code,
five calls per rolling 24 hours). Every other MCP tool (verify_change, verify_agent,
security_scan, secrets_scan, and so on) returns an authentication error
until the server is started with SKYLOS_API_KEY set; create a free key in
the Skylos Cloud dashboard settings. Unauthenticated analyze calls are free.
Authenticated analyze, security, quality, secrets and provenance scans can
use credits; Skylos Cloud sets the current cost. remediate currently costs
10 credits per call. The CLI equivalents (skylos verify,
skylos defend, skylos . -a) and skylos agent install-hooks run fully
locally with no account or key.
Does Skylos replace Ruff?
No. skylos lint is an optional convenience entry point that delegates to
Ruff. Install it with pip install "skylos[lint]"; normal Skylos scans do not
run Ruff or merge Ruff violations into SKY-* findings.
Can I use it only on changed code?
Yes. Use skylos . -a --diff origin/main locally or configure CI gates to focus
on new findings. In this release --diff can drop findings for a removed
security control, such as a deleted auth decorator (SKY-L021); run
skylos . -a --diff-base origin/main without --diff to see those.
Does skylos done catch every way to fake a finished change?
No. It compares test functions (pytest, unittest, JavaScript/TypeScript), so rewriting a custom test-runner script or deleting cases from a test data file is not caught, and a test can still be weakened in ways its static assertion count cannot see. See the done gate's limits and its benchmark.
How should I handle intentional dynamic code?
Use baselines, whitelists, inline suppressions, or runtime tracing. See the configuration docs and smart tracing docs.
- Report security issues through SECURITY.md.
- Open bugs and false-positive reports with minimal repros.
- Check ROADMAP.md for useful contribution areas.
- Read CONTRIBUTING.md before sending a pull request.
- See QUALITY.md for project quality and gate expectations.
- Join the Discord for community support.
Skylos is licensed under the Apache License 2.0.
