sokrates
Skill3 starsChanged 31 days agoMITView on GitHub
Start here for anything about Sokrates (sokrates.dev), the source-code analysis tool: analyze a repository, understand a codebase, set up or improve the Sokrates config, scan for risks, build a landscape of many repositories, improve code where it matters. Finds out where the user is and routes to the right sokrates-skill, running Sokrates when that is the next step.
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 37
When the user named what they want, start from that and use the situation only to check the prerequisites - "scan this repo" with no …
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Sokrates (start here)
Sokrates measures a codebase - size, complexity, duplication, churn, coupling, contributors - and writes
one analysis per repository (_sokrates/) or one landscape over many (_sokrates_landscape/). The
other sokrates-skills configure it, add AI findings on top of its data, and act on what it found.
This skill decides which of them applies now. Do not guess the situation: measure it.
1. Find out where you are
python3 <this-skill-path>/scripts/situation.py [folder] [--json <scratch>/situation.json]It prints the situation (repository or landscape, analysis present and how old, configuration tuned or not, AI findings, how Sokrates can be run on this machine) and ranked next steps, each naming the skill or command. Trust the order: a step only makes sense once the ones before it are done - findings built on an untuned configuration describe the wrong scope, an improvement measured on a stale analysis proves nothing.
2. Act on the first applicable step
| the script says | do |
[install] | Sokrates is not on this machine. Tell the user the options (Docker image ghcr.io/zeljkoobrenovic/sokrates, the CLI jar) and stop; do not substitute your own analysis. |
[analyze] | Run the printed command in the repository root (it includes git history extraction, init when there is no configuration, and the reports). Then re-run situation.py. |
[sokrates-repo-config] [sokrates-decompositions] [sokrates-features-of-interest] [sokrates-people-config] | Load that skill and follow it. Every change to config.json is followed by sokrates analyze (or generateReports), so the data the next steps read is current. |
[full-scan] | Load full-scan; it chooses the bundle (basic, a deep-dive family, or full) from what the user asked. A named worry ("is it secure", "well tested") goes straight to that scanner family. |
[sokrates-scan-core] | Findings without an explorer page: run the printed render_findings.py. |
[sokrates-improve] | Load sokrates-improve; it selects a target from the data, changes the code on a branch and proves the effect by re-measuring. |
[analyzeLandscape] [sokrates-landscape-config] [sokrates-virtual-landscapes] | Landscape work: run the printed command, then the landscape skills. |
When the user named what they want, start from that and use the situation only to check the prerequisites - "scan this repo" with no analysis means: analyze first, say so, then scan.
3. Running Sokrates
situation.py prints the form that works here, in this preference: sokrates on the PATH, the jar from
SOKRATES_JAR, or Docker (docker run --rm -v "$(pwd):/code" ghcr.io/zeljkoobrenovic/sokrates <command>).
The commands that matter:
| command | does |
analyze | one repository, in place: git history, configuration if missing, reports under _sokrates/ |
analyzeGitRepo -url <git url> | clone, analyze, keep only the analysis under <owner>/<repo>/ |
analyzeLandscape [-urls repos.txt] | analyze every listed repository, then the landscape over all analyses under the root |
analyzeGitHubOrg -org <login> / analyzeGitLabGroup -group <path> | a whole organization, one landscape per org |
-dataOnly | only the data.zip - enough for every skill, much faster, no HTML |
-ai claude|codex|gemini | run the agent with the skills after each analysis (incremental, -aiMaxRepos, -aiForce) |
Builds differ: older ones lack -dataOnly, -ai, -prune, the organization commands, or match scope
patterns against the whole path. Do not guess from dates — probe:
python3 <this-skill-path>/scripts/capabilities.py [--data _sokrates/reports/data/data.zip] [--json <scratch>/capabilities.json]It runs the detected CLI, parses its usage into commands and options, says which capabilities the
installed build has and lacks (and which jar a sokrates wrapper runs), and with --data which exports
an analysis holds (history zip, units, duplicates, temporal dependencies, …). When a capability is
missing, say so and use the older form (extractGitHistory + init + generateReports instead of
analyze, a full run instead of -dataOnly) rather than failing on an unknown flag.
4. Which skill when (the map)
| you want | skill |
| the configuration right: scope, file classes, thresholds | sokrates-repo-config |
| meaningful components | sokrates-decompositions |
| debt markers, security-sensitive code, integrations, feature flags tracked | sokrates-features-of-interest |
| one person = one contributor | sokrates-people-config |
| what this codebase is, does, how it is built | full-scan (basic) |
| how good it is at testing, reliability, maintainability, risk | full-scan family quality |
| performance, storage, network, observability | full-scan family runtime |
| security, infrastructure, configuration | full-scan family security |
| the findings format, validation, explorer, merge, diff, re-check, summary | sokrates-scan-core |
| make the code better where the numbers say so, and prove it | sokrates-improve |
| a landscape: what gets aggregated, tags, teams | sokrates-landscape-config |
| sub-landscapes by naming, technology, team, activity | sokrates-virtual-landscapes |
| the portfolio story over a scanned landscape: concentration, recurring findings, coverage, priorities | landscape-synthesis-scan |
A named worry goes straight to its scanner (each writes validated findings; full-scan runs bundles of them):
| the question | scanner |
| what does this software do, for whom, through which entry points | functionality-scan |
| what do the domain concepts mean, where does the language drift | domain-language-scan |
| how is it structured, what depends on what, is the architecture eroding | architecture-scan |
| how did it get here, what is the trajectory | evolution-scan |
| which languages, frameworks, libraries, build and infra tooling | tech-stack-scan |
| how is it built, tested, released, deployed | cicd-scan |
| what runtime environment does it declare: Terraform, Kubernetes, Dockerfiles | iac-scan |
| how is it configured, where do settings and secrets come from | configuration-scan |
| how well is it tested, what is untested | testing-scan |
| what does it log, measure, trace; what stays dark | observability-scan |
| what happens when things fail: errors, retries, isolation | reliability-scan |
| where will it be slow, what scales badly | performance-scan |
| where does the data live, how is it versioned and kept intact | storage-scan |
| what does it connect to and listen on, what happens offline | network-scan |
| is it secure: identity, secrets, injection, crypto, trust | security-scan |
| how maintainable, graded per sub-characteristic and component | maintainability-scan |
| which files are risky and why, bus factor, change coupling | risk-synthesis-scan |
5. Rules shared by every skill
- Numbers come from the Sokrates data (
_sokrates/reports/data/data.zip), never from reading the tree and estimating. Findings cite file, line and verbatim snippet and are validated before they are reported. - Reports are generated artefacts: edit
config.json, never a file underreports/. - Say what was done and what was skipped. A scan that did not validate, an improvement that did not move the numbers, an analysis that could not run: report it as such.
In this repository27 other files it gives its agents.
- sokrates-decompositionsSkill
- sokrates-features-of-interestSkill
- sokrates-landscape-configSkill
- sokrates-people-configSkill
- sokrates-repo-configSkill
- sokrates-virtual-landscapesSkill
- sokrates-improveSkill
- architecture-scanSkill
- cicd-scanSkill
- configuration-scanSkill
- domain-language-scanSkill
- evolution-scanSkill
- full-scanSkill
- functionality-scanSkill
- iac-scanSkill
- landscape-synthesis-scanSkill
- maintainability-scanSkill
- network-scanSkill
- observability-scanSkill
- performance-scanSkill
- reliability-scanSkill
- risk-synthesis-scanSkill
- security-scanSkill
- sokrates-scan-coreSkill
- storage-scanSkill
- tech-stack-scanSkill
- testing-scanSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.