# Discover

> Discover an existing project's conventions and generate or refresh minimal AI spec files (.superskills/conventions.md, AGENTS.md, CLAUDE.md). Use when a project lacks AGENTS.md/CLAUDE.md, when the user asks to generate conventions ("生成规范", "init ai docs", "discover conventions"), or when conventions are reported stale.

- Skill: `mrlyk/discover` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrlyk/discover`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/discover/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrlyk (https://skillmd.com/u/mrlyk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrlyk/discover

---


# Discover Conventions

Generate or refresh the project's AI-facing spec files. Keep everything short — these files load into every session, so every line costs tokens forever.

## Scan (read evidence, don't guess)

- Manifests and configs: package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml, lockfiles, linter/formatter/tsconfig, CI files
- Existing docs: README, CONTRIBUTING, docs/, existing AGENTS.md / CLAUDE.md / editor rules
- Code sample: 3-5 representative source files plus 1-2 test files; note naming, module structure, error handling, test style
- Git: `git log --oneline -20` for the commit message convention

## Write

1. `.superskills/conventions.md` — single source of truth, max 80 lines:
   - **Commands**: install / build / test / lint, the real ones from manifests
   - **Structure**: one line per top-level directory that matters
   - **Conventions**: only rules evidenced in code or docs — naming, imports, error handling, test layout, commit style
   - **Don'ts**: only if evidenced (e.g. a lint rule or doc forbids it)

   Every line must be project-specific and evidenced. Drop generic advice ("write clean code"). Prefer one line over three.

2. `AGENTS.md` (if missing) — max 20 lines: one-paragraph project description, key commands, then exactly these pointers:
   - `Read .superskills/conventions.md before writing code.`
   - `Check .superskills/learnings/INDEX.md for past learnings; read a linked entry when relevant.`
   - `If anything in a request is unclear, do not guess — proactively trigger the superskills clarify skill to ask before coding; when the request is already specific, just implement.`
   - `Before reporting any coding task as done you must have executed the changed code: run the documented examples plus boundary cases (empty, extreme, malformed, repeated/trailing input) via the test suite or a throwaway script you then delete, fix failures at root cause, and include the run output in your final reply. For larger changes apply the superskills test skill.`

   If AGENTS.md exists, only append the pointer lines when missing. Never rewrite existing user content.

3. `CLAUDE.md` (if missing) — exactly these imports:

   ```
   @AGENTS.md
   @.superskills/conventions.md
   ```

   If it exists, append missing imports only.

4. `.superskills/learnings/INDEX.md` — create with a `# Learnings` header if missing.

## Refresh mode

If `.superskills/conventions.md` already exists:
- Diff reality against it (recent commits, new configs, changed structure); update changed lines only, keep it within 80 lines.
- Fold learnings from `.superskills/learnings/` that have hardened into stable conventions directly into conventions.md, then delete those learning files and their INDEX lines.

Finish by suggesting a commit of `.superskills/`, `AGENTS.md`, and `CLAUDE.md`.