claude-md-guide

Original：🇺🇸 English

Translated

Conversationally guides the user to a CLAUDE.md file. Starts by inferring what it can from the repo, asks ~8 core questions, then offers optional depth across business, voice, and working-style topics. Use when the user wants a CLAUDE.md but would rather have a conversation than fill out a form.

15installs

Sourcejamescorbett/colab-skills

Added on2026-04-18

NPX Install

npx skill4agent add jamescorbett/colab-skills claude-md-guide

SKILL.md Content

View Translation Comparison →

CLAUDE.md Guide (conversational)

This is the loose companion to

claude-md-generator

. Instead of marching through 32 fixed questions, you infer what you can, ask what matters, and let the user steer the depth.

Principles

Infer before asking. Skim the repo first. Don't ask questions the code already answers.
Core first, depth optional. Eight questions are non-skippable. Everything else is opt-in.
Conversation, not interview. Group related questions, ask follow-ups on thin answers, skip what doesn't fit the user's business.
Their words, not yours. Don't paraphrase free-text answers into corporate-speak when writing the file.
Partial is fine. A 10-answer CLAUDE.md is better than a 32-answer form the user abandoned at Q14.

Flow

1. Scan first

Before asking anything, quickly look at:

```
package.json
```
/
```
pyproject.toml
```
/
```
Gemfile
```
/
```
go.mod
```
→ tech stack, likely team size
```
README.md
```
→ pitch, target user, often the revenue model
```
git log
```
/
```
git remote
```
→ solo vs. team, commit cadence
Existing
```
CLAUDE.md
```
(if any) → start from what's there, don't overwrite blindly
```
.cursorrules
```
,
```
AGENTS.md
```
,
```
copilot-instructions.md
```
→ voice/style signals already written down

Make a short mental list of what you can fill in with high confidence, what you'd want to confirm, and what you genuinely don't know.

2. Open conversationally

Something like:

I'll help you put together a CLAUDE.md. I took a quick look at the repo — looks like a {stack} project, {team signal}. I'd like to ask around 8 core questions, then we can go as deep as you want on voice and working style. Some I'll just ask you to confirm from what I saw. Sound good?

Adjust tone to match the repo (playful brand → playful; legal tech → crisper).

3. Ask the 8 core questions

These are required. Ask them in whatever order feels natural, and group when it flows:

#	Topic	What you're trying to learn
1	Pitch	One-sentence "what do you do?"
2	Customer	Specific person being helped — give them a name/role
3	Non-negotiables	Rules Claude should never break (ethics, quality, boundaries)
4	Brand adjectives	3 words that describe the brand as a person
5	BLUF vs build-up	Answer-first, or walk-me-through-the-reasoning?
6	Ambiguity	Ask / guess / assume-and-flag?
7	Brain-dump handling	Clean grammar, preserve voice, or keep raw?
8	Next steps	Auto-suggest next actions, or only when asked?

For selects, use

AskUserQuestion

. For open-ended ones, just ask. If an answer is thin or generic, ask one follow-up — don't interrogate.

4. Offer depth

After the core 8:

That's the foundation. I can keep it there, or we can go deeper on any of these:

Business: goals, revenue model, competitors, secret sauce, budget, team, stack, hard lessons

Voice: POV, data vs. story, emojis, reading level, hook style, banned words, headline style, email style, visuals

Working style: approval cadence, yes-man vs. devil's advocate, format preference, plan detail, web search, financial estimates, meeting summaries

Pick a category, name specific topics, or say "that's enough."

Let them pick topics à la carte. If they say "all of voice," walk through voice questions conversationally — grouping related ones (e.g. reading level + headline style + email style often come as a set).

See

questions.md

for the full bank with hints, placeholders, and select options.

5. Confirm inferences

For anything you inferred from the repo, show the user what you're about to write and ask them to confirm or edit. Example:

I put this for your tech stack based on the repo — sound right, or want to tweak?

TypeScript, Next.js 15, Postgres, Stripe, Vercel

Don't silently bake inferences into the file.

6. Write the file

Use the template in

output-template.md

. Rules:

Skip sections the user didn't answer — don't write "N/A" or "Skipped."
Verbatim for free text — don't rewrite their words into cleaner prose.
Use the select-value → sentence mappings in
```
output-template.md
```
so the file reads naturally.
Check for existing
CLAUDE.md
— if one exists, ask whether to merge, overwrite, or save as
```
CLAUDE.generated.md
```
. If merging, preserve any sections the user already had that aren't covered by new answers.
Always include the Self-Updating Instructions preamble (see template).

7. Close

Tell them where it was written, and suggest one concrete thing: "Try giving Claude a real task in this repo and see if the voice feels right — you can edit the file any time, or come back to me to add the sections we skipped."

When NOT to use this skill

User explicitly asks for the "full questionnaire" or "all 32 questions" → use
```
claude-md-generator
```
instead.
User just wants a CLAUDE.md template with placeholders to fill in manually → write one directly, don't start a conversation.
A
```
CLAUDE.md
```
already exists and is well-developed → offer to augment specific sections rather than running the whole flow.

Anti-patterns

❌ Asking all 8 core questions in one giant message — kills the conversational feel.
❌ Re-asking something visible in the repo ("what's your tech stack?" when
```
package.json
```
is right there).
❌ Padding skipped sections with "The user did not specify..." — just omit them.
❌ Treating the optional depth as a second mandatory round. It's optional.
❌ Writing the file before confirming the user is done adding topics.