What can you do with this server?

This MCP server exposes Skylos tools for static code analysis, security review, quality/architecture assessment, AI-agent verification, remediation, and triage. * analyze: find dead code (unused functions, classes, imports, variables, parameters, files); read-only; works without an API key (5 calls/day). * security_scan: scan source for security issues like SQL/command injection, SSRF, path traversal, eval/exec, unsafe deserialization. * quality_check: report code-quality issues (complexity, deep nesting, long functions, duplicate branches). * architecture_check: report module coupling, cohesion and circular dependencies. * health_score: assess a project via Risk, Maintainability and Dead code readouts. * secrets_scan: find hard-coded secrets/credentials with redacted values. * provenance_scan: attribute changes to AI agents, bots or humans using git signals and local evidence. * validate_code_change: validate a unified diff for security regressions, dangerous patterns, secrets and hallucinated dependencies. * verify_change: verify an edited file/range for AI-code defects, security bugs and secrets. * verify_agent: statically verify AI-agent guardrails (prompt injection, dangerous sinks, tool scope, output validation, PII, cost controls) with OWASP mapping and attestation. * verify_dead_code: ask an LLM to review dead-code candidates to reduce false positives. * remediate: plan or apply LLM-generated fixes for findings (dry-run default; can edit files). * generate_fix: generate a unified-diff patch to remove/comment dead code, optionally applying it. * learn_triage / get_triage_suggestions: record and suggest accept/dismiss decisions for findings. * get_security_context: summarize a project's security setup, including frameworks, auth, headers, rate limiting, validation and policy file. Most tools require SKYLOS_API_KEY; analyze is free without a key. Some tools are read-only/local, while remediate and generate_fix can modify code.

Which integrations are available for this server?

Scans Docker Compose and other deployment configs for privileged access, host networking, missing sandboxing, and other edge-device security misconfigurations. Generates GitHub Actions PR gates with annotations and failure thresholds, and scans workflows for CI/CD misconfigurations. Scans GitLab CI configurations for dangerous triggers, unpinned actions/includes, broad tokens, and other supply-chain risks.

mcp-skylos

by duriantaco

Overview Schema Source Related Servers Discussions Admin

Python

What Is Skylos?

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 done runs 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 main

Proof, 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.

MCP Toplist License: Apache 2.0 codecov PyPI - Python Version PyPI version VS Code Marketplace

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 and Dart get dead-code and security checks; Rust gets security checks and experimental dead code (hidden below the default confidence threshold; --confidence 40 lists it). Go dead-code and security checks need the native skylos-go engine: from 4.50 the PyPI wheels for Linux, macOS and Windows (x86_64 and arm64) include it, the container image includes it and the GitHub Action builds it. On other platforms skylos doctor prints the command that builds it from source, and SKYLOS_GO_BIN points Skylos at a separately built engine. 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.

Related MCP server: loctree-mcp

Read The Results

Remember Risk, Maintainability, Dead code, Gate:

Readout	What it tells you
Risk	Highest unresolved severity and counts. One critical finding stays critical, regardless of repository size.
Maintainability	Advice counts, affected code units, and how far measurements exceed their limits.
Dead code	Removal candidates with confidence and evidence; review dynamic calls and public APIs before deleting.
Gate	Whether findings satisfy your configured limits. Passing means within policy, not zero findings.

Finding Type is separate from severity: Defect is a concrete correctness pattern, Review needs context, and Advice concerns maintainability or tooling. A Review finding can still be critical. Advice stays visible in rule groups; --expand-advice shows every location and JSON keeps complete records. Grouping cannot improve the assessment or bypass a gate.

Security findings show recorded source-to-sink evidence when available, with partial static analysis labeled. Dependency coverage names unresolved versions and the supported inputs needed to check them. Neither view claims runtime exploitability or a complete installed environment; JSON keeps the full evidence.

For uv.lock, valid Git, URL, path and private-index dependencies are shown as not checked. Skylos still queries supported public packages; the coverage gap alone does not cause exit 2. It cannot establish a clean dependency assessment. See uv source coverage.

New source scans replace the blended A–F grade with these readouts. Disabled checks are not assessed; failed checks are incomplete. Maintainability percentages use only the relevant units actually measured, with no guessed denominators or uncalibrated grades. The independent debt and defend scores keep their meanings. See the output guide.

Choose the Right Command

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 scan requires Trivy on trusted PATH and 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 exits 0 even when it reports vulnerabilities.
suite runs in the local process and does not upload unless --upload is set, but its dependency scan can query OSV. Findings are report-only: the command exits 0 regardless of their count. Operational and output failures are nonzero; --upload can also fail for an upload error or Cloud quality gate.
defend reports guardrail findings by default. It becomes a gate with --fail-on, --min-score, or gate settings in an explicit policy.
clean without --dry-run or --apply is interactive and can write after the final confirmation. Its current codemods support Python imports and functions. An apply pass still exits 0 if an individual edit prints a failure, so review the completion output.
done exits 0 on pass, 1 when a blocking check fails or does not finish, and 2 when 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.

Start In 60 Seconds

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 . -a

Check whether a branch, often an AI agent's, is really finished:

skylos done --base main

skylos 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, advises on code the branch left without callers (including in files it did not touch), then writes a receipt to .skylos/receipts/. When tests fail, it reruns them on the merge base and labels each failure "introduced" or "already failing"; every failure still blocks by default. 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-defects

Verify a repository, file, or range before an agent hands it to review:

skylos verify . --file src/app.py --range 40:75 --project-context

For 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-endpoint

Create a project config with thresholds, ignores, template hooks, and vibe dictionary extensions:

skylos init

Create 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 stats

Gate 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 --fill

The 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.

The gate (skylos . --gate, skylos cicd gate, and the generated workflow) fails on any critical security issue, any secret, and any critical AI-code issue, such as an import of a package that does not exist on PyPI (SKY-D222) or a call to a function that is never defined or imported (SKY-L012). Other findings fail it only above count limits. Change the limits under [tool.skylos.gate] in pyproject.toml:

[tool.skylos.gate]
max_high = 5          # high-severity security issues allowed
max_quality = 10      # quality issues allowed
max_ai_defects = 10   # AI-code issues allowed (defaults to max_quality)
# AI-code issues at these severities fail the gate whatever max_ai_defects
# allows. Add "HIGH" to block more; [] turns the rule off.
block_ai_defect_severities = ["CRITICAL"]

max_ai_defects and block_ai_defect_severities are separate checks; the gate fails if either one fails. In a pull request, skylos cicd gate --diff-base reads this policy from the base branch, so a pull request cannot turn the rule off for itself. A gate policy synced from Skylos Cloud replaces the repository's [tool.skylos.gate] section.

Every gate run ends with one verdict line and the reasons behind it: Quality Gate: PASSED, Quality Gate: FAILED (exit 1), or Quality Gate: INCOMPLETE — could not decide (exit 2) when required analysis did not finish, for example a lockfile the dependency scan could not resolve. Each reason names the check that stopped, how many files or dependencies it missed, and what to change. A file that does not parse is a coverage warning under the verdict, not a reason to stop: the limits are evaluated on everything else (set require_complete = true under [tool.skylos.gate.coverage] to fail instead). --format json carries the same verdict in a top-level gate object; concise, LLM, GitHub, and GitLab output print it on stderr. See Exit Codes And Incomplete Analysis.

