fix(cli): relocate skills setting to experimental namespace

fix(core): parse skills frontmatter with CRLF/BOM

docs/users/configuration/settings.md

@@ -311,6 +311,12 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
 >
 > **Note about advanced.tavilyApiKey:** This is a legacy configuration format. For Qwen OAuth users, DashScope provider is automatically available without any configuration. For other authentication types, configure Tavily or Google providers using the new `webSearch` configuration format.
 
+#### experimental
+
+| Setting               | Type    | Description                      | Default |
+| --------------------- | ------- | -------------------------------- | ------- |
+| `experimental.skills` | boolean | Enable experimental Agent Skills | `false` |
+
 #### mcpServers
 
 Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Qwen Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. At least one of `command`, `url`, or `httpUrl` must be provided. If multiple are specified, the order of precedence is `httpUrl`, then `url`, then `command`.

docs/users/features/skills.md

@@ -11,12 +11,29 @@ This guide shows you how to create, use, and manage Agent Skills in **Qwen Code*
 ## Prerequisites
 
 - Qwen Code (recent version)
-- Run with the experimental flag enabled:
+
+## How to enable
+
+### Via CLI flag
 
 ```bash
 qwen --experimental-skills
 ```
 
+### Via settings.json
+
+Add to your `~/.qwen/settings.json` or project's `.qwen/settings.json`:
+
+```json
+{
+  "tools": {
+    "experimental": {
+      "skills": true
+    }
+  }
+}
+```
+
 - Basic familiarity with Qwen Code ([Quickstart](../quickstart.md))
 
 ## What are Agent Skills?

packages/cli/src/config/config.ts

