setup-chalk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Initialize a

.chalk/

folder for any repository. Produces a machine-readable

chalk.json

(the single source of truth for skills) and human-readable PROFILE docs covering product, engineering, design, and AI orientation.

为任意代码仓库初始化一个

.chalk/

文件夹。生成机器可读的

chalk.json

（Skill的唯一事实来源）以及面向产品、工程、设计和AI方向的人类可读PROFILE文档。

What This Skill Produces

该Skill生成的内容

.chalk/
  chalk.json                          # Machine-readable project identity (skills read this first)
  docs/
    product/
      PROFILE.md                      # What the product is, who it's for, core JTBD
    engineering/
      PROFILE.md                      # Architecture + tech stack + data flow (single source)
      coding-style.md                 # Naming, file structure, component patterns, conventions
    ai/
      PROFILE.md                      # Agent-facing orientation, gotchas, quick reference
    design/
      PROFILE.md                      # Design system: colors, typography, spacing, tokens
      assets/                         # Copied logos, icons, favicons, brand marks

.chalk/
  chalk.json                          # 机器可读的项目标识（Skill会优先读取此文件）
  docs/
    product/
      PROFILE.md                      # 产品定位、目标用户、核心待办任务（JTBD）
    engineering/
      PROFILE.md                      # 架构+技术栈+数据流（唯一事实来源）
      coding-style.md                 # 命名规范、文件结构、组件模式、约定俗成规则
    ai/
      PROFILE.md                      # 面向Agent的指南、注意事项、快速参考
    design/
      PROFILE.md                      # 设计系统：颜色、排版、间距、设计令牌
      assets/                         # 复制的Logo、图标、网站图标、品牌标识

Workflow

工作流程

Phase 1 — Discover

阶段1 — 发现

Locate the repo root — Use
```
$ARGUMENTS
```
if provided, otherwise use the current working directory.
Check for existing
.chalk/
— If it already exists, warn the user and ask whether to merge or overwrite. If merging, skip files that already exist and only fill gaps.

Scan the repo — Read these files to understand the project:

```
README.md
```
(or
```
readme.md
```
)

package.json

Cargo.toml

pyproject.toml

go.mod

Gemfile

pom.xml

(dependency manifest)

```
tsconfig.json
```
/
```
tsconfig.*.json
```

Build configs:

vite.config.*

next.config.*

webpack.config.*

electron.vite.config.*

turbo.json

angular.json

Styling:

tailwind.config.*

postcss.config.*

, any

*.css

files in

src/

```
.eslintrc*
```
,
```
.prettierrc*
```
,
```
biome.json
```
(linter/formatter config)
```
Dockerfile
```
,
```
docker-compose.yml
```
```
.github/workflows/*.yml
```
(CI/CD)
Existing
```
AGENTS.md
```
,
```
.cursorrules
```
, or
```
CLAUDE.md
```

定位仓库根目录 — 如果提供了
```
$ARGUMENTS
```
则使用该参数，否则使用当前工作目录。
检查现有
.chalk/
文件夹 — 如果已存在，向用户发出警告并询问是合并还是覆盖。如果选择合并，跳过已存在的文件，仅补充缺失内容。

扫描仓库 — 读取以下文件以了解项目：

```
README.md
```
（或
```
readme.md
```
）

package.json

Cargo.toml

pyproject.toml

go.mod

Gemfile

pom.xml

（依赖清单）

```
tsconfig.json
```
/
```
tsconfig.*.json
```

构建配置：

vite.config.*

next.config.*

webpack.config.*

electron.vite.config.*

turbo.json

angular.json

样式配置：

tailwind.config.*

postcss.config.*

src/

目录下的所有

*.css

文件

```
.eslintrc*
```
,
```
.prettierrc*
```
,
```
biome.json
```
（代码检查/格式化工具配置）
```
Dockerfile
```
,
```
docker-compose.yml
```
```
.github/workflows/*.yml
```
（CI/CD配置）
已存在的
```
AGENTS.md
```
,
```
.cursorrules
```
, 或
```
CLAUDE.md
```

Phase 2 — Analyze

阶段2 — 分析

