Coding standards implemented as AI Coding can become truly usable skills

Taking the front-end coding standards in the project (vue-code-convention skill) as an example, the system disassembles how to consolidate front-end project standards scattered across code, documentation, and team experience into AI development skills that are triggerable, adjudicable, executable, verifiable, and continuously iteratable.

When AI truly starts participating in project development, we quickly encounter a problem: it can write Vue, knows TypeScript, Pinia, and Vue Router, but it may not necessarily know how this project should be written.

It might put a new page into a technically correct yet never-before-used project directory; it might create composables/ in a repository that usually organizes business workflows with hooks/; it might also refactor the team's code structure that has been running stably for years in pursuit of 'best practices'.

This does not mean AI is not smart enough. On the contrary, the problem is that general knowledge gives it too many reasonable answers, while project development requires a set of answers chosen by the team.

The role of Project Development Skill is to distill these choices into a project context that AI can understand and execute. It is not about writing another coding standard for humans to read, nor is it about copying ESLint documentation into Markdown. Rather, it is about creating a decision-making system for AI: which tasks require consulting it, whose opinion to follow when conflicts arise, which rules cannot be changed, which details can be judged in context, and how to demonstrate that the result meets project requirements once completed.

This article uses vue-code-convention, which I developed, as an example to discuss how to design such a Skill for your own front-end project.

1. First distinguish: coding standards, prompts, and Skills are not the same thing

The three seem to 'tell AI what to do,' but their responsibilities differ.

Ordinary standards often only describe the outcome, e.g., "component files use PascalCase." An effective Skill should also include its applicable scope, exceptions, and conflict resolution: page module directories use kebab-case, component files use PascalCase, route entry points must be index.vue. Otherwise, AI might correctly execute one instruction but disrupt the overall structure.

Prompts are not suitable for carrying these contents long-term. Repeating every time "API methods must end with Api, do not use any, where to place new business modules" is not only inefficient but also very prone to omissions.

Therefore, the relationship among the three can be summarized as:

Prompts describe the current task, Skills provide the long-term decision environment, and code and tools are responsible for the final constraints.

2. The raw material for a good Skill is not the standards you remember, but the facts in the repository

Many people, when writing project Skills, first open a blank document and list "best practices" from memory. This easily turns into a general tutorial rather than a project Skill.

A more reliable method is to first perform project archaeology, collecting evidence from the real repository:

1. Read AGENTS.md, CLAUDE.md, copilot-instructions.md, the README, architecture documents, and historical standards.
2. Identify two or three high-quality representative modules.
3. Compare new modules with legacy modules to distinguish "current standards" from "historical baggage."
4. Check package.json, TypeScript, ESLint, Vite, testing, and build configurations.
5. Review real cases where AI or new members are most prone to mistakes.
6. Identify project decisions that cannot be checked by static tools but affect long-term maintenance. The part of vue-code-convention with the most project value is not general knowledge like 'using const instead of var,' but the information below that cannot be known just by looking at the framework documentation:

src/views/<feature-module>/
├── index.vue
├── api/
├── components/
├── composables/
├── functional/
├── hooks/
├── config/
├── modules/
├── styles/
├── types/
├── utils/
└── locales/

This structure addresses a large number of practical issues: where to place a routable large business function, how to distinguish between business components and low-coupling reusable units, whether side effects and process orchestration should go into hooks/ or utils/, when types need a separate directory, and which directories should only be created on demand.

What is particularly important is that the Skill clearly states: the complete directory is just a 'directory vocabulary,' not a scaffold that needs to be copied every time a module is created. index.vue is required, while other directories should only be created when they have actual responsibilities. This one constraint can directly prevent AI from generating a batch of empty directories.

This is exactly the content that project Skills should prioritize: if you do not tell AI, it is difficult for it to infer this from the current task based solely on general capabilities, and guessing wrong would gradually cause the project to lose knowledge consistency.

3. Write usage scenarios first, then rules

Before writing a Skill, first list the real tasks it needs to handle. For example, a Vue project development Skill should at least cover:

• Creating a new business module that can be independently carried by the menu;
• Adding components, interfaces, or business hooks to existing modules;
• Splitting a Vue page that has become too large;
• Refactoring data requests, reactive states, or listener logic;
• Determining whether a piece of code should remain inside a module or be promoted to a shared directory;
• Modifying existing functions and completing validations according to project practices.

