Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .agents/skills/socratic/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
name: socratic
description: Set up a repository after this skill is installed. Asks which agent tools to connect, reads the manifests and the code, and writes rules and skills the person accepts. Use when the person installs this skill, wants a harness, or wants the harness brought up to date.
description: Set up a repository after this skill is installed. Asks which agent tools to connect, reads the manifests and the code, and writes rules and skills the person accepts. Use when the person installs this skill, wants harness instructions, or wants the harness instructions brought up to date.
---

# Socratic

You are already the agent. The person installed this skill. This directory is not the repository to wrap. Do not inspect this skill's own folder for the project's manifests, and do not clone the harness repository.
You are already the agent. The person installed this skill. This directory is not the repository to wrap. Do not inspect this skill's own folder for the project's manifests, and do not clone this repository.

If they just installed you, set the repository up before you do anything else.

Expand All @@ -22,11 +22,11 @@ Four steps ship in this folder. They are not separate skills. Read each file and
3. `interview.md`
4. `verify.md`

If one is missing, stop. Do not invent a replacement. Do not run a harness program. There is no CLI.
If one is missing, stop. Do not invent a replacement. Do not run a separate program. There is no CLI.

## Rules for every step

- Do not delete, move, or overwrite a file this harness did not write. You may edit a rule, skill, or MCP entry this harness wrote. You may not delete source files, manifests, `.git`, or a tool directory that was already there.
- Do not delete, move, or overwrite a file this skill did not write. You may edit a rule, skill, or MCP entry this skill wrote. You may not delete source files, manifests, `.git`, or a tool directory that was already there.
- Do not create, delete, or modify `.git`.
- Do not invent a practice the person did not state. An answer that does not change how an agent should work produces no file.
- Do not install a skill, an MCP server, or a package until the person says yes in this chat. Do not treat silence as a yes.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/socratic/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ If `.cursor`, `.claude`, or `.codex` is already a real directory, leave it. Do n

```mdc
---
description: Read the harness in .agents before editing.
description: Read the harness instructions in .agents before editing.
alwaysApply: true
---

Expand Down
2 changes: 1 addition & 1 deletion .out-of-scope/no-cli.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
The harness is the socratic skill and the four step files it reads. A program the skill shells out to, and a second command name, are out of scope.
This project is the socratic skill and the four step files it reads. A program the skill shells out to, and a second command name, are out of scope.
19 changes: 15 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<img src="docs/soc.jpg" alt="SOC, a black-and-white stick-figure sketch holding a scroll with a question mark" width="280" />
</p>

Human intent becomes a harness an agent can follow. This repository is one skill, `socratic`. You install it, open an agent in your repository, and the agent does the work. There is no CLI.
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.

Expand All @@ -16,15 +16,26 @@ npx skills add beelarr/soc

That installs one skill, `socratic`. 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. Update it later with `npx skills update`.
Add `-g` to install the skill for every repository on your machine. `npx skills update` updates the installed `socratic` skill. It does not by itself improve the harness instructions in the repository. That is another session.

## 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 finished run leaves a harness in the repository:
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`.
- 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.

Expand Down
2 changes: 1 addition & 1 deletion SCOPE.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,6 @@ A wish with no session behind it can wait. Put how-do-I questions in discussions

Read .out-of-scope/ before you file. Those notes are decisions, not a backlog.

Also out of scope: a setting that only your tool needs, a branch for one harness, and a change that exists to match one person's habits. Put that in your own AGENTS.md, or fork the skill.
Also out of scope: a setting that only your tool needs, a branch for one tool, and a change that exists to match one person's habits. Put that in your own AGENTS.md, or fork the skill.

If an issue is too thin to judge, we will ask once. If there is no reply, we will close it.
2 changes: 1 addition & 1 deletion test/skill-checks.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ const REQUIRED = [
["SKILL.md", "interview.md"],
["SKILL.md", "verify.md"],
["SKILL.md", "They are not separate skills"],
["SKILL.md", "Do not delete, move, or overwrite a file this harness did not write"],
["SKILL.md", "Do not delete, move, or overwrite a file this skill did not write"],
["SKILL.md", "Do not create, delete, or modify `.git`"],
["setup.md", "Do not delete it"],
["setup.md", "package.json"],
Expand Down
2 changes: 1 addition & 1 deletion test/skills.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import { test } from "node:test";
import { checkSkills } from "./skill-checks.js";

test("the five skills are the harness, and none of them invokes a CLI", async () => {
test("socratic is the only installable skill, and none of the files invokes a CLI", async () => {
const result = await checkSkills();
assert.deepEqual(result.failures, []);
});
Loading