Need more commands? Read the CLI Reference.

Check Every Agent Edit (Claude Code, Codex, Cursor)

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 or one-shot run (pip, uvx, npx, pnpm dlx, bunx, go run pkg@v, ...): blocks hallucinated or typosquatted packages, and asks before installs it cannot verify (git and URL sources, unknown registries, failed lookups).
Before a git command: blocks --no-verify, HUSKY=0 and other ways around the repository's git hooks.
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.

Common Workflows

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
Risks that need a human approval	`skylos cicd risk-review --base origin/main`	Lists deleted or weakened tests, removed auth checks, added or changed dependencies, weakened CI, silenced checks, added secrets, guardrail setting edits, migration changes and very large diffs. As a required GitHub check (`skylos cicd init --risk-review`) it fails until a person with write access approves the head commit; bot approvals do not count	Risk review
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. A removed security control (SKY-L021, such as a deleted auth decorator) is still reported, even when the change only deletes the decorator line	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, hallucinated package installs and git-hook bypasses, asks before unverifiable 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

What Skylos Catches

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.

Dependency licenses

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.

Give Coding Agents Project Standards

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 CI

The 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.

Verify AI Agents Before They Ship

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 10

These 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 --defend generates the workflow step, the skylos-defend pre-commit hook gates locally, and $GITHUB_STEP_SUMMARY gets a score summary automatically in Actions.
Policy as code: skylos-defend.yaml pins gate thresholds and severity overrides (--policy).
Agent-native: the verify_agent MCP 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.

Test Running Agent Behavior

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-endpoint

Or 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.json

Version 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_KEY

Full guide: docs/agent-behavior-testing.md.

How Skylos Fits

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 (App/Pages Router files and metadata routes), React, Laravel (auto-discovered commands, listeners, components, factories, seeders), tool config files, 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. See What Leaves Your Machine.
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 verify and MCP verify_change use 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-defects and full scans put strict AI-code failure checks under ai_defects, including phantom references, fake package APIs, nonexistent packages, impossible dependency versions, and weakened test assertions. The category/tag is ai_defect; several rules intentionally keep historical SKY-L or SKY-D IDs for suppression and baseline compatibility, while new AI-defect-only checks use SKY-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.

What Leaves Your Machine

Skylos sends nothing to Skylos Cloud unless the command or flag you ran says it talks to Skylos Cloud: --upload, skylos login, whoami, project, sync, credits, upload, ingest claude-security, verify-verdict, feedback, or the --verify scan option. A token on its own (SKYLOS_TOKEN, a saved skylos login, a CI OIDC token) never makes a command upload a scan, findings or a run summary. There is no update check and no analytics.