The value of scenarios lies in exposing decision points. Taking 'adding a new user management page' as an example, AI needs to consecutively make the following judgments:

任务是否属于大型业务模块？
  ↓
应该放入哪个目录？
  ↓
需要创建哪些子目录？
  ↓
请求、状态、类型和组件分别放在哪里？
  ↓
应该沿用哪个现有模块？
  ↓
完成后执行哪些检查？

If a Skill can only respond with "Vue code uses <script setup>" but cannot answer this decision chain, it is still just a code style checklist.

It is recommended to continue asking four questions for each scenario:

• At which step is AI most likely to guess wrong?
• Which file or module in the repository represents the correct approach?
• Is this rule a mandatory constraint, or can it change depending on the task?
• How can we verify that AI actually got it right?

What should ultimately be written into the Skill is not all knowledge, but the high-value answers to these questions.

4. description is not a summary, but the trigger for the Skill

The main text of a Skill is only read after it is triggered. Therefore, the description in the frontmatter determines whether the Skill can appear at the right time.

An overly broad description might be:

description: Vue 3 项目编码规范。

It explains the topic, but does not specify when to use it. AI may not be able to determine that this Skill is related to directory restructuring when faced with 'splitting the user management page.'

The handling method of vue-code-convention is closer to a trigger condition:

---
name: vue-code-convention
description: Authoritative Vue 3 + TypeScript development conventions. MUST be loaded for new Vue feature development, feature refactoring, components, composables, hooks, API modules, directory structure decisions, async requests, reactive state, comments, and performance work.
---

Three things are stated here at the same time:

• What it is: Vue 3 + TypeScript project development standards;
• When to use it: new features, feature refactoring, components, hooks, APIs, directories, requests, and performance work;
• Its status: an authoritative source in related project decisions.

When writing your own description, you can use the following formula:

Scope of authority + specific triggering tasks + key project objects + necessary authority explanation

Do not write 'when to use' only in the main text's 'Applicable Scenarios' section, because AI cannot see the main text when deciding whether to load a Skill.

5. What really determines execution quality is rule precedence

A front-end task may trigger multiple Skills at the same time: Vue standards, UI design, accessibility, performance, Pinia, Router, testing, etc. Each of them may be reasonable, but not necessarily consistent with the current project's directory structure and historical choices.

Therefore, project Skills must declare how conflicts are resolved. The priority given by vue-code-convention is:

1. User's explicit requirements
2. AGENTS.md in the repository (CLAUDE.md, copilot-instructions.md, etc.)
3. vue-code-convention
4. Other Vue and front-end skills

At the same time, it further specifies: other Skills can optimize types, component design, testing, accessibility, and performance, but cannot replace the functional directory structure specified by the project.

The value of this content is far higher than adding ten more code style rules because it delineates the boundary between 'allowed optimizations' and 'forbidden rewrites':

• Project Skills are responsible for defining the stable skeleton of this repository;
• Specialized Skills are responsible for improving the quality of local implementations;
• Users can still explicitly request an exception;
• AI does not need to guess among multiple seemingly equivalent suggestions.

If a repository has both repository rules and personal Skills, duplication of the same guideline must also be avoided. A suitable division of responsibilities is:

• AGENTS.md, CLAUDE.md, copilot-instructions.md, and similar files contain repository-level collaboration rules, Skill selection rules, and top-level constraints;
• Project Skills contain the complete decision knowledge for a certain type of development task;
• ESLint, TypeScript, and testing consolidate machine-checkable rules;
• Task prompts only describe the goal and acceptance criteria of the current change.

6. Grade the rules: not all requirements should be written as MUST

If Skills are written too loosely, AI will act freely; if written too rigidly, they will execute mechanically in inappropriate scenarios. The key is not to use more 'MUSTs', but to set appropriate flexibility for different decisions.

Frontend project rules can be divided into four categories:

To determine whether a rule should be mandatory, you can ask:

1. Would violating it inevitably cause errors or project structure fragmentation?
2. Are there legal and common counterexamples?
3. Can tools automatically check it?
4. Is the current project code already consistently following it?

For example, "All independent requests should be put into try...catch...finally" is very clear, but finally only actually provides value when cleanup logic is needed; if there is no loading, lock, or temporary state to restore, enforcing an empty finally can instead create noise. A more robust approach could be: requests must explicitly define error boundaries; use finally when mandatory cleanup logic exists; prohibit bare requests without error handling.

Another example: "600 lines must be split" is suitable as a project guardrail but should not be the sole basis. A 450-line component mixing request orchestration, table configuration, and popup state may already need splitting; a purely structured declarative configuration file, even if slightly long, may not need to be broken down. It is best for Skills to specify both the numerical threshold and the underlying maintenance goal.

The more rigid a rule is, the more strictly you need to verify that it has no counterexamples. MUST is not about emphasis; it is a maintenance commitment.

7. Express Key Decisions with “Rule + Reason + Positive and Negative Examples + Exceptions”

If you only write the conclusion, AI can apply it mechanically; if you only explain the principle, AI might derive answers different from the project. For important rules, the most effective expression structure is usually:

Rule → Why → Correct Example → Incorrect Example → When Exceptions Occur

The description of vue-code-convention for defineModel is an intuitive example:

// Vue 3.4+
const visible = defineModel<boolean>("visible");
const count = defineModel<number>("count", { default: 0 });

The rules are not just about 'using the new API'; they also specify the version prerequisites and provide the naming format for models. Therefore, AI can determine that it only executes when the project version meets Vue 3.4+, and props + emits must still be used when maintaining older versions of the project.

The directory rules are also suitable for this expression:

hooks/       place business state, side effects, and flow orchestration
utils/       place stateless pure functions
components/  place components with business logic
composables/ place low-coupling reusable units

Compared with 'reasonably splitting files,' this kind of boundary definition is more actionable. To reduce ambiguity, a pair of specific examples can also be added: useUserTable includes requests, loading, and lifecycle, moving into hooks/; formatUserName only accepts parameters and returns a string, moving into utils/.

However, the reasons do not need to be written as a long tutorial. Skill usage context is a limited resource and should prioritize preserving information that will change decisions. Things like 'var has variable hoisting' are typically common knowledge the model already knows; whereas 'why this project separates hooks/ and composables/' is worth explaining.

8. Write the directory structure as a decision model, not a static tree

In front-end project Skills, the directory structure is often the rule that has the greatest impact, because a single misplaced decision can be repeatedly mimicked by subsequent features.

Providing only the directory tree is not enough; at a minimum, four types of questions must be answered.

1. When to use this structure

vue-code-convention clearly states that this structure is intended for large business features that can be independently supported by menus, such as user management and role management; simple features are not recommended to adopt the full structure.

This can prevent AI from 'architecting' a small page of only a few dozen lines into a dozen files.

2. Which directories are necessary, which should be created as needed

Routing pages index.vue are necessary, while other directories should be created according to actual responsibilities, without generating empty placeholder directories.

3. What are the boundaries between adjacent directories

Clear distinctions are needed between hooks/ and utils/, components/ and composables/, modules/ and ordinary components. Directory names themselves cannot replace responsibility explanations.

4. When should code be upgraded to shared capabilities

If multiple features reuse the same piece of code, it should be promoted to shared directories such as src/components, src/api, or src/utils, instead of continuing to copy it into each separate module.

Therefore, a complete directory Skill is not a map of 'where to put files,' but a model of 'under what conditions code should be moved.'

Single use → place nearby
Multiple reuse within a module → module-level directory
Reuse across multiple business modules → project shared directory
Independent sub-business → modules/

This model maintains project boundaries better than continuously adding directory names.

9. Separate Versions, Facts, and Preferences

Project Skills often mix three types of content:

• Language or framework facts, such as the timing of dependency collection in watchEffect;
• Version-specific capabilities, such as defineModel in Vue 3.4, deep in Vue 3.5;
• Team preferences, such as always using const arrow functions for functions.

These three types of content require different maintenance approaches. Framework facts need to match official documentation and actual runtime results; version capabilities need to specify the minimum version; team preferences only need to align with project consensus but should not be presented as language-level absolute truths.

This step is very important because the code in Skills can be taken by AI as reliable references. A nonexistent operator, a deprecated API, or an example incompatible with the project's TypeScript version may be copied into multiple features.

For example, when maintaining the "Modern Operators" section, the compiler should be used to verify whether the examples actually work. ??, ?., ??= are syntax supported by JavaScript/TypeScript; if a format like ?= appears in the documentation, it must first be confirmed whether it comes from a specific proposal, compiler plugin, or library, and should not be listed as a standard operator based on memory alone.

