问题导向的 Agent Skills 编写实践：如何让 vue-tsc 检查未声明 Vue 组件

误区和反思我的实践：让 vue-tsc 检查出未声明的组件第一版测试 Skill 迭代最终 Skill

最近终于有时间有兴趣去了解 agent skill 到底是个什么东西，用来干什么。这次尝试了一次有意思的学习方式，我告诉 Claude Code 我想学习 skill 是什么，希望它能够当一个严格老师，帮我理解 skill 的概念和写法。下面是在“老师”的指导下，我的实践记录。

误区和反思

在尝试编写 skill 的时候，我犯的第一个错误就是， “我觉得这个领域应该有个 skill，所以我要写一个 skill” 。好在 AI 马上指出这个想法是错的，要求我必须找到一个实际问题，再去写 skill 解决它。

最终总结出来，编写 skill 的两个关键应用场景

应对知识盲区：处理 AI 自己做不到或做不好的情况。

提升效率：AI 能搞定，但直接给答案能省 token，节省上下文空间

并且，这给出了一个判断 skill 价值的逻辑，如果你的 skill 着两个都不沾，那大概率它就不应该是一个 skill。

所以，像我一上来就想着”我要写一个关于 X 的 skill” ，然后开始空想，这是错的。

正确的流程是：

先找到问题：让 AI 做某个任务，观察它在哪里失败

确认问题真实存在：不是你以为 AI 不会，而是你亲眼看到它不会

写 skill 解决这个问题：只写解决问题需要的内容

测试、迭代、完善：看看 AI 用了 skill 之后表现如何，继续改

我的实践：让 vue-tsc 检查出未声明的组件

最近有段时间在折腾 Vue 3 + TypeScript 项目，期间发现自己 <template> 里写了不存在的组件，但是 vue-tsc 没报错，让 AI 整了一遍，一通瞎改后，还是不行。我开始以为是不支持，就自己手动搜索了下，发现 Vue Language Tools 的文档里有个 vueCompilerOptions 配置项，里面有 strictTemplates 和 checkUnknownComponents 这些选项。

只是默认都是 false。

这里，AI 不知道这些选项，或者说知道得不够准确。就是一个典型的 AI 知识盲区的场景。

第一版

基于这个发现，我写了第一版 skill。

首先是定义部分，这部分决定了 skill 什么时候被触发：


---
name: vue-tsc-compiler-options
description: Configures Vue 3 template type checking via vueCompilerOptions in tsconfig.json. Covers strictTemplates, checkUnknownComponents, checkUnknownProps, checkUnknownEvents, and checkUnknownDirectives. Use when setting up vue-tsc, diagnosing unknown component errors, or enabling strict template validation.
---

这里写 description 有个要点，内容要包含两个关键的部分。第一是说明做什么，第二是什么时候用，也就是触发词，要包含可能触发的关键词（vue-tsc、unknown component、strict template）

接下来是正文部分，内容尽量简洁，只写必要的信息：


# Vue Compiler Options for Type Checking

## Quick Reference

Enable strict template checking in `tsconfig.json`:

```json
{
  "vueCompilerOptions": {
    "strictTemplates": true
  }
}
```

## Options

| Option | Default | Effect |
|--------|---------|--------|
| `strictTemplates` | `false` | Enables all checkUnknown* options below |
| `checkUnknownComponents` | `false` | Error on undefined/unregistered components |
| `checkUnknownProps` | `false` | Error on props not declared in component definition |
| `checkUnknownEvents` | `false` | Error on events not declared via `defineEmits` |
| `checkUnknownDirectives` | `false` | Error on unregistered custom directives |

## Reference

Full documentation: https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options

整个 skill 不到 50 行。只写必要的信息，URL 留着让 AI 需要时自己去查。

测试 Skill

带着这个 skill 再让 AI 配置，它确实加上了 strictTemplates: true，但是加的很曲折。

这里有个背景知识要补充下。

现在一个 vue3 + TS 的项目，一般会有多个 tsconfig 文件：

tsconfig.json：顶层，通常只是用来引用其他配置

tsconfig.app.json：应用代码的配置，Vue 文件在这里

tsconfig.node.json：Vite 配置文件用的

AI 第一次加到了 tsconfig.json 里面，而不是 tsconfig.app.json，发现没起作用后，又瞎改了一通，直到最后一次才改对，加到了 tsconfig.app.json 里。

这次测试反馈说明 skill 还不够完善，还不够下基层，得再说清楚点，该往哪个文件加配置。

迭代

我考虑过直接硬编码”用 tsconfig.app.json“，但不同项目结构可能不一样。最后决定给一个提示而不是硬规则：


## Which tsconfig?

Add `vueCompilerOptions` to the tsconfig that includes Vue source files. In projects with multiple tsconfigs, this is typically `tsconfig.app.json`, not the root `tsconfig.json` or `tsconfig.node.json`.

这样 AI 有了方向感，但不会在遇到非标准项目结构时出错。

最终 Skill


---
name: vue-tsc-compiler-options
description: Configures Vue 3 template type checking via vueCompilerOptions in tsconfig.app.json. Covers strictTemplates, checkUnknownComponents, checkUnknownProps, checkUnknownEvents, and checkUnknownDirectives. Use when setting up vue-tsc, diagnosing unknown component errors, or enabling strict template validation.
---

# Vue Compiler Options for Type Checking

## Which tsconfig?

Add `vueCompilerOptions` to the tsconfig that includes Vue source files. In projects with multiple tsconfigs, this is typically `tsconfig.app.json`, not the root `tsconfig.json` or `tsconfig.node.json`.

## Quick Reference

Enable strict template checking in `tsconfig.app.json`:

```json
{
  "compilerOptions": { ... },
  "vueCompilerOptions": {
    "strictTemplates": true
  }
}
```

This enables all `checkUnknown*` options automatically.

## Options

| Option | Default | Effect |
|--------|---------|--------|
| `strictTemplates` | `false` | Enables all checkUnknown* options below |
| `checkUnknownComponents` | `false` | Error on undefined/unregistered components |
| `checkUnknownProps` | `false` | Error on props not declared in component definition |
| `checkUnknownEvents` | `false` | Error on events not declared via `defineEmits` |
| `checkUnknownDirectives` | `false` | Error on unregistered custom directives |

## Granular Control

If `strictTemplates` is too strict, enable individual checks:

```json
{
  "vueCompilerOptions": {
    "checkUnknownComponents": true,
    "checkUnknownProps": false
  }
}
```

## Common Issue

**Problem:** vue-tsc passes but undefined components exist in templates.

**Cause:** `checkUnknownComponents` defaults to `false`.

**Fix:** Enable `strictTemplates` or `checkUnknownComponents` explicitly.

## Reference

Full documentation: https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options