Detect framework and project type — Identify from dependencies:

Dependency	Framework	Type	Default Port
`next`	Next.js	web	3000
`vite` + `@vitejs/plugin-react`	Vite + React	web	5173
`react-scripts`	CRA	web	3000
`nuxt`	Nuxt	web	3000
`@angular/core`	Angular	web	4200
`svelte` / `@sveltejs/kit`	SvelteKit	web	5173
`electron` / `electron-vite`	Electron	desktop	varies
`vue`	Vue	web	5173
`express` / `fastify` / `koa`	Node API	api	3000
`django` / `flask` / `fastapi`	Python web	web/api	8000

Detect routes — Scan based on detected framework:
- File-based routing (Next.js, Nuxt, SvelteKit): glob
```
app/**/page.{tsx,jsx,ts,js}
```
  or
```
pages/**/*.{tsx,jsx,vue}
```
- React Router: grep for
```
<Route
```
  ,
```
createBrowserRouter
```
  , or
```
path:
```
  in
```
src/
```
- Vue Router: grep for
```
path:
```
  in router config files
- Angular: grep for
```
{ path:
```
  in routing modules
- Query-param routing (Electron): grep for
```
searchParams.get
```
  or
```
?page=
```
- Express/API: grep for
```
app.get(
```
  ,
```
router.get(
```
  ,
```
@app.route
```
- Fallback: scan for page components in
```
src/pages/
```
  ,
```
src/views/
```
  ,
```
src/app/
```
  ,
```
src/routes/
```
Map source layout — Identify key directories:
- Source root (
```
src/
```
  ,
```
app/
```
  ,
```
lib/
```
  )
- Entry points (main files, renderers, workers)
- Components, pages/views, styles, and tests directories
Map the architecture — Identify:
- Process model (monolith, Electron multi-process, SPA, SSR, etc.)
- Directory structure patterns (feature folders, atomic design, domain-driven)
- Entry points and boot sequence
- Data flow (state management, IPC, API calls, database)
- Key abstractions (hooks, services, stores, controllers)
Extract coding style — Analyze 3-5 representative files from different layers:
- Naming conventions, export patterns, component patterns
- State management, error handling, comment style
- Import ordering, TypeScript strictness
Catalog the tech stack — For every dependency: name, version, layer, purpose, category.
Extract design tokens — CSS custom properties, Tailwind theme extensions, recurring color/typography/spacing values.
Find brand assets — Glob for icons, logos, favicons under resources/, public/, assets/.

检测框架和项目类型 — 通过依赖项识别：

依赖项	框架	类型	默认端口
`next`	Next.js	网页应用	3000
`vite` + `@vitejs/plugin-react`	Vite + React	网页应用	5173
`react-scripts`	CRA	网页应用	3000
`nuxt`	Nuxt	网页应用	3000
`@angular/core`	Angular	网页应用	4200
`svelte` / `@sveltejs/kit`	SvelteKit	网页应用	5173
`electron` / `electron-vite`	Electron	桌面应用	不固定
`vue`	Vue	网页应用	5173
`express` / `fastify` / `koa`	Node API	接口服务	3000
`django` / `flask` / `fastapi`	Python web	网页/接口应用	8000

检测路由 — 根据检测到的框架进行扫描：
- 文件式路由（Next.js, Nuxt, SvelteKit）：匹配
```
app/**/page.{tsx,jsx,ts,js}
```
  或
```
pages/**/*.{tsx,jsx,vue}
```
- React Router：在
```
src/
```
  目录中搜索
```
<Route
```
  ,
```
createBrowserRouter
```
  或
```
path:
```
- Vue Router：在路由配置文件中搜索
```
path:
```
- Angular：在路由模块中搜索
```
{ path:
```
- 查询参数路由（Electron）：搜索
```
searchParams.get
```
  或
```
?page=
```
- Express/API：搜索
```
app.get(
```
  ,
```
router.get(
```
  ,
```
@app.route
```
- 备选方案：扫描
```
src/pages/
```
  ,
```
src/views/
```
  ,
```
src/app/
```
  ,
```
src/routes/
```
  目录中的页面组件
