Skip to content
beelarrPublic

About

A harness instruction builder

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SOC

SOC, a black-and-white stick-figure sketch holding a scroll with a question mark

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.

Install

npx skills add beelarr/soc

That 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 update

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

Two paths

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 besides socratic after 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.md you already wrote stays. If it does not mention .agents, the skill adds a short pointer at the end.

Any tool

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.

What you get

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.md at the root, if you did not already have one.
  • .agents/ holding the rules and skills.
  • When .cursor, .claude, or .codex is 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.md containing @../AGENTS.md, and only when that file is absent. Codex uses the root AGENTS.md and does not get .codex/AGENTS.md. Copilot and Windsurf get a one-line pointer at AGENTS.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.

The skills

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.json depends 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 main and main is the trunk.

What the skills will not do

  • 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 .codex directory stays. Cursor gets .cursor/rules/agents.mdc. Claude gets .claude/CLAUDE.md only 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.

Repository layout

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.

Verify

npm test

Influences

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

Open source

Feedback

Issues are for a session where the skill did the wrong thing. The standard is SCOPE.md. Questions go to discussions.

About

A harness instruction builder

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages