Skip to content
This repository was archived by the owner on Sep 23, 2025. It is now read-only.

Commit 3ca1e15

Browse files
nikomatsakisnikomatsakis
committed
Add comprehensive installation guide
- Created src/installation.md with tool-agnostic approach - Added to SUMMARY.md for mdbook integration - Covers global setup (main.md + personal info) and optional project setup - Specific instructions for Claude Code and Q CLI with concrete examples - Practical FAQ addressing common issues - Addresses GitHub issue #13: clearer installation docs and multi-tool support Key improvements over current approach: - Tool-agnostic instructions first, then specific examples - Removes dependency on user install script - Clear two-step process: global + project setup - Real commands and examples from actual usage - Personal voice and practical guidance
1 parent 892efc6 commit 3ca1e15

File tree

2 files changed

+132
-0
lines changed

2 files changed

+132
-0
lines changed

‎src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Summary
22

33
- [Introduction](introduction.md)
4+
- [Installation Guide](installation.md)
45

56
# Collaborative prompting
67

‎src/installation.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Installation Guide
2+
3+
This guide shows how to set up Socratic Shell collaboration patterns with your AI tool. We begin by describing the general process, but you can also find specific instructions for [Claude Code](#claude-code-instructions) and [Q CLI](#q-cli-instructions) below.
4+
5+
## Tool-agnostic instructions
6+
7+
### Global setup
8+
9+
Add the [`main.md`] file to your "global context" along with some basic identifying information (e.g., your name). This file contains a dialog that will be read by the LLM to instruct it in the basics of [collaborative prompting](./collaborative-prompting.md).
10+
11+
[`main.md`]: https://github.com/socratic-shell/socratic-shell/blob/main/src/prompts/user/main.md
12+
13+
For myself, I do it like this:
14+
15+
* Clone the socratic-shell repository onto my local system.
16+
* Update my global context to reference the [`main.md`][] file directly from the checkout and then add something like "My name is Niko. I am a designer of the Rust programming language. I like an informal communication style."
17+
18+
This allows me to `git pull` periodically and pick up the latest iterations.
19+
20+
### Project Setup (optional)
21+
22+
The repo also includes a number of prompts that capture particular patterns that projects can use on an à la carte basis. These are designed to be copied and sync'd with your project, a kind of "poor man's git submodule". The idea is that they should be part of your project repository so that all people working on it share the same working style. The installation script can also update them to the latest versions available on socratic-shell.
23+
24+
To install those scripts run
25+
26+
```bash
27+
curl https://raw.githubusercontent.com/socratic-shell/socratic-shell/main/src/prompts/project/install.sh | bash
28+
```
29+
30+
which will create a `.socratic-shell` directory in your project containing the markdown files from the [project prompts directory][].
31+
32+
[project prompts directory]: https://github.com/socratic-shell/socratic-shell/blob/main/src/prompts/project/
33+
34+
You can then add the ones that you want to your project's context in whatever way befits your tool. As an example, the [CLAUDE.md file on the socratic-shell/dialectic repo](https://github.com/socratic-shell/dialectic/blob/main/CLAUDE.md) includes a line like
35+
36+
```
37+
We track progress in github tracking issues on the repository `socratic-shell/dialectic':
38+
39+
@.socratic-shell/github-tracking-issues.md
40+
```
41+
42+
## Claude Code instructions
43+
44+
### Global Setup
45+
46+
1. **Clone this repository** somewhere permanent on your system:
47+
```bash
48+
git clone https://github.com/socratic-shell/socratic-shell.git ~/socratic-shell
49+
```
50+
51+
2. **Create or edit** `~/.claude/CLAUDE.md` and add:
52+
```markdown
53+
# Your Personal Info
54+
My name is [Your Name] and I prefer [informal/formal] communication style.
55+
56+
# Socratic Shell Collaboration Patterns
57+
@[path-to-socratic-shell]/src/prompts/user/main.md
58+
59+
# Your additional customizations here...
60+
```
61+
62+
### Project Setup (optional)
63+
64+
1. **From your project directory**, run the sync script:
65+
```bash
66+
curl https://raw.githubusercontent.com/socratic-shell/socratic-shell/main/src/prompts/project/install.sh | bash
67+
```
68+
69+
2. **Create or edit** your project's `CLAUDE.md` file and add:
70+
```markdown
71+
# Project Overview
72+
This project is [brief description]. We use GitHub repository [org/repo] for tracking issues.
73+
74+
# Socratic Shell Project Patterns
75+
@.socratic-shell/README.md
76+
77+
# Additional project-specific prompts
78+
@.socratic-shell/github-tracking-issues.md
79+
@.socratic-shell/ai-insights.md
80+
```
81+
82+
## Q CLI instructions
83+
84+
### Global Setup
85+
86+
1. **Clone this repository** somewhere permanent on your system:
87+
```bash
88+
git clone https://github.com/socratic-shell/socratic-shell.git ~/socratic-shell
89+
```
90+
91+
2. **Create a file like `whoami.md` somewhere permanent on your system:
92+
```bash
93+
My name is [Your Name] and I prefer [informal/formal] communication style.
94+
```
95+
96+
3. **Add both of those files to your Q CLI global context by running these commands from inside Q CLI:
97+
```bash
98+
/context add --global [path-to-socratic-shell]/src/prompts/user/main.md
99+
/context add --global [path-to-whoami]/whoami.md
100+
```
101+
102+
### Project Setup (optional)
103+
104+
1. **From your project directory**, run the sync script:
105+
```bash
106+
curl https://raw.githubusercontent.com/socratic-shell/socratic-shell/main/src/prompts/project/install.sh | bash
107+
```
108+
109+
2. **Add chosen pieces of context to your project:** For github tracking issues in particular, you may want to add another file indicating where your github repository is.
110+
```bash
111+
/context add .socratic-shell/github-tracking-issues.md
112+
/context add .socratic-shell/ai-insights.md
113+
```
114+
115+
## Frequently asked questions
116+
117+
### The [`main.md`][] prompt is a dialog, am I supposed to give it to the LLM as context or is this an example for me to read?
118+
119+
Yes. That is, that file is literally what you should give the LLM as context, but it can also serve as an example for you to read. That's kind of the idea (using a dialog helps the LLM get a better idea for how things should go).
120+
121+
### What is this `@filename` syntax? It doesn't seem to work for me.
122+
123+
That is a syntax used by Claude Code to embed prompts from other files. Your tool may have its own syntax, though I've found that many LLMs are smart enough to follow the link regardless if it will be useful.
124+
125+
### The sync script fails, what gives?
126+
127+
Make sure you're in a git repository and have no uncommitted changes in `.socratic-shell/`. The script is designed to be safe and will warn about conflicts. Or file an issue with your details -- this stuff is not exactly widely tested.
128+
129+
### How do I update to newer versions?
130+
131+
For global patterns, `git pull` in your socratic-shell directory. For project patterns, re-run the sync script - it will detect and update changes automatically.

0 commit comments

Comments
 (0)