映射源码布局 — 识别关键目录：
- 源码根目录（
```
src/
```
  ,
```
app/
```
  ,
```
lib/
```
  ）
- 入口文件（主文件、渲染器、工作线程）
- 组件、页面/视图、样式、测试目录
映射架构 — 识别：
- 进程模型（单体应用、Electron多进程、SPA、SSR等）
- 目录结构模式（功能文件夹、原子设计、领域驱动设计）
- 入口点和启动流程
- 数据流（状态管理、IPC、API调用、数据库）
- 核心抽象（Hooks、服务、Store、控制器）
提取编码风格 — 分析来自不同层级的3-5个代表性文件：
- 命名规范、导出模式、组件模式
- 状态管理、错误处理、注释风格
- 导入顺序、TypeScript严格模式
整理技术栈 — 记录每个依赖项：名称、版本、层级、用途、类别。
提取设计令牌 — CSS自定义属性、Tailwind主题扩展、重复使用的颜色/排版/间距值。
查找品牌资源 — 在resources/, public/, assets/目录中搜索图标、Logo、网站图标。

Phase 3 — Generate

阶段3 — 生成

Create
.chalk/chalk.json
— The machine-readable project identity. This is the most important file — skills read it first.

json

{
  "version": "1.0",
  "project": {
    "name": "<from package.json or directory name>",
    "description": "<from package.json description or README>",
    "language": "<typescript|javascript|python|go|rust|java>",
    "framework": "<next|vite|electron|django|express|etc>",
    "type": "<web|desktop|api|library|cli|monorepo>"
  },
  "dev": {
    "command": "<npm run dev|yarn dev|make dev|etc>",
    "port": 3000,
    "url": "http://localhost:3000"
  },
  "test": {
    "command": "<npm test|pytest|go test ./...>",
    "framework": "<jest|vitest|pytest|node:test>"
  },
  "build": {
    "command": "<npm run build>",
    "output": "dist/"
  },
  "routes": [
    { "path": "/", "name": "Home", "src": "src/pages/index.tsx" }
  ],
  "sourceLayout": {
    "root": "src/",
    "entrypoints": { "main": "src/main.tsx" },
    "components": "src/components/",
    "pages": "src/pages/",
    "styles": "src/styles/",
    "tests": "tests/"
  },
  "createdAt": "<ISO timestamp>",
  "updatedAt": "<ISO timestamp>"
}

Schema reference:

docs/chalk.schema.json

in the chalk-skills repo defines all valid fields.

Important: Fill every field you can detect. Omit fields you can't determine — don't guess. Skills handle missing fields gracefully.

Create
.chalk/docs/product/PROFILE.md

Summarize:

Product name, one-liner, primary users, core value prop
Problem: what pain this solves
Target Users: table (Persona, Job, How This Helps)
Core Jobs To Be Done: numbered list, each starts with a verb
Current Status: feature table (Feature, Status, Notes)

Create
.chalk/docs/engineering/PROFILE.md
— Single comprehensive engineering doc covering architecture + tech stack + data flow:

Include:

Architecture diagram (ASCII or Mermaid)
Execution contexts table (entry point, lifecycle, access)
Boot sequence (numbered steps)
Directory structure (annotated tree with purpose per directory)
Data flow (state management, API/IPC boundaries, storage)
Tech stack table (Package, Version, Category, Purpose) grouped by runtime vs dev/build
Key patterns (design patterns, error handling, testing approach)

Create
.chalk/docs/engineering/coding-style.md

Include:

File & folder naming conventions with examples
Component/module structure with real code example from the codebase
Naming conventions (variables, functions, types, files)
Import ordering with real example
Export patterns (default vs named)
TypeScript patterns (strict mode, type vs interface)
Styling patterns (Tailwind, CSS approach)
Error handling patterns

Create
.chalk/docs/ai/PROFILE.md
— Agent-facing quick reference:

Include:

Project Identity: 1 paragraph
Where Things Live: table (What, Where, Notes)
Conventions to Follow: top 5-10 rules
Gotchas: numbered list of agent-surprising things
How to Add a Feature: step-by-step guide

