@teamix-evo/skills 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teamix Evo Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @teamix-evo/skills
+
+Skills (AI IDE 自动技能) for Teamix Evo. 同源支持 **Qoder** 和 **Claude Code**。
+
+## 包结构
+
+```
+packages/skills/
+├── manifest.json          # 顶层声明：枚举所有 skill
+├── _data.json             # 模板共享数据（可选）
+├── _template/             # 新建 skill 时的脚手架模板
+│   └── SKILL.md.hbs
+├── skills/                # 每个 skill 一个子目录
+│   └── teamix-evo-manage/
+│       └── SKILL.md       # 入口文件（同源 Qoder + Claude）
+└── scripts/
+    ├── validate-skills.ts
+    └── scaffold-skill.ts
+```
+
+## 协议要点
+
+- 每个 skill 必须有 `SKILL.md`，frontmatter 至少包含 `name` + `description`。
+- `description` 是 AI 触发依据，请明确写出"何时该激活"。
+- 默认 `updateStrategy: managed`，并使用 managed regions 让升级保留用户自定义部分。
+- 安装后 SKILL.md 同时落到所选 IDE 路径：
+  - Qoder：`.qoder/skills/<name>/SKILL.md` 或 `~/.qoder/skills/<name>/SKILL.md`
+  - Claude：`.claude/skills/<name>/SKILL.md` 或 `~/.claude/skills/<name>/SKILL.md`
+
+## 研发态命令
+
+```bash
+# 校验 manifest + 资源完整性
+pnpm --filter @teamix-evo/skills validate
+
+# 新建 skill（脚手架）
+pnpm --filter @teamix-evo/skills scaffold:skill
+```
+
+## 消费态命令（CLI）
+
+由 `teamix-evo skills` 子命令族管理：
+
+```bash
+teamix-evo skills add         # 全量装入 manifest 内所有 skill
+teamix-evo skills add <name>  # 增量：仅装入指定 skill（可多个）
+teamix-evo skills list        # 列出全部 skill（默认：已装✓ / 未装○）
+teamix-evo skills ls          # 别名
+teamix-evo skills list --installed  # 仅看已装
+teamix-evo skills update      # 升级到最新版（managed 策略保留你的自定义）
+teamix-evo skills uninstall   # 卸载
+```

package/_data.json

@@ -0,0 +1,3 @@
+{
+  "comment": "Shared template data for all skills. Currently empty; reserved for future use."
+}

package/_template/SKILL.md.hbs

@@ -0,0 +1,11 @@
+---
+name: {{name}}
+description: {{description}}
+---
+
+# {{title}}
+
+<!-- teamix-evo:managed:start id="core" -->
+<!-- teamix-evo:managed:end id="core" -->
+
+> 这部分内容由你（用户）自行编辑，CLI 升级时不会覆盖。