Similarly, directory naming should distinguish levels: functional module directories can be kebab-case, and Vue component files can use PascalCase. This is not contradictory but reflects naming rules for two different objects. Skills should write objects completely, rather than just making broad conclusions like "filenames use PascalCase."

10. Don't Leave Everything That Can Be Automatically Checked to Text

Skills excel at providing judgment, while tools excel at ensuring certainty. The two should collaborate, not replace each other.

If a particular check requires AI to rewrite a script each time, it should be considered to put it into Skill scripts/; if the project has stable page or module templates, they can be put into assets/; if the API conventions, component library documentation, or business dictionary are very long, they can be split into references/ for on-demand reading.

An extensible project Skill can adopt the following structure:

vue-project-development/
├── SKILL.md
├── references/
│   ├── feature-structure.md
│   ├── api-conventions.md
│   └── testing-policy.md
├── scripts/
│   └── validate-feature-structure.mjs
└── assets/
    └── feature-template/

SKILL.md retains only the core workflow after triggering, the rule priority, and resource navigation. api-conventions.md is read only when a task involves an API, and feature-structure.md is read only when creating a large functional module. This is progressive disclosure: allowing AI to get enough information at the right time, rather than loading all project knowledge every time.

11. Verification strategy must be written into the Skill

A development Skill without a verification loop can only increase the probability of "looking like project code," but cannot guarantee that the results can actually be merged.

A project-level Skill must at least tell AI to:

• First discover available commands from package.json or project documentation, and do not invent commands;
• Prioritize checks that are directly related to changes;
• Then execute linting, type checks, tests, and builds according to risk;
• Existing tests must not be deleted, skipped, or weakened to pass;
• Checks that cannot be performed must state the reason;
• Do not claim that checks have passed without actual execution.

The strategy in vue-code-convention, "ordinary business features do not require new unit tests by default," is also quite representative. It does not simply apply "all code must be tested," but connects test investment with project reality: ordinary business changes mainly rely on linting, type checking, building, and targeted manual verification; shared libraries, public contracts, and high-risk logic then determine whether to add unit tests based on complexity and regression risk.

This kind of rule is more executable than a slogan because it answers the question "when is it worth testing." Of course, each team's answer may differ. The key is to make the Skill reflect the real engineering strategy, rather than a set of ideal processes that cannot be fulfilled.

Verification should also cover the Skill itself: whether the YAML frontmatter is valid, whether referenced files exist, whether examples can compile, whether commands match the current project, and whether rules conflict with each other. When the project upgrades Vue, TypeScript, or build tools, the relevant sections must also be reviewed simultaneously.

12. Use failure cases to drive Skill iteration

It is difficult to write a Skill completely in one go. High-value rules often come from repeated specific failures:

• AI put business side effects into utils/;
• Created a complete directory tree for simple pages;
• Wrapped an additional layer defineAsyncComponent around route lazy loading;
• Used the index as key in the list;
• Generated a large number of low-value assertions to comply with 'must be tested';
• Reorganized the entire function directory after reading another design Skill.

After each failure, do not immediately add a stronger 'prohibition'. First, determine which layer the failure occurred in:

1. Not triggered: Complete the task keywords in the description.
2. Triggered but information not found: Adjust the structure of the text or resource navigation.
3. Ambiguous rules: Add applicable conditions, positive and negative examples, or directory boundaries.
4. Multiple conflicting rules: Add priority and exception handling.
5. Execution results unstable: Replace plain text with scripts, templates, or tools.
6. Rule itself unreasonable: Reduce the enforcement level or delete it.

You can establish a simple evaluation set and repeatedly test the Skill with fixed tasks:

Task A: Add a large user management module
Observation: Check whether directories are created as needed, and whether APIs, hooks, and types are placed correctly

Task B: Add two parallel requests to an existing page
Observation: Check whether loading, error boundaries, and parallel failure strategies are handled correctly

Task C: Split a 700-line component
Observation: Check whether it is split according to responsibilities rather than evenly by lines of code

Task D: Modify a small display component
Observation: Check whether the structure of large business modules and unrelated refactoring is avoided

During evaluation, only give the AI normal tasks and Skills. Do not tell it the 'standard answer' or the questions you suspect in advance; otherwise, you are only measuring prompt-following ability, not the generalization ability of the Skill.