Create
.chalk/docs/design/PROFILE.md

Include:

Brand identity (name, visual tone)
Color palette: Primary, Neutral, Semantic tables (Name, Hex, Tailwind, Usage)
Typography (font families, size/weight scales)
Spacing & layout (common values, breakpoints)
Borders & shadows
Icons (library, usage patterns)
Component patterns (buttons, cards, common UI)

Copy brand assets to
```
.chalk/docs/design/assets/
```
(files < 500KB, prefer SVG).

创建
.chalk/chalk.json
— 机器可读的项目标识。这是最重要的文件——Skill会优先读取它。

json

{
  "version": "1.0",
  "project": {
    "name": "<来自package.json或目录名称>",
    "description": "<来自package.json描述或README>",
    "language": "<typescript|javascript|python|go|rust|java>",
    "framework": "<next|vite|electron|django|express|etc>",
    "type": "<web|desktop|api|library|cli|monorepo>"
  },
  "dev": {
    "command": "<npm run dev|yarn dev|make dev|etc>",
    "port": 3000,
    "url": "http://localhost:3000"
  },
  "test": {
    "command": "<npm test|pytest|go test ./...>",
    "framework": "<jest|vitest|pytest|node:test>"
  },
  "build": {
    "command": "<npm run build>",
    "output": "dist/"
  },
  "routes": [
    { "path": "/", "name": "Home", "src": "src/pages/index.tsx" }
  ],
  "sourceLayout": {
    "root": "src/",
    "entrypoints": { "main": "src/main.tsx" },
    "components": "src/components/",
    "pages": "src/pages/",
    "styles": "src/styles/",
    "tests": "tests/"
  },
  "createdAt": "<ISO时间戳>",
  "updatedAt": "<ISO时间戳>"
}

Schema参考：chalk-skills仓库中的

docs/chalk.schema.json

定义了所有有效字段。

重要提示：填充所有可检测到的字段。无法确定的字段请留空——不要猜测。Skill会优雅处理缺失字段。

创建
.chalk/docs/product/PROFILE.md

总结内容：

产品名称、一句话描述、核心用户、核心价值主张
解决的问题：该产品解决了什么痛点
目标用户：表格（用户画像、工作内容、产品如何提供帮助）
核心待办任务（JTBD）：编号列表，每项以动词开头
当前状态：功能表格（功能、状态、备注）

创建
.chalk/docs/engineering/PROFILE.md
— 包含架构+技术栈+数据流的综合性工程文档：

内容包括：

架构图（ASCII或Mermaid格式）
执行上下文表格（入口点、生命周期、权限）
启动流程（编号步骤）
目录结构（带注释的树状图，说明每个目录的用途）
数据流（状态管理、API/IPC边界、存储）
技术栈表格（包、版本、类别、用途），按运行时与开发/构建工具分组
核心模式（设计模式、错误处理、测试方法）

创建
.chalk/docs/engineering/coding-style.md

内容包括：

文件与文件夹命名规范及示例
组件/模块结构，附代码库中的真实代码示例
命名规范（变量、函数、类型、文件）
导入顺序，附真实示例
导出模式（默认导出 vs 命名导出）
TypeScript模式（严格模式、type vs interface）
样式模式（Tailwind、CSS方案）
错误处理模式

创建
.chalk/docs/ai/PROFILE.md
— 面向Agent的快速参考：

内容包括：

项目标识：1段文字
资源位置：表格（资源、路径、备注）
需遵循的约定：Top 5-10规则
注意事项：编号列表，列出Agent容易误解的内容
新增功能指南：分步说明

创建
.chalk/docs/design/PROFILE.md

内容包括：

品牌标识（名称、视觉风格）
调色板：主色、中性色、语义色表格（名称、十六进制值、Tailwind类、用途）
排版（字体族、字号/字重层级）
间距与布局（常用值、断点）
边框与阴影
图标（图标库、使用模式）
组件模式（按钮、卡片、通用UI）

复制品牌资源到
```
.chalk/docs/design/assets/
```
（文件大小<500KB，优先选择SVG格式）。

Phase 4 — Verify