package/manifest.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://teamix-evo.dev/schema/skills-package/v1.json",
+  "schemaVersion": 1,
+  "package": "skills",
+  "version": "0.1.0",
+  "engines": {
+    "teamix-evo": ">=0.1.0"
+  },
+  "skills": [
+    {
+      "id": "teamix-evo-manage",
+      "name": "teamix-evo-manage",
+      "description": "Manage the teamix-evo toolkit (init / update / uninstall) inside the current project. Auto-trigger when the user mentions teamix-evo, design system installation, or related lifecycle tasks.",
+      "version": "0.1.0",
+      "source": "skills/teamix-evo-manage",
+      "ides": ["qoder", "claude"],
+      "updateStrategy": "managed",
+      "managedRegions": ["core"],
+      "template": false
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@teamix-evo/skills",
+  "version": "0.2.0",
+  "description": "Skills (AI IDE capabilities) for Teamix Evo",
+  "type": "module",
+  "files": [
+    "manifest.json",
+    "_data.json",
+    "skills",
+    "_template"
+  ],
+  "devDependencies": {
+    "@clack/prompts": "^0.8.0",
+    "tsx": "^4.0.0",
+    "@teamix-evo/registry": "0.2.0"
+  },
+  "scripts": {
+    "validate": "tsx scripts/validate-skills.ts",
+    "scaffold:skill": "tsx scripts/scaffold-skill.ts",
+    "test": "echo 'validate only' && pnpm validate",
+    "typecheck": "echo 'no ts source'",
+    "lint": "echo 'no ts source'",
+    "build": "echo 'pure resource package, no build needed'"
+  }
+}

package/skills/teamix-evo-manage/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: teamix-evo-manage
+description: Use this skill when the user asks to install, initialize, update, list, or uninstall the teamix-evo toolkit (design system, skills, or related packages) inside the current project. Triggers include phrases like "init teamix-evo", "set up the design system", "update teamix-evo", "remove teamix-evo", "list installed teamix-evo packages", or any lifecycle question about teamix-evo packages such as @teamix-evo/design and @teamix-evo/skills.
+---
+
+# teamix-evo-manage
+
+This skill helps the user manage the **teamix-evo** toolkit lifecycle inside their project.
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## When to use
+
+Activate when the user wants to **install / update / inspect / remove** any
+teamix-evo package — typically the design system (`@teamix-evo/design`) or the
+skills package (`@teamix-evo/skills`). Common signals:
+
+- "帮我初始化 teamix-evo 设计体系" / "set up @teamix-evo/design"
+- "升级 teamix-evo" / "update teamix-evo skills"
+- "卸载 teamix-evo" / "remove the design system"
+- "看看装了哪些 teamix-evo 资源"
+
+## What you can do for the user
+
+The CLI binary is `teamix-evo` (bin name), backed by the npm package also
+called `teamix-evo`. All operations are split into **package families**:
+
+### Design system (`@teamix-evo/design`)
+
+| Goal             | Command                                                    |
+| ---------------- | ---------------------------------------------------------- |
+| Initialize       | `npx teamix-evo design init [variant] [--tailwind v3\|v4]` |
+| Update resources | `npx teamix-evo design update`                             |
+| List installed   | `npx teamix-evo design list`                               |
+| Uninstall        | `npx teamix-evo design uninstall [-y] [--keep-files]`      |
+
+- Default variant: `opentrek`.
+- `--tailwind` controls which token entry is wired in. Default: **v4**.
+- Resources marked `frozen` / `regenerable` are physical files; `managed`
+  files use embedded regions (`<!-- teamix-evo:managed:start id="..." -->`)
+  so the user's custom edits survive updates.
+
+### Skills (`@teamix-evo/skills`)
+
+| Goal           | Command                                   |
+| -------------- | ----------------------------------------- |
+| Add (all)      | `npx teamix-evo skills add`               |
+| Add (one+)     | `npx teamix-evo skills add <name...>`     |
+| List (all)     | `npx teamix-evo skills list` (alias `ls`) |
+| List installed | `npx teamix-evo skills list --installed`  |
+| Update         | `npx teamix-evo skills update`            |
+| Uninstall      | `npx teamix-evo skills uninstall [-y]`    |
+
+`skills add` modes:
+
+- **Bulk** (no positional args): installs every skill declared in the
+  manifest. On a project that already has a skills package installed, returns
+  `already-added`.
+- **Incremental** (one or more skill ids): only installs the listed skills.
+  Skills already present are skipped (use `skills update` to refresh). When the
+  project already has a skills config, `--ide` / `--scope` may be omitted —
+  they default to the previously chosen values.
+
+`skills add` is interactive (only when no prior config and no flags):
+
+1. Multi-select target IDE(s): **Qoder** and/or **Claude Code** (default both,
+   at least one required). Non-interactive equivalent: `--ide qoder,claude`.
+2. Scope: **project** (default; `.qoder/.claude` in cwd) or **global**
+   (`~/.qoder/~/.claude`). Non-interactive: `--scope project|global`.
+
+Skills are installed as `SKILL.md` (Anthropic-compatible frontmatter, also
+recognized by Qoder) under `<base>/skills/<name>/SKILL.md`. Update strategy is
+`managed`, so the user's edits inside SKILL.md outside of the marked regions
+are preserved on `update`.
+
+## Workflow you should follow
+
+1. **Detect intent.** Confirm which package family the user wants to touch
+   (design vs skills vs both).
+2. **Check current state.** Suggest running `npx teamix-evo design list` and
+   `npx teamix-evo skills list` to see what's already installed before
+   changing anything.
+3. **Run the smallest correct command.** Prefer the dedicated lifecycle
+   subcommand. Avoid hand-crafted file edits inside `.qoder/`, `.claude/`, or
+   `.teamix-evo/` — let the CLI write through.
+4. **Report and verify.** After running, summarize what changed (files
+   touched, version, IDE, scope) and re-run `list` if useful.
+
+## Configuration files (informational)
+
+- `<projectRoot>/.teamix-evo/config.json` — declares which packages are
+  installed, their versions, IDE selection and scope.
+- `<projectRoot>/.teamix-evo/manifest.json` — installed-resource ledger;
+  CLI uses it for diffing and uninstalling.
+
+Both are **owned by the CLI**. Don't edit by hand unless the user explicitly
+asks; recommend the CLI subcommand instead.
+
+## Common pitfalls
+
+- The CLI must be run from the project root (where `.teamix-evo/` lives or
+  will be created).
+- For `design uninstall`, `managed` files are kept by default to protect user
+  edits. Use `--keep-files` to keep everything (only updates the ledger).
+- A skill's `description` is the AI trigger contract — keep it specific and
+  scenario-rich when editing.
+
+## Console preset upgrade (placeholder → real UI)
+
+Projects scaffolded by `npm create teamix-evo@latest -- --preset console`
+ship with a set of **placeholder components** under
+`src/components/_placeholder/` (Card / Input / Form / Table). They are marked
+with the literal `@teamix-evo:placeholder` tag at the top of each file and
+are registered in `.teamix-evo/create/pending-ui.json`.
+
+**When the user asks to "upgrade UI", "replace placeholders", "接入真组件"**:
+
+1. Read `.teamix-evo/create/pending-ui.json` to know which component IDs are
+   pending and where the placeholder files live.
+2. For each pending component, run `npx teamix-evo ui add <id>` (e.g.
+   `card`, `input`, `form`, `table`). This writes the real implementation to
+   `src/components/ui/<id>.tsx`.
+3. Update import sites: replace `@/components/_placeholder/<Name>` with
+   `@/components/ui/<id>` and adapt the API surface as needed (the real
+   shadcn-style components may have a different signature).
+4. Delete the placeholder file once all references are migrated.
+5. Remove the corresponding entry from `.teamix-evo/create/pending-ui.json`
+   (or delete the file if `pendingComponents` becomes empty).
+
+Grep for `@teamix-evo:placeholder` to discover any remaining placeholders.
+Never leave placeholders in production builds — they are intentionally
+minimal and unstyled.
+
+<!-- teamix-evo:managed:end id="core" -->
+
+## Notes for the user
+
+> 这部分内容由你自由编辑。CLI 升级时只会替换 `id="core"` 区段，不会动这里的笔记。