skylos agent scan, agent verify, agent remediate and agent remediate --standards send a run summary only with --upload: one POST /api/agent-runs with command, per-command counts, model, provider, duration_seconds, commit_hash, branch, actor and status. actor is SKYLOS_ACTOR, the CI-reported user, or the HEAD commit's author, else null; never your operating-system user name. No source, paths, finding text, prompts or model output.
Three things reach Skylos Cloud without such a command, and none sends code or findings: a scan downloads your Cloud custom rules when a token can be found (SKYLOS_CUSTOM_RULES='[]' skips it); skylos doctor checks your credit balance (--format json skips it); and the MCP server started with SKYLOS_API_KEY checks the key every 15 minutes and deducts credits for paid tools.
skylos feedback makes no request itself: it opens a form on skylos.dev (or, with --github, GitHub's issue form) in your browser. The page address carries the Skylos version, OS, Python version and the last failed command with paths and secrets masked; your message is sent only when you press Send.
Package lookups on other hosts send package names and versions, never source: OSV for dependency checks, and PyPI, npm, the Go proxy and JSR for packages that don't exist (on by default in skylos done, skylos verify, agent scan, agent pre-commit and the agent hooks). Dependency checks can also fetch GitHub fix commits, with GITHUB_TOKEN if it is set. LLM commands send code excerpts to the model provider you configure, and skylos cicd review posts PR comments through gh.

Every request, its trigger and its off switch: docs/privacy-and-network.md.

Agent Harness Artifacts

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 for skylos agent test runs.

The current harness state is observable and replay-validated. It is not yet a resume mechanism for continuing interrupted verification runs.

Install Options

# 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-provenance

The 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-provenance

If a Python file cannot be parsed, Skylos names it as not analysed, marks coverage incomplete, and reports every other finding; the file is never treated as clean. The exit code is decided on the code that was analysed; --strict exits 2 instead, and so does a scan where most of the code could not be analysed. See Exit Codes And Incomplete Analysis.

See Installation for source installs, container usage, and optional dependencies.

Configure Templates And Vibe Checks

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 = false

Template 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.

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.toml
skylos.toml
pyproject.toml with a [tool.skylos] table (a pyproject.toml without one is skipped, so it no longer hides the settings above it)

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"

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. 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.

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. 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.

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; see What a full scan leaves out.

Language Support

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, type and docblock references, Laravel conventions, plus taint-style security sinks and sources
Rust	Experimental⁴	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 native skylos-go engine. From 4.50 the PyPI wheels for Linux, macOS and Windows (x86_64 and arm64) include it; the container image includes it and the official GitHub Action builds it. Elsewhere, skylos doctor prints the command that builds it. Without it only Go quality checks run and the Go files are reported as not analysed; 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 them as not analysed (SKY-ANALYSIS-INCOMPLETE, incomplete coverage) instead of skipping them silently; skylos doctor shows whether Dart support is installed.

⁴ Rust dead code is experimental: trait-method calls, pub items used across crates, re-exports, macros and #[bench] functions are not resolved, and a hand-checked sample on ripgrep found no true positives. Rust candidates are capped at confidence 40, below the default threshold, so they are not listed unless you pass --confidence 40; the scan says so in one line. rustc's own unused_imports and dead_code lints cover private items.

"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, it names them as not analysed, marks coverage incomplete and never reports them as clean. A few stray .go files are a coverage warning; when most of the code is Go the scan exits 2. Run skylos doctor to verify engine availability: it prints the version-matched build command, and SKYLOS_GO_BIN points Skylos at a separately built engine. The container image includes the engine and the official GitHub Action builds it automatically.

See Rules Reference for rule families and scanner scope.

Config And Deployment Support

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

With --danger or -a, a directory scan inside a Git worktree also checks that worktree's root .github/workflows/*.yml / *.yaml and .gitlab-ci.yml. For example, skylos src --danger checks the CI configuration that applies to src while keeping source, container and deployment analysis in src. Unrelated staged or unstaged edits do not narrow a full scan. Explicit diff filters still select changed configuration files; a single-file scan stays limited to that file. See scan scope.

Other Workflows

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

Check an Exact GPU Release Artifact

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/app

To 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(...).

Benchmark Snapshot

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 uncertain

Jev-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.

Real-project regression testing

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.

Project Evidence

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.

Integrations

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 uploads
skylos cicd init --no-upload --risk-review         # plus the "Skylos risk review" check

The 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.

Documentation Map

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
Risks a pull request should not merge on a bot's approval (`skylos cicd risk-review`)	Risk review
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
Every network request the CLI can make, and how to turn each off	What leaves your machine
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

Common Questions

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 on your machine with no account or key; their dependency and package checks still query public registries (see What Leaves Your Machine).

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. A removed security control, such as a deleted auth decorator (SKY-L021), is still reported with --diff, including when the change only deletes the decorator line.

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.

Contributing And Support

Report security issues through SECURITY.md.
Report a problem privately with skylos feedback, which opens a prefilled form at skylos.dev/feedback. The page address carries the Skylos version, OS, Python version and the last failed command (paths and secrets masked); your message is sent only when you press Send. No account needed.
Open public bugs and false-positive reports with minimal repros (skylos feedback --github prefills the issue form).
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.

License

Skylos is licensed under the Apache License 2.0.

Available Tools

16 tools

analyzeFind dead codeA

Read-only

Find dead code: unused functions, classes, imports, variables, parameters and files.

Use this to list cleanup candidates in a project. Returns JSON with a summary and per-category findings (file, line, name, confidence) plus _run_id; the full result is stored locally and can be read from the skylos://results/{run_id} resource. Read-only: it never edits code. Findings are candidates: before deleting one, check for dynamic use (getattr, string dispatch, entry points, framework decorators, tests). A non-empty analysis_errors means analysis or verification was incomplete; do not treat the findings as a complete scan.

Defect and Review records remain complete. Advice is grouped by default; expand_advice=True includes every Advice record. Read _result_uri for the complete saved result without rescanning.

Works without SKYLOS_API_KEY (5 calls/day); higher limits with a key.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`expand_advice`	No	Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.
`exclude_folders`	No	Folder names to skip, e.g. ["migrations", "scripts"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: the read-only nature is restated, results are persisted locally and readable via the `skylos://results/{run_id}` resource, findings are explicitly advisory candidates, and a non-empty `analysis_errors` signals an incomplete scan. It even discloses the rate-limit profile (works without an API key at 5 calls/day).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and return shape are front-loaded and most sentences earn their place. The "Defect and Review records remain complete" paragraph introduces categories (Defect/Review) not referenced elsewhere, which slightly muddies an otherwise tight description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema being present, the description still conveys the important non-obvious facts: candidate nature of findings, the persistence resource, the analysis_errors caveat, and usage limits. An agent has everything needed to run it and interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds a little meaning for expand_advice (grouped Advice by default) and reiterates `_result_uri`, but confidence and exclude_folders semantics live almost entirely in the schema, so it does not clearly exceed the schema's own value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource and enumerates the exact categories scanned (unused functions, classes, imports, variables, parameters, files), so an agent knows precisely what it produces. It does not differentiate from the close sibling verify_dead_code, which is left unmentioned, so it falls just short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this to list cleanup candidates in a project" gives clear positive usage context, and the warning to check dynamic use before deleting is useful preconditions guidance. However, it names no alternative tool (e.g. verify_dead_code or generate_fix) and states no explicit when-not, so alternatives are left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

architecture_checkCheck architectureA

Read-only

Report architecture findings for a project: module coupling, cohesion and circular dependencies.

Returns JSON with the architecture findings and _run_id. Read-only and local. Use quality_check for function-level issues.

Defect and Review records remain complete. Advice is grouped by default; expand_advice=True includes every Advice record. Read _result_uri for the complete saved result without rescanning.

Requires SKYLOS_API_KEY: this tool returns an authentication error unless the MCP server is started with SKYLOS_API_KEY set. Without a key only analyze works (5 calls/day). The local CLI needs no key: skylos verify <file> and skylos agent install-hooks.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`expand_advice`	No	Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.
`exclude_folders`	No	Folder names to skip, e.g. ["migrations", "scripts"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover read-only/local safety, but the description goes further: it discloses the authentication failure mode, the degraded no-key quota (analyze only, 5 calls/day), the default grouping of Advice records, and that _result_uri allows retrieving saved results without rescanning.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and alternative, then prerequisites, which is a sensible order. However, the sentence 'Defect and Review records remain complete' is cryptic and unexplained, and the advice/_result_uri material is somewhat bolted on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with an output schema, the description supplies everything extra an agent needs: auth requirement, failure behavior, result-retrieval path, and sibling routing. Nothing required to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the description largely restates it (expand_advice grouping, _result_uri availability) rather than adding new meaning. It says nothing about path resolution or confidence semantics beyond what the schema already documents, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource plus the exact analysis surface: module coupling, cohesion, and circular dependencies. It explicitly contrasts with quality_check ('function-level issues'), so an agent can separate the two siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternative tool and the condition that selects it ('Use quality_check for function-level issues'), and adds a hard prerequisite: SKYLOS_API_KEY must be set or the call fails. It even notes the no-key CLI fallback, which is unusually actionable routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_fixGenerate a dead-code removal patchA

Destructive

Build a unified-diff patch that removes (or comments out) dead code found by static analysis, after grep verification drops findings that are still referenced.

Returns the diff, patch summary, validation errors and applied status. With apply=False (default) it previews changes; with apply=True it edits files if patch validation succeeds. Refuses to run when the analysis or grep verification was incomplete. Review the diff and run trusted tests before keeping it.

ParametersJSON Schema

Name	Required	Description	Default
`mode`	No	"delete" removes dead code; "comment" comments it out instead.	delete
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`apply`	No	False (default) previews the unified diff. True also writes changes when patch validation succeeds.
`min_safety`	No	Skip findings whose safety score (0.0-1.0; imports score highest, methods lowest) is below this value.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it as destructive and non-read-only, but the description adds substantial context beyond them: refusal conditions, patch-validation gating, the 5 calls/day unauthenticated limit, the exact auth error behavior, and an explicit advisory to review the diff and run trusted tests. This is unusually rich behavioral disclosure for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action, then layers return values, apply semantics, and prerequisites in short paragraphs. Every sentence carries information, though the return-value sentence is partially redundant given an output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers what the tool does, its preconditions, its auth model, its destructive path, and its safety advisory. With an output schema present it does not need to detail return values, and nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so mode, path, apply, and min_safety are already documented at the parameter level. The description restates the apply default and preview/write distinction but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and artifact: 'Build a unified-diff patch that removes (or comments out) dead code found by static analysis,' and clarifies the pre-filtering by grep verification. This distinguishes it from siblings like verify_dead_code (detection) and analyze (analysis), so an agent can tell which tool actually produces a patch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains the apply=False preview vs apply=True write path, the precondition (refuses when analysis or grep verification was incomplete), and the auth requirement that gates it. It also routes the agent: without SKYLOS_API_KEY only `analyze` works, and it names the no-key local CLI alternatives (`skylos verify`, `skylos agent install-hooks`).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_security_contextSummarize security contextA

Read-only

Summarize a project's security setup: detected web frameworks, auth decorators and middleware, security headers, rate limiting, input validation and a supported Skylos YAML policy file.

Use it before reviewing or writing security-sensitive code to learn the project's conventions. Returns JSON. Read-only and local.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Project directory. A relative path resolves against the MCP server's working directory.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, non-destructive, closed-world behavior, and the description adds substantial context on top: it returns JSON, runs locally, requires SKYLOS_API_KEY or fails authentication, and without a key only `analyze` works at 5 calls/day. That auth/rate-limit/fallback disclosure is exactly the kind of behavior an agent cannot get from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and the when-to-use line, then appends the auth caveat. The caveat paragraph is long (API key, 5 calls/day, two CLI commands) but each element is actionable for an agent deciding whether the call will succeed, so it largely earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be enumerated, and the description correctly just notes 'Returns JSON'. With one fully documented parameter plus annotations and a rich auth/alternatives section, the definition is nearly self-sufficient; only the sibling boundaries (versus security_scan) remain unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already explains that `path` is the project directory and how relative paths resolve. The description adds no further meaning about the parameter, so the baseline 3 applies for a single fully-documented param.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Summarize a project's security setup') and enumerates exactly what is summarized: frameworks, auth decorators/middleware, headers, rate limiting, validation, Skylos policy file. That is far more specific than its siblings, but it never contrasts itself with closely-related siblings such as security_scan, quality_check or analyze, leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear use condition: 'Use it before reviewing or writing security-sensitive code to learn the project's conventions.' It also tells the agent when the tool is unusable (no SKYLOS_API_KEY) and what still works instead ('analyze', or the local CLI). It does not, however, explain when to prefer security_scan or the other scan tools over this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_triage_suggestionsSuggest triage decisionsA

Read-only

Suggest accept or dismiss for current findings, based on decisions recorded with learn_triage in this project.

Returns JSON suggestions with finding fingerprints, suggested actions and confidence, plus the number of learned patterns. Read-only and local.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Project directory. A relative path resolves against the MCP server's working directory.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description confirms this is local and read-only. It goes further by disclosing an auth failure mode (returns an authentication error without SKYLOS_API_KEY) and a fallback rate limit of 5 calls/day for `analyze`. That auth/rate-limit context is real value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and the learn_triage dependency lead, which is the right front-loading. The closing sentence on CLI alternatives is useful but slightly tangential and lengthens the definition beyond what is needed to call this tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with an output schema and full annotation coverage, the description covers purpose, dependency, auth prerequisite and rate limits. The return-shape sentence is somewhat redundant given the output schema, but nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter at 100% schema description coverage — including the relative-path resolution rule — the schema already carries the semantics, and the description adds nothing further about `path`. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (suggest) and resource (triage decisions for current findings) and ties the behavior to a named sibling, `learn_triage`, which supplies the learned decisions. An agent can immediately distinguish this read-side suggester from the write-side recorder.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the precondition clear — suggestions exist 'based on decisions recorded with `learn_triage` in this project' — so the agent knows to call learn_triage first. It also notes the API-key requirement that gates whether the tool works at all, but it does not explicitly name alternatives (e.g., the local CLI path) as a routing decision.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

health_scoreAssess codebase healthA

Read-only

Assess a project through separate Risk, Maintainability and Dead code readouts.

This tool retains its health_score name for compatibility but no longer creates a blended numeric grade. Gate policy remains independent. Returns assessment, coverage, finding counts and _run_id. Read-only and local. Advice is grouped by default; expand_advice=True includes every Advice record. Read _result_uri for the complete saved result.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`expand_advice`	No	Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.
`exclude_folders`	No	Folder names to skip, e.g. ["migrations", "scripts"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults.
`include_quality`	No	Include code-quality findings in the assessment.
`include_secrets`	No	Include hard-coded secret findings in the assessment.
`include_security`	No	Include security findings in the assessment.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description adds real value on top: the API-key prerequisite and its failure mode, the fact that gate policy is independent of the score, and the _result_uri pointer for the full saved result. Only the auth-exception behavior is described; no rate limits beyond the 5 calls/day for the sibling are given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and compatibility note are front-loaded well, but the closing CLI tangent ('The local CLI needs no key: skylos verify...') is out of scope for an MCP tool definition and dilutes the message. The dense multi-clause sentences require re-reading.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter read-only assessment tool with an output schema, the definition covers the prerequisites (API key), the semantics change (no blended grade), the result-access pointer (_result_uri) and expansion toggle. With the output schema carrying return details, nothing critical is missing beyond explicit sibling selection guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter (including expand_advice and confidence) is already documented by the schema, which sets the baseline at 3. The description restates expand_advice's default/expansion behavior without adding syntax or new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource ('Assess a project') and enumerates the three readouts (Risk, Maintainability, Dead code), and it clarifies the tool no longer produces a blended grade despite the legacy name. It distinguishes itself reasonably from generic siblings but never explicitly contrasts with analyze, quality_check, or security_scan, which are the closest candidates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states an important gate ('Requires SKYLOS_API_KEY... Without a key only `analyze` works') which implicitly routes an unauthenticated agent to a sibling, but there is no explicit when-to-use-this-vs-quality_check/security_scan guidance. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

learn_triageRecord a triage decisionA

Record whether a finding was accepted or dismissed so get_triage_suggestions can learn from it.

Writes the decision to the project's local Skylos state.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Project directory. A relative path resolves against the MCP server's working directory.
`action`	Yes	"accept" (real issue) or "dismiss" (false positive).
`action_id`	Yes	The finding's `fingerprint` from a scan result.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description goes further: it discloses that the decision is persisted to the project's local Skylos state, that the call fails with an authentication error without SKYLOS_API_KEY, and the 5 calls/day quota on the unauthenticated path. That is exactly the failure-mode and persistence context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and feedback-loop rationale are front-loaded in the first sentence, followed by the write target and auth constraint. The trailing CLI sentence is slightly tangential for a description of this specific tool, but it earns its place by routing the agent when no key is available.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-required-parameter mutation tool with an output schema, the description covers purpose, when to use it, authentication requirements, failure behavior, persistence target, and alternatives. Return values are handled by the output schema, so nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% – path, action, and action_id each have their own description, including the accept/dismiss enum values. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Record whether a finding was accepted or dismissed') and ties it to a named sibling, `get_triage_suggestions`, explaining the feedback loop. An agent can distinguish this from the other triage/scan siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit about when to call it (after accepting/dismissing a finding), the prerequisite (SKYLOS_API_KEY must be set or it errors), and the alternatives when the key is absent (only `analyze`, or the local CLI `skylos verify`/`skylos agent install-hooks`). This is genuine when/when-not guidance with named fallbacks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

provenance_scanAttribute changes to agents or humansA

Read-only

Report available evidence of AI-agent, bot and human contributions.

Combines git signals since the base (agent bot accounts, Co-authored-by and AI declaration trailers, agent-named commit subjects) with recorded local attribution evidence. Returns JSON with per-file attribution, evidence and coverage status. Commit declarations do not establish line authorship; missing evidence remains unknown. Read-only and local.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Project directory. A relative path resolves against the MCP server's working directory.
`diff_base`	No	Git ref to compare against. Omit to use the CI base branch when one is set, otherwise origin/main.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only/non-destructive/closed-world, and the description adds substantial context beyond them: the API-key requirement and the exact auth error without it, the 5-calls/day limit for `analyze`, no-key local CLI alternatives, and the epistemic caveat that commit declarations do not establish line authorship. This is exactly the behavioral detail annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, followed by caveats and prerequisites in a logical order; every sentence carries information. Slightly dense but no wasted filler, and the final CLI/auth paragraph stays relevant to correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analysis tool with full schema coverage, an output schema, and rich annotations, the description covers purpose, evidence sources, return shape, epistemic limits, and the auth prerequisite. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both `path` and `diff_base` are already documented. The description reinforces the base-ref concept ('git signals since the base') but adds no format or default nuance beyond the schema's own 'origin/main' fallback note, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Report') and resource (evidence of AI-agent, bot and human contributions) and details the exact git signals inspected. An agent can distinguish it from siblings like verify_agent or verify_change without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the evidence it aggregates ('git signals since the base ... combined with recorded local attribution evidence'), but there is no explicit when-to-use versus verify_agent or the other verification siblings. The key/auth paragraph gives a fallback route (local CLI, or `analyze`) rather than invocation guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

quality_checkCheck code qualityA

Read-only

Report code-quality issues: high complexity, deep nesting, long functions, duplicate branches and similar maintainability findings.

Returns JSON with findings (rule ID, file, line, message) and _run_id. Read-only and local.

Defect and Review records remain complete. Advice is grouped by default; expand_advice=True includes every Advice record. Read _result_uri for the complete saved result without rescanning.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`expand_advice`	No	Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.
`exclude_folders`	No	Folder names to skip, e.g. ["migrations", "scripts"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description adds substantial context beyond them: the auth requirement and its failure mode, a rate limit ('5 calls/day'), the default advice-grouping behavior, and the _result_uri escape hatch for full results without rescanning.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and output shape are front-loaded, and the auth/CLI notes earn their place as call-blocking prerequisites. It is slightly choppy with several short stacked statements, but there is little wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is covered, and the description supplies the critical missing pieces an agent needs — auth requirement, rate limit, grouping default, and where to read full results. Only sibling selection guidance is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries confidence, path, exclude_folders and expand_advice semantics. The description restates expand_advice grouping and hints at the _result_uri path but adds no syntax or meaning the schema lacks, landing at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Report code-quality issues') and enumerates the finding types it produces (complexity, deep nesting, long functions, duplicate branches, maintainability). This lets an agent distinguish it from security_scan/secrets_scan/architecture_check by scope, though it never explicitly names the sibling it is not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides real prerequisite context (SKYLOS_API_KEY required, error otherwise; without a key only `analyze` works at 5 calls/day; the local CLI needs no key). However, it never states when to choose quality_check over the sibling analysis tools (architecture_check, health_score, verify_dead_code), so sibling routing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remediatePlan or apply LLM fixesA

Destructive

Plan or apply LLM-generated fixes for Skylos findings in a project.

With dry_run=True (default), static analysis returns a remediation plan without calling a model or changing files. With dry_run=False, it generates fixes and can edit files in place: this needs the skylos[llm] extra and provider configuration (including credentials when required), and sends affected code to that provider. It does not run your tests. Review every change and run trusted tests before keeping it.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`model`	No	LLM model name passed to the provider (e.g. gpt-4.1 or a Claude model). Configure the provider's credentials in the MCP server's environment when required by that provider.	gpt-4.1
`dry_run`	No	True (default) only plans the fixes. False writes the generated edits to files in `path`.
`severity`	No	Only fix findings at this severity or above: critical, high, medium or low.
`test_cmd`	No	Not supported over MCP; non-empty values are rejected. Run tests yourself after reviewing the fixes.
`max_fixes`	No	Maximum number of findings to fix in this run.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing that dry_run=False sends affected code to a third-party provider (reinforcing openWorldHint), edits files in place (reinforcing destructiveHint), requires the skylos[llm] extra and credentials, does not run tests, and demands review. This is exactly the behavioral context annotations alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and mode split, and most sentences carry real information. It is somewhat long, and the trailing local-CLI/`analyze` note, while useful, is tangential to invoking this tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-risk mutation tool with 6 parameters and an output schema, the description covers the necessary prerequisites, data-flow implications, and post-run caution. Return values are handled by the output schema, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all six parameters are already documented in the schema, establishing a baseline of 3. The description reinforces the dry_run and model semantics and adds the credential/environment angle, but adds little syntax or format detail beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (plan or apply LLM-generated fixes) and resource (Skylos findings in a project), and clearly splits the two operating modes. It does not, however, distinguish itself from the nearby sibling `generate_fix`, which sounds like it may overlap, leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit conditional context: dry_run=True plans only, dry_run=False edits in place, and it names prerequisites (skylos[llm], provider config/credentials, SKYLOS_API_KEY) plus what happens without a key (only `analyze` works, 5 calls/day). It lacks an explicit statement of when to prefer this over `generate_fix` or `validate_code_change`, so it falls short of a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

secrets_scanFind hard-coded secretsA

Read-only

Find hard-coded secrets and credentials (API keys, tokens, private keys, passwords) in source and config files.

Returns JSON with findings (provider, file, line) and _run_id. Secret values are redacted in the output. Read-only and local.

Defect and Review records remain complete. Advice is grouped by default; expand_advice=True includes every Advice record. Read _result_uri for the complete saved result without rescanning.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`expand_advice`	No	Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.
`exclude_folders`	No	Folder names to skip, e.g. ["migrations", "scripts"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/non-destructive/non-open-world, and the description still adds substantial behavior: secret values are redacted in output, Advice is rule-grouped unless expand_advice=True, _result_uri holds the full saved result without rescanning, and the tool hard-fails without SKYLOS_API_KEY at a 5-call/day cap. That is well beyond what the annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed in a sensible order by output shape, flags, and the auth constraint. The middle sentences about 'Defect and Review records' and default Advice grouping feel like carried-over boilerplate for a secrets tool and cost it a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present the description need not explain returns, yet it still names the key fields and the _result_uri escape hatch, and it covers the auth prerequisite that would otherwise cause silent tool failures. The main gap is that the confidence parameter's reference to dead-code findings is unexplained for a secrets scanner.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters are already documented at the schema level, and the description adds little syntax or format detail on top. The one notable line it does add — Advice grouping — is only loosely tied to the expand_advice parameter and the confidence mention of 'dead-code findings' reads as leakage from another tool rather than clarification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — find hard-coded secrets and credentials — and enumerates what counts (API keys, tokens, private keys, passwords) plus the scan targets (source and config files). It does not explicitly distinguish itself from the sibling security_scan or provenance_scan, so an agent must infer the boundary from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides real admission guidance — SKYLOS_API_KEY is required, otherwise only `analyze` works at 5 calls/day, and the local CLI needs no key (`skylos verify`, `skylos agent install-hooks`). However, it never states when to pick this over security_scan or provenance_scan, which is the more common selection decision, so usage is implied rather than specified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

security_scanScan for security issuesA

Read-only

Scan source code for security issues such as SQL and command injection, SSRF, path traversal, eval/exec and unsafe deserialization.

Returns JSON with findings (rule ID, severity, file, line, message) and _run_id. Read-only; the scan runs locally and does not upload code. Use secrets_scan for hard-coded credentials and validate_code_change to check a diff before it lands.

Defect and Review records remain complete. Advice is grouped by default; expand_advice=True includes every Advice record. Read _result_uri for the complete saved result without rescanning.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`expand_advice`	No	Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.
`exclude_folders`	No	Folder names to skip, e.g. ["migrations", "scripts"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, non-destructive, non-open-world behavior, and the description adds substantial context: the scan runs locally and does not upload code, findings are returned with rule ID/severity/file/line/message, `_run_id` is returned, and `_result_uri` can retrieve complete saved results. It also discloses authentication requirements and the fallback behavior when no API key is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and is generally efficient for a complex tool. However, the sentence 'Defect and Review records remain complete' appears without clear connection to a security scan and slightly disrupts the otherwise useful flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and rich annotations, the description still supplies the key operational context an agent needs: authentication requirements, local execution behavior, alternative tools, result retrieval via `_result_uri`, and default vs expanded advice handling. It is complete enough for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents `path`, `confidence`, `expand_advice`, and `exclude_folders`. The description restates the `expand_advice` grouping behavior but does not add meaningful syntax or usage guidance beyond what the schema already provides for the other parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: scanning source code for security issues, with concrete example categories such as SQL/command injection, SSRF, path traversal, and unsafe deserialization. It also differentiates from siblings by naming `secrets_scan` for credentials and `validate_code_change` for diffs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to alternatives: `secrets_scan` for hard-coded credentials and `validate_code_change` to check a diff before it lands. It also states operational prerequisites, including that `SKYLOS_API_KEY` is required and that without it only `analyze` works at 5 calls/day.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_code_changeCheck a diff before it landsA

Read-only

Validate a code diff for security regressions and issues before it lands.

Takes a unified diff and checks for:

Security control regressions (auth, CSRF, TLS, rate limiting removal)
New dangerous patterns (eval, exec, SQL injection, etc.)
Secrets in added code
Hallucinated or undeclared dependencies in added imports and manifest entries (requirements*.txt, pyproject.toml, package.json, go.mod), verified against the package registries. The "registry" field reports "ok", "unreachable" or "error" (lookups incomplete — do not treat pass as clean), or "skipped".

Returns pass/fail with findings.

ParametersJSON Schema

Name	Required	Description	Default
`diff`	Yes	Unified diff text, e.g. the output of `git diff`.
`path`	No	Project root the diff applies to; used to find dependency manifests. Relative paths resolve against the MCP server's working directory.	.
`policy`	No	Optional policy path. Accepted for compatibility but currently not applied to the result.
`check_dependencies`	No	Look up newly added imports and manifest entries in the package registries (PyPI, npm, Go proxy). False skips these network calls.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations (readOnlyHint=true, openWorldHint=true allow network registry lookups). It discloses the registry field's possible values and warns that 'unreachable'/'error' must not be treated as clean, states the auth requirement and the 5 calls/day unauthenticated limit, and names the keyless CLI path. This is unusually rich behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then grouped into a scannable check list, return contract, and requirements. Every sentence carries information, though the dependency-registry explanation and auth paragraph make it longer than strictly minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter validation tool with an output schema, the definition covers everything needed to invoke it correctly: input format (unified diff), the pre-land use case, auth/rate-limit constraints, the degraded-registry caveat, and a keyless alternative. The output schema handles the return shape, so nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so `diff`, `path`, `policy`, and `check_dependencies` are already documented in the schema (including the policy caveat and the registry network-call behavior). The description adds the semantics of the output 'registry' field but nothing new about the parameters themselves; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Validate a code diff') and immediately scopes it to 'security regressions and issues before it lands.' The enumerated check categories (control regressions, dangerous patterns, secrets, hallucinated dependencies) differentiate it clearly from siblings like quality_check, architecture_check, and secrets_scan.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides strong context: pre-land/pre-merge timing, the SKYLOS_API_KEY prerequisite, the fallback when no key is present ('only `analyze` works (5 calls/day)'), and CLI alternatives. It does not explicitly contrast itself with the close siblings verify_change or security_scan, so an agent must still infer which of those to prefer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_agentVerify an AI agent's guardrailsA

Read-only

Statically verify an AI agent's guardrails before deployment.

Deterministic, local pre-deployment agent verification: inventories LLM integrations, runs the defense checks (prompt-injection exposure, dangerous sinks, tool scope, output validation, PII filtering, cost controls), and returns scores, failed checks with remediation, OWASP LLM/Agentic coverage, and a reproducible attestation digest. No model is involved in the verdict and the analysis runs locally; source code is not sent to Skylos Cloud. Optional gate: set fail_on (severity) and/or min_score (0-100).

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Directory of the LLM application or agent to check.	.
`fail_on`	No	Fail the gate if any failed check is at this severity or above: critical, high, medium or low.
`min_score`	No	Fail the gate if the defense score (0-100) is lower.
`owasp_version`	No	Version of that OWASP list; omit for the default (2025 for llm, 2026 for agentic).
`exclude_folders`	No	Extra folder names to skip, comma-separated (e.g. "migrations,scripts"). Added to the default excludes.
`owasp_framework`	No	OWASP list to map results to: "llm" (Top 10 for LLM Applications) or "agentic".	llm

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint=true, openWorldHint=false, destructiveHint=false) are consistent and the description meaningfully extends them: deterministic verdict with no model involved, analysis runs locally, source code is not sent to Skylos Cloud, SKYLOS_API_KEY is required or an auth error is returned, and a concrete rate limit (5 calls/day for analyze).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose and the strongest differentiators (deterministic, local, no model) before the auth details. Slightly long, and the closing CLI/`install-hooks` sentence is tangential to invoking the MCP tool, but most sentences carry real information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter read-only analysis tool with an output schema and full schema descriptions, this covers everything an agent needs: what is analyzed, what is returned, authentication and rate-limit constraints, gating behavior, and the privacy/data-handling posture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description echoes the fail_on severity gate and min_score (0-100) that the schema already documents, adding only the framing that they form an 'optional gate' that fails the run — marginal value beyond structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+mode: 'statically verify an AI agent's guardrails before deployment,' then enumerates exactly what is inventoried and checked (LLM integrations, prompt injection, dangerous sinks, tool scope, etc.). It is clearly distinguishable from siblings such as verify_dead_code, verify_change, and security_scan.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context ('pre-deployment'), explains the optional gate semantics via fail_on/min_score, and names an alternative path when authentication fails ('without a key only `analyze` works'). It does not, however, explicitly state when *not* to use this versus security_scan or quality_check among the many siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_changeVerify an edited file or rangeA

Read-only

Verify a changed file/range for AI-code defects and security bugs.

Returns a narrow, versioned JSON verdict containing AI-code trust findings such as hallucinated references, unfinished generated code, stale references, disabled controls, and dependency hallucinations (checked by default; pass include_dependency_hallucinations=False to skip the registry lookups), plus high/critical security findings (category "security") and hard-coded secrets (category "secret", values redacted) in the selected file/range. Pass include_security_findings=False to skip the security and secret checks.

ParametersJSON Schema

Name	Required	Description	Default
`file`	No	File inside `path` to check; omit to check `path`.
`path`	No	Project root, or a single file to check.	.
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`line_range`	No	Lines to check in `file`, as "START:END" or "START-END" (e.g. "10:40"), or one line number.
`contract_path`	No	Path to a repo-specific AI-code contract file; omit to use the project's default contract if it has one.
`exclude_folders`	No	Extra folder names to skip, comma-separated (e.g. "migrations,scripts"). Added to the default excludes.
`project_context`	No	Also load the rest of the project to resolve cross-file references (slower; may reduce unresolved-reference findings).
`contract_enabled`	No	False disables contract discovery and checks. Omit contract_path when False; combining them is rejected.
`include_security_findings`	No	Include high and critical security findings and hard-coded secrets in the verdict.
`include_dependency_hallucinations`	No	Check imported packages against the package registries. False skips these network calls.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnly/openWorld/destructive annotations: it discloses the SKYLOS_API_KEY requirement and that an auth error is returned without it, notes the registry network lookups, states that secret values are redacted, and mentions the versioned JSON verdict shape and CLI alternative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the paragraphs are organized by capability, output, and auth. Some content (default-on toggles, category names) overlaps with the schema descriptions, but the length is largely justified by the operational constraints it conveys.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with an output schema and annotations, the description covers the important operational gaps: authentication, network behavior, redaction, and finding categories. It omits explicit sibling-routing guidance, which is the main remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description adds real meaning for the two toggle parameters: include_dependency_hallucinations=False skips registry lookups and include_security_findings=False skips security/secret checks, clarifying the cost/behavior tradeoff of each.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (verify a changed file/range) and enumerates the concrete finding classes it returns (hallucinated references, unfinished code, secrets, security findings). However, it does not differentiate itself from similar siblings such as verify_dead_code, security_scan, or quality_check, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for the operation and a partial routing hint (without an API key only `analyze` works), plus how to toggle checks off. It stops short of stating when to prefer this tool over the many overlapping siblings (verify_dead_code, security_scan, provenance_scan), leaving that to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_dead_codeVerify dead code with an LLMA

Read-only

Ask an LLM to review selected unused function, class, import and variable candidates, with its reasoning.

Use it after analyze when you need fewer false positives before deleting code. Sends code snippets and search results to the chosen model provider, so it needs the skylos[llm] extra and provider configuration, including credentials when required. Candidates outside the review limits, or whose use remains uncertain, can remain unverified. Does not edit files. Refuses to run when the static analysis was incomplete.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Directory or file to scan. A relative path resolves against the MCP server's working directory.
`model`	No	LLM model name passed to the provider (e.g. gpt-4.1 or a Claude model). Configure the provider's credentials in the MCP server's environment when required by that provider.	gpt-4.1
`confidence`	No	Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default.
`max_verify`	No	Maximum findings in the main LLM verification pass. Entry discovery, prefiltering and challenges can make additional model calls.
`max_challenge`	No	Maximum number of surviving findings the model re-checks in a second pass.
`exclude_folders`	No	Extra folder names to skip, comma-separated (e.g. "migrations,scripts"). Added to the default excludes.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds substantial context beyond them: code snippets are sent to an external model provider, the `skylos[llm]` extra and provider credentials are required, files are never edited, and it refuses to run on incomplete static analysis.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose followed by prerequisites, limits, and auth. Most sentences earn their place, though the API-key/CLI paragraph is somewhat verbose and restates the credential requirement already implied earlier.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a network-dependent LLM-backed tool with an output schema, the description covers everything an agent needs: prerequisite ordering after `analyze`, external-provider auth, SKYLOS_API_KEY requirement with the 5-calls/day fallback, non-destructive behavior, and the fact that some candidates may remain unverified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are already documented in the schema; the description adds little parameter-level detail beyond implying review-limit behavior ('candidates outside the review limits... can remain unverified'). Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (verify) and resource (dead-code candidates: unused functions, classes, imports, variables) plus the mechanism (an LLM review with reasoning). It is clearly separable from 'analyze' (the static pass) and from sibling scanners like security_scan or quality_check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly sequences usage: 'Use it after `analyze` when you need fewer false positives before deleting code.' It also states when it will not help ('candidates outside the review limits, or whose use remains uncertain, can remain unverified') and when it refuses to run (incomplete static analysis).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

16 tool updatesv4.49.0Oct 14, 2026

Changedanalyze4 fields changed

addedInput schema / properties / confidence / description

Added value: +"Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default."

addedInput schema / properties / exclude_folders / description

Added value: +"Folder names to skip, e.g. [\"migrations\", \"scripts\"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults."

addedInput schema / properties / expand_advice

Added value: +{
+  "default": false,
+  "description": "Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.",
+  "title": "Expand Advice",
+  "type": "boolean"
+}

addedInput schema / properties / path / description

Added value: +"Directory or file to scan. A relative path resolves against the MCP server's working directory."

Addedarchitecture_check

Changedgenerate_fix4 fields changed

addedInput schema / properties / apply / description

Added value: +"False (default) previews the unified diff. True also writes changes when patch validation succeeds."

addedInput schema / properties / min_safety / description

Added value: +"Skip findings whose safety score (0.0-1.0; imports score highest, methods lowest) is below this value."

addedInput schema / properties / mode / description

Added value: +"\"delete\" removes dead code; \"comment\" comments it out instead."

addedInput schema / properties / path / description

Added value: +"Directory or file to scan. A relative path resolves against the MCP server's working directory."

Changedget_security_context1 field changed

addedInput schema / properties / path / description

Added value: +"Project directory. A relative path resolves against the MCP server's working directory."

Changedget_triage_suggestions1 field changed

addedInput schema / properties / path / description

Added value: +"Project directory. A relative path resolves against the MCP server's working directory."

Addedhealth_score

Changedlearn_triage3 fields changed

addedInput schema / properties / action / description

Added value: +"\"accept\" (real issue) or \"dismiss\" (false positive)."

addedInput schema / properties / action_id / description

Added value: +"The finding's `fingerprint` from a scan result."

addedInput schema / properties / path / description

Added value: +"Project directory. A relative path resolves against the MCP server's working directory."

Changedprovenance_scan2 fields changed

addedInput schema / properties / diff_base / description

Added value: +"Git ref to compare against. Omit to use the CI base branch when one is set, otherwise origin/main."

addedInput schema / properties / path / description

Added value: +"Project directory. A relative path resolves against the MCP server's working directory."

Changedquality_check4 fields changed

addedInput schema / properties / confidence / description

Added value: +"Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default."

addedInput schema / properties / exclude_folders / description

Added value: +"Folder names to skip, e.g. [\"migrations\", \"scripts\"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults."

addedInput schema / properties / expand_advice

Added value: +{
+  "default": false,
+  "description": "Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.",
+  "title": "Expand Advice",
+  "type": "boolean"
+}

addedInput schema / properties / path / description

Added value: +"Directory or file to scan. A relative path resolves against the MCP server's working directory."

Changedremediate6 fields changed

addedInput schema / properties / dry_run / description

Added value: +"True (default) only plans the fixes. False writes the generated edits to files in `path`."

addedInput schema / properties / max_fixes / description

Added value: +"Maximum number of findings to fix in this run."

addedInput schema / properties / model / description

Added value: +"LLM model name passed to the provider (e.g. gpt-4.1 or a Claude model). Configure the provider's credentials in the MCP server's environment when required by that provider."

addedInput schema / properties / path / description

Added value: +"Directory or file to scan. A relative path resolves against the MCP server's working directory."

addedInput schema / properties / severity / description

Added value: +"Only fix findings at this severity or above: critical, high, medium or low."

addedInput schema / properties / test_cmd / description

Added value: +"Not supported over MCP; non-empty values are rejected. Run tests yourself after reviewing the fixes."

Changedsecrets_scan4 fields changed

addedInput schema / properties / confidence / description

Added value: +"Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default."

addedInput schema / properties / exclude_folders / description

Added value: +"Folder names to skip, e.g. [\"migrations\", \"scripts\"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults."

addedInput schema / properties / expand_advice

Added value: +{
+  "default": false,
+  "description": "Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.",
+  "title": "Expand Advice",
+  "type": "boolean"
+}

addedInput schema / properties / path / description

Added value: +"Directory or file to scan. A relative path resolves against the MCP server's working directory."

Changedsecurity_scan4 fields changed

addedInput schema / properties / confidence / description

Added value: +"Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default."

addedInput schema / properties / exclude_folders / description

Added value: +"Folder names to skip, e.g. [\"migrations\", \"scripts\"]. When given, this list replaces the default excludes (node_modules, .venv, build, dist and similar); omit it to keep the defaults."

addedInput schema / properties / expand_advice

Added value: +{
+  "default": false,
+  "description": "Include every Advice record instead of rule-group counts; complete results are always available through _result_uri.",
+  "title": "Expand Advice",
+  "type": "boolean"
+}

addedInput schema / properties / path / description

Added value: +"Directory or file to scan. A relative path resolves against the MCP server's working directory."

Changedvalidate_code_change4 fields changed

addedInput schema / properties / check_dependencies

Added value: +{
+  "default": true,
+  "description": "Look up newly added imports and manifest entries in the package registries (PyPI, npm, Go proxy). False skips these network calls.",
+  "title": "Check Dependencies",
+  "type": "boolean"
+}

addedInput schema / properties / diff / description

Added value: +"Unified diff text, e.g. the output of `git diff`."

addedInput schema / properties / path / description

Added value: +"Project root the diff applies to; used to find dependency manifests. Relative paths resolve against the MCP server's working directory."

addedInput schema / properties / policy / description

Added value: +"Optional policy path. Accepted for compatibility but currently not applied to the result."

Addedverify_agent
Addedverify_change

Changedverify_dead_code6 fields changed

addedInput schema / properties / confidence / description

Added value: +"Minimum confidence (0-100) for dead-code findings. Higher values report fewer, surer candidates; 60 is the CLI default."

addedInput schema / properties / exclude_folders / description

Added value: +"Extra folder names to skip, comma-separated (e.g. \"migrations,scripts\"). Added to the default excludes."

addedInput schema / properties / max_challenge / description

Added value: +"Maximum number of surviving findings the model re-checks in a second pass."

addedInput schema / properties / max_verify / description

Added value: +"Maximum findings in the main LLM verification pass. Entry discovery, prefiltering and challenges can make additional model calls."

addedInput schema / properties / model / description

Added value: +"LLM model name passed to the provider (e.g. gpt-4.1 or a Claude model). Configure the provider's credentials in the MCP server's environment when required by that provider."

addedInput schema / properties / path / description

Added value: +"Directory or file to scan. A relative path resolves against the MCP server's working directory."

12 tool updatesv4.10.0May 2, 2026
- Addedanalyze
- Addedgenerate_fix
- Addedget_security_context
- Addedget_triage_suggestions
- Addedlearn_triage
- Addedprovenance_scan
- Addedquality_check
- Addedremediate
- Addedsecrets_scan
- Addedsecurity_scan
- Addedvalidate_code_change
- Addedverify_dead_code

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-10-15 06:20 across 16 tools

Disambiguation3/5

Several tools have overlapping surfaces: security_scan, validate_code_change, and verify_change all report security findings (differing only in scope), and remediate, generate_fix, and verify_dead_code all touch dead-code fixing, while health_score re-aggregates analyze/quality_check/architecture_check outputs. The descriptions do a reasonable job of distinguishing scope and intent, so an agent can mostly disambiguate, but the boundaries are not crisp.

Naming Consistency3/5

Two competing conventions coexist: verb_noun tools (verify_agent, get_security_context, generate_fix, verify_change) and noun_action scan/check tools (security_scan, secrets_scan, provenance_scan, quality_check, architecture_check), plus bare verbs (analyze, remediate) and a noun_score (health_score). It remains readable, but there is no single predictable pattern.

Tool Count4/5

16 tools sits at the edge of the heavy range but is largely justified by the platform's breadth (verification, static analysis, security, quality, architecture, remediation, triage, provenance). A few tools feel redundant (two diff-verification tools, two fix-generation tools), so it is slightly over-scoped rather than egregiously so.

Completeness4/5

The surface covers a coherent lifecycle: context discovery (get_security_context), multiple scanners, dead-code analysis with LLM confirmation and patch generation, remediation, change validation, and a triage learn/suggest loop. Coverage is strong; only minor gaps (e.g. no explicit run/result retrieval or config tooling beyond the referenced resource) keep it from perfect.

Maintenance

ActivityActive

ResponsivenessResponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

Frogeye Security Scanner A
io.github.frogeye-ai
Zero-config MCP security scanner for AI-generated apps. 25K+ vulnerability patterns.
Security Penetration Testing
2
ArchGraphOAuth
dev.archgraph
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code Analysis Software Architecture Developer Tools
2
RogerRat A
io.github.opcastil11
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Communication Agent Orchestration
21
agent-sec A
ai.kernora
Zero-install security baseline for AI coding agents — OWASP/CWE-cited rules over MCP.
Security Code Analysis
221

Related MCP Servers

CodeRAG
RAG Systems Code Analysis Developer Tools
SylphxAI
A
license
Not graded
quality
F
maintenance
A high-performance MCP server providing lightning-fast hybrid code search using TF-IDF and vector embeddings for AI assistants. It enables real-time codebase indexing and semantic retrieval with sub-50ms latency and offline support.
Updated 25 days ago (2026-09-25 05:18 UTC)
12
MIT
loctree-mcpofficial
Code Analysis Developer Tools
Loctree
F
license
Not graded
quality
A
maintenance
Structural code intelligence for AI agents. Scan once, query everything — dead exports, circular imports, dependency graphs, and more. CLI + MCP server.
Updated a month ago (2026-09-20 08:21 UTC)
6 npm
9
-
CodeHealth MCP
Developer Tools Code Analysis Software Architecture
icohangar-ops
A
license
A
quality
A
maintenance
AI-powered codebase health analysis — detects dead code, circular dependencies, coupling issues, and architectural drift. 6 MCP tools for Claude Desktop, Cursor, Windsurf, and Slack.
Updated 13 days ago (2026-10-07 00:25 UTC)
6
61 npm
MIT
AgentsBestFriend
TheRealFloatDev
F
license
Not graded
quality
D
maintenance
Give your AI coding agents superpowers — a local MCP server for fast, token-efficient code navigation, search & analysis.
Updated 6 months ago (2026-04-22 17:34 UTC)
-

What Is Skylos?

Read The Results

Choose the Right Command

Start In 60 Seconds

Check Every Agent Edit (Claude Code, Codex, Cursor)

Common Workflows

What Skylos Catches

Dependency licenses

Give Coding Agents Project Standards

Verify AI Agents Before They Ship

Test Running Agent Behavior

How Skylos Fits

What Leaves Your Machine

Agent Harness Artifacts

Install Options

Configure Templates And Vibe Checks

Language Support

Config And Deployment Support

Other Workflows

Check an Exact GPU Release Artifact

Benchmark Snapshot

Real-project regression testing

Project Evidence

Integrations

Documentation Map

Common Questions

Contributing And Support

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

loctree-mcpofficial