13. What can still be refined from vue-code-convention

Overall, vue-code-convention already possesses the key framework of a project development Skill: clear coverage, authoritative order, specific directory structure, numerous positive and negative examples, and project-level constraints on versions, testing, and performance.

If further evolution is desired, I would prioritize the following actions.

1. Shrink the 'complete specification' into a 'high-value decision set'

Remove common sense that the model already knows and that is enforced by ESLint or TypeScript, leaving context for directory boundaries, project exceptions, validation commands, and real pitfalls.

2. Split long reference content

Separate functional module structures, Vue reactive pitfalls, performance recommendations, and comment conventions into references/, keeping the main file for routing rules to reduce the contextual cost each time it is triggered.

3. Correct absolute rules

Check each MUST and NEVER for reasonable counterexamples. Rules that can be expressed conditionally should not be written as absolute commands just for the sake of appearing strict.

4. Add 'live examples' within the repository

The Skill already points to reference modules, but it can also indicate what each module specifically demonstrates. Reference paths must be verified regularly to prevent them from becoming invalid if files are moved.

5. Establish version and build verification

Check version-related rules when upgrading dependencies; perform minimal compilation verification for all TypeScript and Vue examples; add lightweight scripts to check directory conventions.

This does not negate the existing content; it is the natural evolution when a Skill moves from a 'useful rules collection' toward a 'stable project development system.'

14. A front-end project Skill template that can be directly modified

The following framework can serve as a starting point. It intentionally does not include general Vue knowledge because what truly needs to be supplemented should be your own project-specific answers.

---
name: project-frontend-development
description: Frontend development specifications and workflow for this project. Used for new feature development, feature refactoring, component and state design, API modules, directory and file placement, testing, and validation decisions. Serves as the authoritative source when involving project structure.
---

# Project Frontend Development

## Authority

Handle conflicts in the following order:

1. Explicit user requests
2. Repository AGENTS.md (CLAUDE.md, copilot-instructions.md, etc.)
3. This Skill
4. Other specialized Skills

Other Skills can optimize implementation details but must not alter the project structure defined by this Skill.

## Workflow

1. Read relevant code and representative modules.
2. Determine whether the task is a new feature, partial modification, or refactoring.
3. Select applicable directories and implementation rules.
4. Maintain public interfaces and unrelated behaviors unchanged.
5. Execute validation commands that actually exist in the project.
6. Summarize changes, validation results, and remaining risks.

## Project Invariants

- [Project constraints that must not be violated]
- [Public contracts and compatibility requirements]
- [Patterns prohibited from introduction]

## Feature Structure

- [When to enable module structures]
- [Required directories and on-demand directories]
- [Responsibility boundaries of adjacent directories]
- [Conditions for promoting to shared directories]

## Implementation Decisions

- Requests and error handling: [project choice]
- State management: [project choice]
- Component splitting: [judgment criteria]
- Type placement: [judgment criteria]
- Styles and design system: [project choice]

## Exceptions

- [How to handle legacy modules]
- [Framework version differences]
- [Conditions allowing rule deviations]

## Validation

- Run: [actual project commands]
- Retain and update existing tests.- Do not declare that unperformed checks have passed.

## References

- Read `references/feature-structure.md` when creating large modules.
- Read `references/api-conventions.md` when modifying APIs.
- Read `references/testing-policy.md` when handling high-risk logic.

After using the template, all placeholder content should be removed, leaving only the sections that are genuinely needed for the project. A Skill that is 80 lines long but each line affects decisions is usually more effective than an 800-line front-end knowledge encyclopedia.

Conclusion

Writing a Skill for a front-end project is essentially performing an "executable project knowledge modeling." You need to convert the team's past experiences, which relied on verbal communication, code imitation, and Review corrections, into rules that AI can trigger, retrieve, adjudicate, and verify.

What is most important to remember is not any fixed structure, nor a specific number of rules to write, but the following chain:

Identify decision points from real tasks, extract project rules from repository facts, resolve conflicts using priority, eliminate ambiguity with conditions and examples, verify with tools, and continuously iterate from failure cases.

A Skill truly becomes a part of project development capability only when it enables AI, when faced with new requirements, not only to write correct Vue code but also to proactively find the correct directory, reuse appropriate boundaries, avoid unnecessary refactoring, and perform real validation.