Kornevdima Claude Mem Project Profile

project-profile: Build the Calibration Artifact

This skill creates AGENTS.md (and the .agents/rules/ scaffolding) for a project. The output is the calibration layer that helps coding agents — Claude Code, Codex, Cursor, Copilot, Aider, etc. — produce code that fits the host project's conventions.

The design is informed by the [[Project Profile Skill Suite]] and the empirical findings in [[evaluating-agents-md-eth]]. Key load-bearing constraints:

• AGENTS.md auto-generated from configs is net-positive only when content is concrete. Repository overviews are net-negative. Cut them.
• Tribal knowledge is the only consistent positive. Interview the human; don't guess.
• Specific actionable directives outperform descriptive prose 1.6× in agent compliance.
• Cross-tool standard is AGENTS.md. Don't invent a claude-mem-specific format.

When to invoke

• A project has no AGENTS.md, CLAUDE.md, .cursorrules, or CONVENTIONS.md and the user wants agent context set up.
• A brownfield repo where new code should match existing conventions.
• The user says "/project-profile", "set up AGENTS.md", "init project context", "scan project conventions".

Do NOT invoke for:

• Greenfield empty repos (no conventions exist yet — wait until there's something to capture).
• Pure docs-only repos (no build/test commands to extract).

Modes (this version implements first-run only)

Steps to follow when invoked

Step 0 — Resolve target path

If the user gave a path, use it. Otherwise use the current working directory.

TARGET="${1:-$PWD}"
TARGET=$(cd "$TARGET" && pwd)  # absolutize

If $TARGET isn't a directory, abort with a clear error.

Step 1 — Detect existing context files

Check for any of:

• $TARGET/AGENTS.md
• $TARGET/CLAUDE.md
• $TARGET/.cursorrules or $TARGET/.cursor/rules/
• $TARGET/CONVENTIONS.md (Aider's format)

If AGENTS.md already exists, stop and ask the user:

"AGENTS.md already exists at $TARGET. First-run mode would overwrite it. Options: (1) abort and use --refresh mode (not yet implemented), (2) back up the existing file and proceed, (3) cancel."

Default to (3) cancel unless the user explicitly says proceed.

If CLAUDE.md / .cursorrules / CONVENTIONS.md exist but no AGENTS.md, note them in the output and proceed — we'll cross-reference and not duplicate their content.

Step 2 — Dispatch mechanical-scanner subagent

Dispatch ONE mechanical-scanner-subagent (defined in agents/mechanical-scanner-subagent.md):

Agent tool call:
  subagent_type: "mechanical-scanner-subagent"
  description: "Scan project configs for AGENTS.md mechanical sections"
  prompt: |
    target_path: <TARGET absolute path>
    existing_agents_md: <"none" or contents of existing AGENTS.md if any>

Wait for the subagent's response. It returns a structured markdown summary in its message — there's no file output for this scanner.

Parse the response. Extract:

• The "Detected stack" block (for the user's situational awareness)
• The "Proposed AGENTS.md sections" block (for composition into the final file)
• "Notes for the main agent" (surface to the user before the interview)

Step 3 — Show the user what was detected

Print a brief summary to the user, like:

Detected: TypeScript / Next.js / pnpm / vitest / eslint
Test command (from CI): pnpm test --reporter verbose
Lint command: pnpm lint
Build: pnpm build
Notes from scanner:
  - Two test commands found (unit + e2e). Recommend noting both.
  - .nvmrc pins Node 22.

Then prompt:

"Mechanical sections look right? [y / edit]"

If the user wants to edit, accept their inline edits before proceeding. Don't write to disk yet.

Step 4 — Tribal interview

Conduct a SHORT structured interview. Ask one question at a time, accept free-form answers, allow "skip" or "n/a" for each. Limit to these four questions — do not extend:

Q1: Anything I should never touch? (Examples: legacy modules, generated code, vendored libs. Free-form, or "none".)

Q2: Use X not Y rules? (Examples: "use httpx not requests", "Result types not exceptions", "no print() in production code". Free-form list, or "none".)

Q3: Code generations to mark? (For brownfield repos with multiple eras of code. Format: current: <glob>; legacy: <glob>; transitional: <glob>. Or "none".)

Q4: Style for new code (vs legacy)? (One or two sentences on what new code should look like. Or "none".)

If the user gives "none" / "skip" to all four, that's fine — proceed with mechanical-only AGENTS.md. The point of asking is to give the human a chance to add the only kind of content empirically known to help.

Step 5 — Compose AGENTS.md

Build the file in this exact structure. Do not add a "Project overview" section (AGENTbench: net-negative). Do not paraphrase README.

# AGENTS.md

> Cross-tool agent context for this project. Read by Codex, Cursor, Copilot, Aider, Claude Code, and other AGENTS.md-compatible agents.

## Build & Test

[mechanical-scanner output, exact commands]

## Linting & Formatting

[mechanical-scanner output, exact commands]

## Language Version

[from mechanical-scanner if detected; omit section otherwise]

## Code Generations

[from Q3 if user provided; omit section otherwise]

Example:
- Current style: src/api/v3/**, src/services/v3/**
- Legacy (do not copy patterns from): src/legacy/**, src/api/v1/**
- Transitional: src/api/v2/** (reference only, not as analogue)

## Conventions

[combined from Q1, Q2, Q4 if user provided; omit section if all "none"]

Format each as a concrete directive. Examples:
- Never modify src/legacy/* — being deprecated.
- Use httpx, not requests.
- Use Result types in src/api/v3/**, not exceptions.
- New components go in src/components/v3/. Match the patterns there, not in src/legacy/components/.

## Rules

Detailed rules live in `.agents/rules/` (one rule per file, see `_index.md`). Use the `/capture-rule` skill to add a new rule from a productive chat.

## Cross-references

[only include if other context files were detected in Step 1]

- `CLAUDE.md` — Claude Code tool-specific notes
- `.cursor/rules/` — Cursor tool-specific rules
- `CONVENTIONS.md` — superseded; consider migrating into this file

Target length: under 2K tokens total. If the file exceeds 3K tokens, push back: AGENTbench shows costs ramping without benefits beyond ~2K.

Step 6 — Create .agents/rules/ scaffolding

mkdir -p "$TARGET/.agents/rules"

Write $TARGET/.agents/rules/_index.md as an empty index:

---
type: index
title: "Project Rules Index"
updated: <YYYY-MM-DD today>
---

# Project Rules Index

Rules captured via `/capture-rule`. One rule per file. The evaluator reads this index to detect conflicts cheaply.

| Rule | Scope | Created | One-line summary |
|---|---|---|---|
| (none yet) | | | |

Step 7 — Show the user the proposed AGENTS.md

Print the full proposed AGENTS.md to the user. Prompt:

"Looks good? [Accept / Edit / Reject]"

• Accept: write the file to $TARGET/AGENTS.md, confirm path.
• Edit: accept inline edits, then write.
• Reject: don't write anything; report "AGENTS.md not created."

Step 8 — Append to wiki/log.md (if claude-mem wiki present)

If $TARGET/wiki/log.md exists, prepend a log entry:

## [YYYY-MM-DD] project-profile | First-run setup
- Type: skill execution
- Created: AGENTS.md, .agents/rules/_index.md
- Detected stack: <one-line summary from scanner>
- Tribal answers given: <count of non-"none" responses>
- Existing context files cross-referenced: <CLAUDE.md, .cursorrules, etc., or "none">

If no claude-mem wiki present, skip this step. The skill is useful in projects without a wiki too.

Step 9 — Report to the user

Brief confirmation:

project-profile complete:
  $TARGET/AGENTS.md (NN tokens)
  $TARGET/.agents/rules/_index.md (empty)

Next steps:
  - Use the project normally; agents will read AGENTS.md upfront.
  - When you correct an agent's behavior in chat into the right pattern,
    run /capture-rule to crystallize the lesson.

Hard rules

1. Never write AGENTS.md without explicit user accept. Step 7 is mandatory.
2. Never paraphrase README into AGENTS.md. AGENTbench: net-negative.
3. Never invent commands. If the scanner reports "(not detected)", leave the slot honest.
4. Cap at 4 tribal questions. Adding more burns user patience without proportional gain.
5. Default to "skip" being acceptable. Mechanical-only AGENTS.md is still useful.

Known limitations (intentional, deferred)

• No refresh mode yet. When configs drift, user must re-run first-run mode (and merge by hand). Refresh comes in step 4 of the implementation sequence.
• No status mode yet. No --status flag for rule-count/health output.
• No per-subdirectory AGENTS.md. Monorepos with multiple subprojects get only a root-level file.
• No CLAUDE.md @path imports. If user wants Claude Code to specifically link to AGENTS.md, they add the import manually.

Connections

• [[Project Profile Skill Suite]] — design doc this implements
• [[Project Profile]] — broader concept
• [[AGENTS.md]] — output format spec
• [[evaluating-agents-md-eth]] — empirical caveats baked into this skill
• agents/mechanical-scanner-subagent.md — the subagent this skill dispatches

Source: kornevdima/claude-mem — distributed by TomeVault.