@@ -334,7 +334,14 @@ export async function parseArguments(settings: Settings): Promise<CliArgs> {
         .option('experimental-skills', {
           type: 'boolean',
           description: 'Enable experimental Skills feature',
-          default: false,
+          default: (() => {
+            const legacySkills = (
+              settings as Settings & {
+                tools?: { experimental?: { skills?: boolean } };
+              }
+            ).tools?.experimental?.skills;
+            return settings.experimental?.skills ?? legacySkills ?? false;
+          })(),
         })
         .option('channel', {
           type: 'string',

packages/cli/src/config/settings.ts

@@ -922,6 +922,21 @@ export function migrateDeprecatedSettings(
 
       loadedSettings.setValue(scope, 'extensions', newExtensionsValue);
     }
+
+    const legacySkills = (
+      settings as Settings & {
+        tools?: { experimental?: { skills?: boolean } };
+      }
+    ).tools?.experimental?.skills;
+    if (
+      legacySkills !== undefined &&
+      settings.experimental?.skills === undefined
+    ) {
+      console.log(
+        `Migrating deprecated tools.experimental.skills setting from ${scope} settings...`,
+      );
+      loadedSettings.setValue(scope, 'experimental.skills', legacySkills);
+    }
   };
 
   processScope(SettingScope.User);

packages/cli/src/config/settingsSchema.ts

@@ -1207,6 +1207,16 @@ const SETTINGS_SCHEMA = {
     description: 'Setting to enable experimental features',
     showInDialog: false,
     properties: {
+      skills: {
+        type: 'boolean',
+        label: 'Skills',
+        category: 'Experimental',
+        requiresRestart: true,
+        default: false,
+        description:
+          'Enable experimental Agent Skills feature. When enabled, Qwen Code can use Skills from .qwen/skills/ and ~/.qwen/skills/.',
+        showInDialog: true,
+      },
       extensionManagement: {
         type: 'boolean',
         label: 'Extension Management',

packages/cli/src/i18n/locales/zh.js

@@ -873,11 +873,11 @@ export default {
   'Session Stats': '会话统计',
   'Model Usage': '模型使用情况',
   Reqs: '请求数',
-  'Input Tokens': '输入令牌',
-  'Output Tokens': '输出令牌',
+  'Input Tokens': '输入 token 数',
+  'Output Tokens': '输出 token 数',
   'Savings Highlight:': '节省亮点：',
   'of input tokens were served from the cache, reducing costs.':
-    '的输入令牌来自缓存，降低了成本',
+    '从缓存载入 token ，降低了成本',
   'Tip: For a full token breakdown, run `/stats model`.':
     '提示：要查看完整的令牌明细，请运行 `/stats model`',
   'Model Stats For Nerds': '模型统计（技术细节）',

packages/cli/src/utils/commentJson.test.ts

@@ -8,7 +8,10 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { updateSettingsFilePreservingFormat } from './commentJson.js';
+import {
+  updateSettingsFilePreservingFormat,
+  applyUpdates,
+} from './commentJson.js';
 
 describe('commentJson', () => {
   let tempDir: string;
@@ -180,3 +183,18 @@ describe('commentJson', () => {
     });
   });
 });
+
+describe('applyUpdates', () => {
+  it('should apply updates correctly', () => {
+    const original = { a: 1, b: { c: 2 } };
+    const updates = { b: { c: 3 } };
+    const result = applyUpdates(original, updates);
+    expect(result).toEqual({ a: 1, b: { c: 3 } });
+  });
+  it('should apply updates correctly when empty', () => {
+    const original = { a: 1, b: { c: 2 } };
+    const updates = { b: {} };
+    const result = applyUpdates(original, updates);
+    expect(result).toEqual({ a: 1, b: {} });
+  });
+});

packages/cli/src/utils/commentJson.ts

@@ -38,7 +38,7 @@ export function updateSettingsFilePreservingFormat(
   fs.writeFileSync(filePath, updatedContent, 'utf-8');
 }
 
-function applyUpdates(
+export function applyUpdates(
   current: Record<string, unknown>,
   updates: Record<string, unknown>,
 ): Record<string, unknown> {
@@ -50,6 +50,7 @@ function applyUpdates(
       typeof value === 'object' &&
       value !== null &&
       !Array.isArray(value) &&
+      Object.keys(value).length > 0 &&
       typeof result[key] === 'object' &&
       result[key] !== null &&
       !Array.isArray(result[key])

packages/core/src/skills/skill-manager.test.ts

@@ -112,6 +112,62 @@ You are a helpful assistant with this skill.
       expect(config.filePath).toBe(validSkillConfig.filePath);
     });
 
+    it('should parse markdown with CRLF line endings', () => {
+      const markdownCrlf = `---\r
+name: test-skill\r
+description: A test skill\r
+---\r
+\r
+You are a helpful assistant with this skill.\r
+`;
+
+      const config = manager.parseSkillContent(
+        markdownCrlf,
+        validSkillConfig.filePath,
+        'project',
+      );
+
+      expect(config.name).toBe('test-skill');
+      expect(config.description).toBe('A test skill');
+      expect(config.body).toBe('You are a helpful assistant with this skill.');
+    });
+
+    it('should parse markdown with UTF-8 BOM', () => {
+      const markdownWithBom = `\uFEFF---
+name: test-skill
+description: A test skill
+---
+
+You are a helpful assistant with this skill.
+`;
+
+      const config = manager.parseSkillContent(
+        markdownWithBom,
+        validSkillConfig.filePath,
+        'project',
+      );
+
+      expect(config.name).toBe('test-skill');
+      expect(config.description).toBe('A test skill');
+    });
+
+    it('should parse markdown when body is empty and file ends after frontmatter', () => {
+      const frontmatterOnly = `---
+name: test-skill
+description: A test skill
+---`;
+
+      const config = manager.parseSkillContent(
+        frontmatterOnly,
+        validSkillConfig.filePath,
+        'project',
+      );
+
+      expect(config.name).toBe('test-skill');
+      expect(config.description).toBe('A test skill');
+      expect(config.body).toBe('');
+    });
+
     it('should parse content with allowedTools', () => {
       const markdownWithTools = `---
 name: test-skill

packages/core/src/skills/skill-manager.ts

@@ -307,9 +307,11 @@ export class SkillManager {
     level: SkillLevel,
   ): SkillConfig {
     try {
+      const normalizedContent = normalizeSkillFileContent(content);
+
       // Split frontmatter and content
-      const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
-      const match = content.match(frontmatterRegex);
+      const frontmatterRegex = /^---\n([\s\S]*?)\n---(?:\n|$)([\s\S]*)$/;
+      const match = normalizedContent.match(frontmatterRegex);
 
       if (!match) {
         throw new Error('Invalid format: missing YAML frontmatter');
@@ -556,3 +558,13 @@ export class SkillManager {
     }
   }
 }
+
+function normalizeSkillFileContent(content: string): string {
+  // Strip UTF-8 BOM to ensure frontmatter starts at the first character.
+  let normalized = content.replace(/^\uFEFF/, '');
+
+  // Normalize line endings so skills authored on Windows (CRLF) parse correctly.
+  normalized = normalized.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+  return normalized;
+}