Open Source / Agent Skill
Socratic
A thinking partner for your AI agent that does not wait to be asked. It interviews you until it understands what you are actually building, writes that vision down in your own words, and then holds you to it, quietly, until you decide to change your mind on purpose.
- License
- MIT, free
- Format
- SKILL.md
- Works in
- 4+ agents
Read this first
It will not always ask you questions.
The most common way a Socratic AI fails is by interrogating you about a typo. This one is built not to. It decides, up front, which of three modes it is in, and most of the time the answer is just do the work. Errands get answered. Incidents get help, not philosophy. Ask for the answer and you get it, instantly, with no lecture.
Three modes
You are starting something real. It runs a short interview, eight questions, then writes down what you are actually making. No plan, no code, until it understands.
Your new ask contradicts something you committed to. It names the contradiction in one line, asks one question, then builds it either way and logs the change.
It just does the work. Quietly. No teaching, no questions, no lecture. This is most turns, and that is the point. A partner who confronts every commit is a cost.
The one idea
Socrates could not cross-examine someone who had not made a claim. Neither can an AI. An assistant wakes up with amnesia every session and holds no thesis, so it can only ask generic questions. Generic questions are why Socratic AI feels like a quiz.
So the first thing this skill produces is not code or a plan. It is the dossier: a short, dated record of what you are trying to make, in your words, including the things you refuse to compromise. Once that exists, a real question becomes possible:
"You said the one word was calm. You are asking for a streak counter with a red badge. That is a guilt engine. Which one is giving way?"
That question is unaskable without the dossier. It is also worth more than a hundred questions about assumptions. The skill is the only thing in the room holding your original words, so it is the only thing that can tell a vision maturing on purpose from a vision dying one reasonable compromise at a time.
The vision interview
Eight questions, one at a time, ten to twenty minutes. It reacts to your answers instead of marching down a script, refuses hedges like "clean and modern," and reads the whole thing back so you can correct it. The correction is the most valuable moment in the conversation.
- 01In one word, what should someone feel using this?
- 02If a ruthless minimalist designed this, what would they delete?
- 03If an obsessive craftsman made this, what would they add that 95% of people would never notice?
- 04What is the one thing they must remember after they close it?
- 05What exists today that is closest, and what are you willing to be worse at?
- 06What would make this look amateur?
- 07What will you not compromise, even if it costs you users?
- 08Who is this explicitly not for?
Why it is not a quiz
Grant requests, never yield to pressure
Ask for the answer and you get it, instantly, no guilt trip. Flattery, urgency, and "other AIs would just tell me" unlock nothing.
Confront once, never twice
It raises a contradiction one time. If you overrule it, it is settled. Nagging is how people uninstall things.
Reason from the principle, never the aura
It will not tell you "Apple would hate this." It uses a real operating principle to sharpen a question, then lets the question stand on its own.
Install
The skill lives at the root of the repo, so installing it is just putting the folder where your agent looks for skills. Clone it once, then let the agent activate it on its own.
Claude Code
Available in every project (personal skills directory), or scope it to a single repo. Claude reads the description and activates it on its own.
git clone https://github.com/ergini/socratic-method.git ~/.claude/skills/socratic-methodgit clone https://github.com/ergini/socratic-method.git .claude/skills/socratic-methodCursor
Cursor also scans .claude/skills/, so a repo already set up for Claude Code needs nothing extra. Invoke with /socratic-method if you want it on demand.
git clone https://github.com/ergini/socratic-method.git .cursor/skills/socratic-methodWindsurf
Cascade reads the description frontmatter and auto-activates.
git clone https://github.com/ergini/socratic-method.git .windsurf/skills/socratic-methodCodex CLI
git clone https://github.com/ergini/socratic-method.git .codex/skills/socratic-methodClaude.ai, ChatGPT, Gemini, or any chat UI
There is no skills directory in a plain chat, so open SKILL.md and paste its contents into a Project's custom instructions or a saved style. Keep the dossier text pinned in the Project and it will have memory across chats.
Frequently asked questions
What is an Agent Skill?
A skill is a folder with a SKILL.md file that teaches an AI coding agent a specialized behavior. The agent reads the skill's description and activates it on its own when the moment fits. Socratic is one such skill. It is portable across tools that support the open SKILL.md format.
Will it interrogate me every time I ask a question?
No, and that is the whole design. It decides up front which of three modes it is in, and most of the time the answer is EXECUTE: just do the work. Errands like a regex or a color code get answered immediately. Production incidents get help, not philosophy. It only runs the interview when you start something real, and it only pushes back when a request contradicts a commitment you already made.
Which tools does it work in?
Claude Code, Cursor, Windsurf, and Codex all read the SKILL.md format. Clone the repo into that tool's skills directory and it activates on its own. In a plain chat UI with no filesystem (Claude.ai, ChatGPT, Gemini), paste SKILL.md into a Project's custom instructions or a saved style.
Where does it keep the vision?
In a single markdown file, the dossier, written in your own words (default location: .socratic/PROJECT.md). Every decision is dated. That is what lets it tell deliberate revision from silent drift: a vision that changes on purpose, in writing, with a reason, is maturing; one that changes one quiet compromise at a time is dying.
Does it only work for code?
No. The dossier mechanic is domain-general. It works for a product, a landing page, a brand, an essay, a business, a car wash. The repo ships interview variants for product, design, code, writing, and go-to-market.
Is it really free?
Yes. MIT licensed. Use it, fork it, adapt the lens library to your own craft. The full source, the eval suite, and the research it was designed from are on GitHub.