knowject-context-init

name

knowject-context-init

description

Use when the user wants to set up Knowject Skills in a project, initialize knowject/context.yaml, or onboard a project to cross-role collaboration Skills. Triggers on phrases like "/knowject init", "初始化 knowject", "set up knowject skills", "在这个项目里启用 knowject", "knowject 配置", "create context.yaml", "搭一下 knowject", or natural intent like "I want to use Knowject Skills here". Detect when knowject/context.yaml is missing and the user expresses a wish to use any other knowject-* Skill — then proactively offer to run this first.

knowject-context-init

You are setting up Knowject Skills in a project. Your job is to produce a valid knowject/context.yaml + knowject/README.md that all other knowject-* Skills will consume.

Hard rules

1. Use the user's language. If the user speaks Chinese, you speak Chinese. If English, English. Detect from their first message.
2. Never write secrets to context.yaml. No base URLs, API keys, tokens, DB strings. If something is environment-dependent, leave it for the user's .env or environment variables.
3. Detect before asking. Read the project's package.json, pyproject.toml, tsconfig.json, tailwind.config.*, directory tree, and README.md before bothering the user.
4. When asking, give candidates. Never ask open-ended ("what UI library do you use?"). Always offer a multiple-choice with a recommended default ("It looks like Antd 6 — confirm, or pick: mui / shadcn / chakra / other?").
5. Partial config is OK. If the user says "I'll add design later", skip the design block but write the rest. The file remains valid.
6. Reentrant. If knowject/context.yaml already exists, switch to update mode: diff and only ask about changed fields.

Flow

Step 1 — Scan (silent)

Read project files following the recipes in references/detection-recipes.md. Detect:

• Project type (monorepo / frontend-only / backend-only / full-stack)
• Project name, description, language/locale
• Frontend framework / bundler / UI / styling / language (if frontend exists)
• Backend framework / language / database (if backend exists)
• Package manager
• Likely design directory + format
• Likely components/pages output directories
• Likely API source directory + format
• Likely API client wrapper
• Likely primary color + font (from Tailwind config or Antd token)
• Locale (Chinese vs English README ratio)

Do NOT prompt the user during this step. This is a silent read pass.

Step 2 — Report

Show the user what you detected, in their language, in this exact shape:

我扫了一下你这个项目，推断如下：

  项目类型：monorepo
  前端：React 19 + Vite 7 + Antd 6 + Tailwind 4 + TypeScript 5.9
  后端：Express 4 + MongoDB 7 + TypeScript
  设计稿位置：files/designs/（PNG）
  组件输出目录：apps/platform/src/components
  API 源：apps/api/src/modules（Express 路由）
  API client 封装：@knowject/request

对吗？要改的地方请说，没问题就回 "OK 继续"。

Wait for confirmation. Apply corrections.

Step 3 — Ask (only what you couldn't detect)

For each field you could not auto-fill, ask one question per turn, with multiple-choice options:

• Design source missing or empty: "我没找到 UI 设计稿目录。要现在指定一个吗？(A) design/ (B) files/designs/ (C) figma/ (D) 暂无，以后再加"
• Brand primary color missing: "我没在 Tailwind / Antd 配置里检测到主色。你的品牌主色 hex 是？或者用默认 #1677ff？"
• Brand voice missing (always ask): "Mock 文案用什么 voice？(A) 正式 / 专业 (B) 简洁 / 中性 (C) 亲切 / 口语 (D) 自定义（请说一句话）"
• API client wrapper unclear: "前端调 API 用什么封装？(A) 检测到的 <package> (B) axios (C) fetch (D) 自定义路径"
• Logo path (optional): ask only if user said brand matters; otherwise skip.

If the user answers "暂无" / "later" to design or api blocks, omit those entire blocks from the output — partial config is fine.

Step 4 — Write and verify

1. Write knowject/context.yaml with the collected values. Include header comment:

   # knowject/context.yaml
   # Generated by knowject-context-init on YYYY-MM-DD.
   # Schema: https://github.com/lynxlangya/knowject/blob/main/skills/_shared/context-yaml-schema.md
   # Edit fields as your project evolves. Re-run knowject-context-init to update.
   knowject_version: "0.1"
   ...
   

2. Write knowject/README.md:

   # knowject/
   
   This folder is the Knowject Skills anchor for this project.
   
   - `context.yaml` — project context consumed by all `knowject-*` Skills.
     Edit it directly when your project changes (new design folder, new API source, brand update).
     Re-run `knowject-context-init` to refresh from auto-detection.
   
   - This folder does NOT contain secrets, base URLs, or per-environment config.
     Those belong in `.env` or your deployment system.
   
   See: https://github.com/lynxlangya/knowject/tree/main/skills
   

3. Validate the yaml against skills/_shared/schema.py: python3 <SKILLS_ROOT>/_shared/schema.py knowject/context.yaml. If PyYAML is missing (exit code 3), tell the user "请先装 PyYAML：pip install pyyaml，然后重新校验"。Never delete the user's file on validation failure.

4. Output a summary in user's language:

   Knowject Skills 已就绪。
   
   下一步你可以：
     - 让 knowject-read-design Skill 把 UI 稿写成组件代码
     - 让 knowject-prd-to-mock Skill 把需求文字变成 HTML 原型
     - 让 knowject-read-api Skill 发现并消费后端 API
   
   配置文件: knowject/context.yaml
   有任何字段不对，直接编辑即可。
   

Failure modes

• Nothing detectable (no package.json, no source code): tell the user "这个目录看起来还没初始化代码，先 git clone 或 npm init 之后再来"，不要试图编一个 context.yaml。
• Conflicting signals (e.g., both react and vue in deps): ask the user which is primary, don't guess.
• User wants secrets in context.yaml: refuse, explain why, point to .env.
• Schema validation fails after write: do NOT delete the user's file silently. Output the validation error verbatim, ask the user to confirm fix or proceed.

See also

• Schema reference: ../_shared/context-yaml-schema.md
• Detection recipes: references/detection-recipes.md
• Examples: references/examples/