阶段4 — 验证

Validate
chalk.json
— Check that required fields are present and values make sense. Print warnings for missing optional fields.
List created files — Print a tree of everything created under
```
.chalk/
```
.
Summarize — Tell the user what was captured, what has gaps, and suggest running
```
/setup-docs
```
to enrich stubs with deeper analysis.

验证
chalk.json
— 检查必填字段是否存在且值合理。对缺失的可选字段打印警告。
列出已创建文件 — 打印
```
.chalk/
```
目录下所有已创建文件的树状结构。
总结 — 告知用户已捕获的内容、存在的缺口，并建议运行
```
/setup-docs
```
以通过深度分析完善文档草稿。

Doc Format Rules

文档格式规则

No YAML frontmatter in docs (plain markdown)
First
```
# Heading
```
is the document title
```
Last updated: YYYY-MM-DD (<brief note>)
```
immediately after the title
Use
```
## Heading
```
for sections
GFM features: tables, code blocks, checkboxes, Mermaid diagrams
Use real code examples from the repo, not generic placeholders
Be specific and concrete — hex codes not "brand green", actual file paths not "components folder"

文档中不要使用YAML前置元数据（纯Markdown格式）
第一个
```
# 标题
```
为文档标题

标题后紧跟

最后更新时间：YYYY-MM-DD（<简短说明>）

使用
```
## 标题
```
作为章节标题
使用GFM特性：表格、代码块、复选框、Mermaid图
使用代码库中的真实代码示例，而非通用占位符
内容要具体、明确——使用十六进制颜色码而非“品牌绿色”，使用实际文件路径而非“组件文件夹”

Migration from v1

从v1版本迁移

If the project has the old docs structure (numbered files like

0_PRODUCT_PROFILE.md

1_architecture.md

3_techstack.md

Merge

0_ENGINEERING_PROFILE.md

1_architecture.md

3_techstack.md

→

engineering/PROFILE.md

Rename
```
0_PRODUCT_PROFILE.md
```
→
```
product/PROFILE.md
```
Rename
```
0_AI_PROFILE.md
```
→
```
ai/PROFILE.md
```
Rename
```
0_design-system.md
```
→
```
design/PROFILE.md
```

Rename

2_coding-style.md

→

engineering/coding-style.md

Keep any extra docs as additional files in their vertical
Expand
```
chalk.json
```
with new fields (project, dev, test, build, routes, sourceLayout)
Delete old numbered files after confirming the merge

Ask the user before performing migration.

如果项目使用旧版文档结构（编号文件如

0_PRODUCT_PROFILE.md

1_architecture.md

3_techstack.md

）：

合并

0_ENGINEERING_PROFILE.md

1_architecture.md

3_techstack.md

→

engineering/PROFILE.md

重命名
```
0_PRODUCT_PROFILE.md
```
→
```
product/PROFILE.md
```
重命名
```
0_AI_PROFILE.md
```
→
```
ai/PROFILE.md
```
重命名
```
0_design-system.md
```
→
```
design/PROFILE.md
```

重命名

2_coding-style.md

→

engineering/coding-style.md

将所有额外文档保留在对应分类目录下
扩展
```
chalk.json
```
以包含新字段（project, dev, test, build, routes, sourceLayout）
确认合并完成后删除旧的编号文件

执行迁移前请先询问用户。

Style Transfer Focus

风格迁移重点

The goal is fidelity. An AI agent reading these docs should be able to:

Write new code that looks like it belongs in the codebase (coding style)
Place files in the right directories following the right patterns (architecture)
Use the correct libraries and APIs (tech stack)
Match the visual design exactly — right colors, right spacing, right typography (design system)
Use the brand assets correctly (design assets)

Prioritize concrete examples over abstract rules.

目标是保真度。阅读这些文档的AI Agent应能够：

编写与代码库风格一致的新代码（编码风格）
按照正确的模式将文件放置在正确的目录中（架构）
使用正确的库和API（技术栈）
完全匹配视觉设计——正确的颜色、间距、排版（设计系统）
正确使用品牌资源（设计资产）

优先具体示例而非抽象规则。