Human intent becomes harness instructions an agent can follow. This repository is one skill, socratic. You install it in a repository you already have. That repository either has harness instructions or it does not.
SOC asks about what the code is already doing before anyone writes a rule. The skill does not invent a practice the person did not state. An answer that does not change how an agent should work produces no file.
npx skills add beelarr/socThat installs one skill, socratic, from the latest commit on main. Open an agent in the repository you want to wrap. It reads setup.md, research.md, interview.md, and verify.md from its own folder and follows them in that order. Those four files are not separate skills, so they do not take the names setup, research, interview, or verify in the skill list.
Add -g to install the skill for every repository on your machine.
npx skills updateThat replaces an installed copy with the latest main. It updates the skill. It does not by itself improve the harness instructions in the repository. That is another session.
v0.1.0 is the first tagged release. After CI passes on main, the commit messages since that tag publish the next one. fix: is a patch, feat: is a minor, and feat!: or a BREAKING CHANGE: footer is a major. docs: and chore: publish nothing. Install and update follow main, which moves ahead of the tag.
Harness instructions are the documentation an agent follows: AGENTS.md, the rules in .agents/rules/, and the skills in .agents/skills/. Those files are the harness instructions. The skill does not create the repository.
- No harness instructions yet. The repository has no
AGENTS.md, and.agents/has no rules and no skills besidessocraticafter the install. The skill writes the harness instructions from what you accept. - Harness instructions are already there. The skill reads the rules and skills it finds, checks the manifests for what changed, and updates a rule, skill, or MCP entry it wrote when your answer says to. An
AGENTS.mdyou already wrote stays. If it does not mention.agents, the skill adds a short pointer at the end.
The harness instructions have one copy, in .agents. The skill asks which tools to connect: Cursor, Claude, Codex, Copilot, Windsurf, or all of them. A tool that reads some other path still gets a symlink or a one-line import pointing at .agents. It does not get its own copy of the rules and skills.
A first run leaves harness instructions in the repository. A later run leaves the harness instructions that are already there and changes only what you accept:
AGENTS.mdat the root, if you did not already have one..agents/holding the rules and skills.- When
.cursor,.claude, or.codexis missing, a symlink from that directory to.agents, plus that tool's ignore file. If one of those is already a real directory, it stays. Cursor gets.cursor/rules/agents.mdc. Claude gets.claude/CLAUDE.mdcontaining@../AGENTS.md, and only when that file is absent. Codex uses the rootAGENTS.mdand does not get.codex/AGENTS.md. Copilot and Windsurf get a one-line pointer atAGENTS.md. Any other tool gets a symlink or a one-line import to.agents. - Rules in
.agents/rules/and skills in.agents/skills/for the practices you accepted. - Vendor skills and MCP entries only where you said yes.
You do not get a decision log. Ownership, incidents, and open questions stay in the conversation unless they imply a rule or a skill.
socratic is the only skill. It names the repository and then follows the four steps in its folder.
| Step | What it does |
|---|---|
setup.md |
Asks which tools to connect. Writes AGENTS.md, .agents, and the links. Reads package.json and the other manifests. On a later run, reads git log -1 -p for those files. The installed socratic skill does not by itself make a run a later run. |
research.md |
Looks up skills and MCP servers for the dependencies, reads the docs for the version in the manifest, and prepares an offer. It does not install anything. |
interview.md |
Describes the architecture it can see and asks if that is right. Says which skills may be useful and waits for a yes. Writes a rule in the person's words, with no extra ban. |
verify.md |
Opens each file again and quotes a line from that read. A declined install, and an MCP the docs say this version cannot use, must be absent. |
Two examples:
package.jsondepends on Next. Research finds the skill and MCP Vercel publishes. It does not offer an MCP when the docs require a newer version than the manifest.- You say the team is trunk-based. The interview writes a rule that branches come off
mainandmainis the trunk.
- Install a skill, an MCP server, or a package before you say yes.
- Delete a file it did not write. An existing
.cursor,.claude, or.codexdirectory stays. Cursor gets.cursor/rules/agents.mdc. Claude gets.claude/CLAUDE.mdonly if it is absent. Codex does not get.codex/AGENTS.md. - Read
.env,.env.*,*.pem, or*.key. - Invent a stack by reading source files. Dependencies come from manifests. Architecture questions come from the directories and entry points the interview names.
- Upload your repository. A documentation fetch uses a URL the agent shows you first.
| Path | Role |
|---|---|
.agents/skills/socratic/SKILL.md |
The only installed skill. Runs first. |
.agents/skills/socratic/setup.md |
Files, tool links, manifests, later-run diff. |
.agents/skills/socratic/research.md |
Reads the docs for the version in the manifest and prepares an offer of skills and MCP servers. It does not write a doc. It does not install anything. |
.agents/skills/socratic/interview.md |
Code reading, vendor asks, rules and skills. |
.agents/skills/socratic/verify.md |
The file check at the end of a run. |
test/skills.test.js |
Checks that socratic is the only installed skill and that the steps still say the limits above. |
npm testThis project owes a lot to Matt Pocock and poteto. Matt's Skills for Real Engineers shaped how we think about grilling a plan before an agent writes code. poteto's How and Poteto mode shaped how we explain architecture, keep changes small, and prove the work.
- LICENSE. MIT, Copyright (c) 2026 Bryon Larrance.
- CODE_OF_CONDUCT.md
- SECURITY.md
Issues are for a session where the skill did the wrong thing. The standard is SCOPE.md. Questions go to discussions.
