autosnippet 2.5.0 → 2.7.0

package/lib/service/skills/SkillAdvisor.js

@@ -0,0 +1,324 @@
+/**
+ * SkillAdvisor — 基于使用模式的 Skill 推荐引擎
+ *
+ * 分析项目使用行为并推荐创建 Skill：
+ *   1. Guard 违规模式 — 同类违规反复出现 → 编码规范 Skill
+ *   2. Memory 偏好积累 — 用户偏好超过阈值 → 约定总结 Skill
+ *   3. Recipe 分布缺口 — 某类 Recipe 高频使用但无对应 Skill
+ *   4. 搜索 miss — 高频搜索但低命中 → 知识盲区 Skill
+ *
+ * 设计原则：
+ *   - 只做分析和推荐，不自动创建（由 Agent 决策执行 create_skill）
+ *   - 静默降级：任何数据源读取失败不影响其他维度
+ *   - 零 AI 调用 — 纯规则分析，确保即时返回
+ *   - 推荐结果包含 draft 草稿（name + description + rationale），
+ *     Agent 可直接调用 create_skill 创建
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getProjectSkillsPath } from '../../infrastructure/config/Paths.js';
+
+export class SkillAdvisor {
+  #projectRoot;
+  #db;
+
+  /**
+   * @param {string} projectRoot — 用户项目根目录
+   * @param {object} [opts]
+   * @param {object} [opts.database] — better-sqlite3 实例（可选）
+   */
+  constructor(projectRoot, { database } = {}) {
+    this.#projectRoot = projectRoot;
+    this.#db = database || null;
+  }
+
+  /**
+   * 生成 Skill 推荐列表
+   *
+   * @returns {{
+   *   suggestions: Array<{
+   *     name: string,
+   *     description: string,
+   *     rationale: string,
+   *     source: string,
+   *     priority: 'high' | 'medium' | 'low',
+   *     signals: object
+   *   }>,
+   *   analysisContext: object
+   * }}
+   */
+  suggest() {
+    const existingSkills = this.#listExistingProjectSkills();
+    const suggestions = [];
+    const analysisContext = {};
+
+    // ── 维度 1: Guard 违规模式 ──
+    try {
+      const guardInsights = this.#analyzeGuardPatterns();
+      analysisContext.guard = guardInsights.summary;
+      suggestions.push(...guardInsights.suggestions.filter(
+        s => !existingSkills.has(s.name),
+      ));
+    } catch { /* silent */ }
+
+    // ── 维度 2: Memory 偏好积累 ──
+    try {
+      const memoryInsights = this.#analyzeMemoryPatterns();
+      analysisContext.memory = memoryInsights.summary;
+      suggestions.push(...memoryInsights.suggestions.filter(
+        s => !existingSkills.has(s.name),
+      ));
+    } catch { /* silent */ }
+
+    // ── 维度 3: Recipe 分布与使用 ──
+    try {
+      const recipeInsights = this.#analyzeRecipePatterns();
+      analysisContext.recipes = recipeInsights.summary;
+      suggestions.push(...recipeInsights.suggestions.filter(
+        s => !existingSkills.has(s.name),
+      ));
+    } catch { /* silent */ }
+
+    // ── 维度 4: 候选积压 ──
+    try {
+      const candidateInsights = this.#analyzeCandidatePatterns();
+      analysisContext.candidates = candidateInsights.summary;
+      suggestions.push(...candidateInsights.suggestions.filter(
+        s => !existingSkills.has(s.name),
+      ));
+    } catch { /* silent */ }
+
+    // 按优先级排序：high > medium > low
+    const priorityOrder = { high: 0, medium: 1, low: 2 };
+    suggestions.sort((a, b) => (priorityOrder[a.priority] || 2) - (priorityOrder[b.priority] || 2));
+
+    return {
+      suggestions,
+      existingProjectSkills: [...existingSkills],
+      analysisContext,
+      hint: suggestions.length > 0
+        ? `发现 ${suggestions.length} 个 Skill 创建建议。你可以使用 autosnippet_create_skill 工具直接创建，也可以根据 rationale 自行判断是否需要。`
+        : '当前项目使用模式暂无明确的 Skill 创建建议。继续使用后会积累更多信号。',
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════
+  //  维度 1: Guard 违规模式分析
+  // ═══════════════════════════════════════════════════════
+
+  #analyzeGuardPatterns() {
+    const suggestions = [];
+    if (!this.#db) return { summary: 'DB 不可用', suggestions };
+
+    try {
+      // 查询 Guard 违规记录（audit_logs 中 action LIKE 'guard%' + result='violation'）
+      const rows = this.#db.prepare(`
+        SELECT json_extract(operation_data, '$.ruleName') as ruleName,
+               COUNT(*) as cnt
+        FROM audit_logs
+        WHERE action LIKE 'guard%'
+          AND result = 'violation'
+        GROUP BY ruleName
+        HAVING cnt >= 3
+        ORDER BY cnt DESC
+        LIMIT 5
+      `).all();
+
+      if (rows.length > 0) {
+        const topRule = rows[0];
+        suggestions.push({
+          name: `project-guard-${_kebab(topRule.ruleName || 'common')}`,
+          description: `项目编码规范 — 基于高频 Guard 违规「${topRule.ruleName}」（${topRule.cnt} 次）自动推荐`,
+          rationale: `Guard 规则「${topRule.ruleName}」被违反 ${topRule.cnt} 次，说明团队可能不了解此规范。创建 Skill 可以让 AI 在编码时主动提醒，并提供正确写法参考。`,
+          source: 'guard_violations',
+          priority: topRule.cnt >= 10 ? 'high' : 'medium',
+          signals: { ruleName: topRule.ruleName, violationCount: topRule.cnt, allRules: rows },
+        });
+      }
+
+      return {
+        summary: { violationRules: rows.length, topViolations: rows.slice(0, 3) },
+        suggestions,
+      };
+    } catch {
+      return { summary: 'Guard audit_log 查询失败', suggestions };
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════
+  //  维度 2: Memory 偏好分析
+  // ═══════════════════════════════════════════════════════
+
+  #analyzeMemoryPatterns() {
+    const suggestions = [];
+    const memoryPath = path.join(this.#projectRoot, '.autosnippet', 'memory.jsonl');
+
+    if (!fs.existsSync(memoryPath)) {
+      return { summary: '无 Memory 记录', suggestions };
+    }
+
+    try {
+      const raw = fs.readFileSync(memoryPath, 'utf-8').trim();
+      if (!raw) return { summary: '无 Memory 记录', suggestions };
+
+      const entries = raw.split('\n')
+        .map(l => { try { return JSON.parse(l); } catch { return null; } })
+        .filter(Boolean);
+
+      const preferences = entries.filter(e => e.type === 'preference');
+
+      if (preferences.length >= 5) {
+        // 有足够多的偏好积累 → 建议归纳为 Skill
+        const sample = preferences.slice(-5).map(p => p.content).join('\n- ');
+        suggestions.push({
+          name: 'project-conventions',
+          description: `项目约定总结 — 基于 ${preferences.length} 条团队偏好自动推荐`,
+          rationale: `Memory 中已积累 ${preferences.length} 条用户偏好（如"我们不用…"、"以后都…"），建议归纳为一个 Skill 文档，让 AI 在每次对话中都能参考：\n- ${sample}`,
+          source: 'memory_preferences',
+          priority: preferences.length >= 10 ? 'high' : 'medium',
+          signals: { totalPreferences: preferences.length, recentSamples: preferences.slice(-5) },
+        });
+      }
+
+      return {
+        summary: { totalEntries: entries.length, preferences: preferences.length },
+        suggestions,
+      };
+    } catch {
+      return { summary: 'Memory 读取失败', suggestions };
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════
+  //  维度 3: Recipe 分布与使用热度
+  // ═══════════════════════════════════════════════════════
+
+  #analyzeRecipePatterns() {
+    const suggestions = [];
+    if (!this.#db) return { summary: 'DB 不可用', suggestions };
+
+    try {
+      // 按 category 分布
+      const categories = this.#db.prepare(`
+        SELECT category, COUNT(*) as cnt
+        FROM recipes
+        WHERE category IS NOT NULL AND category != ''
+        GROUP BY category
+        ORDER BY cnt DESC
+      `).all();
+
+      // 按 language 分布
+      const languages = this.#db.prepare(`
+        SELECT language, COUNT(*) as cnt
+        FROM recipes
+        WHERE language IS NOT NULL AND language != ''
+        GROUP BY language
+        ORDER BY cnt DESC
+      `).all();
+
+      // 高频使用但无自定义 Skill 的 category
+      const topCategory = categories[0];
+      if (topCategory && topCategory.cnt >= 10) {
+        const catName = topCategory.category.toLowerCase();
+        suggestions.push({
+          name: `project-${_kebab(catName)}-patterns`,
+          description: `${topCategory.category} 模式汇总 — 该类 Recipe 数量最多（${topCategory.cnt} 条），建议创建专属开发指南`,
+          rationale: `项目中 ${topCategory.category} 类 Recipe 高达 ${topCategory.cnt} 条，占比最大。创建一个 Skill 汇总此类别的核心设计模式、常见用法和注意事项，让 AI 在处理相关代码时有更精准的参考。`,
+          source: 'recipe_distribution',
+          priority: 'low',
+          signals: { category: topCategory.category, recipeCount: topCategory.cnt, allCategories: categories },
+        });
+      }
+
+      // 高使用量 Recipe 统计（adoption_count + application_count >= 5）
+      let hotRecipes = [];
+      try {
+        hotRecipes = this.#db.prepare(`
+          SELECT title, category,
+                 (adoption_count + application_count) as total_usage
+          FROM recipes
+          WHERE (adoption_count + application_count) >= 5
+          ORDER BY total_usage DESC
+          LIMIT 10
+        `).all();
+      } catch { /* 查询失败时降级为空 */ }
+
+      return {
+        summary: { categories: categories.length, languages, hotRecipeCount: hotRecipes.length },
+        suggestions,
+      };
+    } catch {
+      return { summary: 'Recipe 查询失败', suggestions };
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════
+  //  维度 4: 候选积压分析
+  // ═══════════════════════════════════════════════════════
+
+  #analyzeCandidatePatterns() {
+    const suggestions = [];
+    if (!this.#db) return { summary: 'DB 不可用', suggestions };
+
+    try {
+      const stats = this.#db.prepare(`
+        SELECT
+          COUNT(*) as total,
+          SUM(CASE WHEN status='pending' THEN 1 ELSE 0 END) as pending,
+          SUM(CASE WHEN status='rejected' THEN 1 ELSE 0 END) as rejected
+        FROM candidates
+      `).get();
+
+      // 大量被拒绝 → 提示候选质量 Skill
+      if (stats && stats.rejected >= 10) {
+        suggestions.push({
+          name: 'project-candidate-quality',
+          description: `候选提交质量指南 — ${stats.rejected} 条候选被拒，建议创建提交标准 Skill`,
+          rationale: `已有 ${stats.rejected} 条候选被驳回（总计 ${stats.total} 条）。创建一个 Skill 明确项目的候选提交标准（哪些代码值得提取、必填字段要求、质量标杆），可以减少返工。`,
+          source: 'candidate_rejection',
+          priority: stats.rejected >= 20 ? 'high' : 'medium',
+          signals: { total: stats.total, pending: stats.pending, rejected: stats.rejected },
+        });
+      }
+
+      return {
+        summary: stats || {},
+        suggestions,
+      };
+    } catch {
+      return { summary: '候选查询失败', suggestions };
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════
+  //  辅助方法
+  // ═══════════════════════════════════════════════════════
+
+  /**
+   * 列出已有的项目级 Skill 名称集合（避免重复推荐）
+   */
+  #listExistingProjectSkills() {
+    const names = new Set();
+    const dir = getProjectSkillsPath(this.#projectRoot);
+    try {
+      fs.readdirSync(dir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .forEach(d => names.add(d.name));
+    } catch { /* no project skills */ }
+    return names;
+  }
+}
+
+/**
+ * 字符串转 kebab-case（简化版）
+ */
+function _kebab(str) {
+  return (str || 'unknown')
+    .replace(/[^a-zA-Z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .toLowerCase()
+    .substring(0, 30);
+}
+
+export default SkillAdvisor;

package/lib/service/skills/SkillHooks.js

@@ -10,18 +10,26 @@
  *   - onGuardCheck(violation, ctx) → violation (可修改)
  *   - onBootstrapComplete(stats, ctx) → void
  *
- * 加载顺序: 内置 skills/ → 项目级 .autosnippet/skills/（同名覆盖）
+ * 加载顺序: 内置 skills/ → 项目级 AutoSnippet/skills/（同名覆盖）
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Logger from '../../infrastructure/logging/Logger.js';
+import { getProjectSkillsPath } from '../../infrastructure/config/Paths.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PROJECT_ROOT = path.resolve(__dirname, '../../..');
-const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
-const PROJECT_SKILLS_DIR = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
+const SKILLS_DIR = path.resolve(__dirname, '../../../skills');
+
+/**
+ * 获取项目级 Skills 目录（运行时动态解析）
+ * 路径: {projectRoot}/AutoSnippet/skills/
+ */
+function _getProjectSkillsDir() {
+  const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
+  return getProjectSkillsPath(projectRoot);
+}
 
 const HOOK_NAMES = [
   'onCandidateSubmit',
@@ -48,7 +56,7 @@ export class SkillHooks {
     await this.#loadFromDir(SKILLS_DIR, loaded);
 
     // 2. 项目级 skills（覆盖同名）
-    await this.#loadFromDir(PROJECT_SKILLS_DIR, loaded);
+    await this.#loadFromDir(_getProjectSkillsDir(), loaded);
 
     // 3. 注册所有钩子
     for (const [skillName, mod] of loaded) {

package/lib/service/spm/SpmService.js

@@ -650,7 +650,7 @@ export class SpmService {
     const CODE_EXTS = isDirectoryTarget
       ? new Set(['.swift', '.m', '.mm', '.h', '.c', '.cpp', '.js', '.ts', '.tsx', '.jsx', '.py', '.java', '.kt', '.go', '.rs', '.rb', '.vue', '.mjs', '.cjs'])
       : new Set(['.swift', '.m', '.h', '.c', '.cpp', '.mm']);
-    const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
+    const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', 'Carthage', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
     const MAX_FILES = 300;
 
     const files = [];
@@ -889,7 +889,7 @@ export class SpmService {
       // 非 SPM 项目：直接扫描常见源码目录（fallback）
       this.#logger.info('[SpmService] scanProject: No SPM targets, falling back to directory scan');
       const CODE_EXTS = new Set(['.swift', '.m', '.mm', '.h', '.js', '.ts', '.tsx', '.jsx', '.py', '.java', '.kt', '.go', '.rs', '.rb', '.vue', '.mjs', '.cjs']);
-      const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
+      const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'Pods', 'Carthage', '.build', 'DerivedData', 'vendor', '__pycache__', '.venv', 'target']);
       const srcDirs = ['Sources', 'src', 'lib', 'app', 'pages', 'components', 'modules', 'packages'];
 
       const walkDir = (dir, targetName) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "AutoSnippet - 连接开发者、AI 与项目知识库的工具",
   "type": "module",
   "main": "lib/bootstrap.js",

package/templates/copilot-instructions.md

@@ -9,6 +9,7 @@
 ## 知识库与结构
 - 知识库根目录：`AutoSnippet/`（用户项目可通过 boxspec `knowledgeBase.dir` 自定义）
 - Recipe：`AutoSnippet/recipes/*.md`（Markdown + Frontmatter + Snippet + Usage Guide）
+- **Project Skills**：`AutoSnippet/skills/<name>/SKILL.md`（项目级 AI 知识增强文档，跟随 Git）
 - constitution.yaml：`AutoSnippet/constitution.yaml`（权限宪法：角色 + 能力 + 治理规则）
 - 运行时 DB：`.autosnippet/autosnippet.db`（SQLite，recipes/candidates/snippets 索引缓存）
 - 向量索引：`.autosnippet/context/`（`asd embed` 生成）
@@ -51,14 +52,21 @@
 - `autosnippet_submit_draft_recipes` — 解析草稿 Markdown 文件
 - `autosnippet_enrich_candidates` — AI 补全缺失语义字段
 
-### 项目扫描
+### 项目扫描 & 冷启动
 - `autosnippet_get_targets` / `autosnippet_get_target_files` / `autosnippet_get_target_metadata`
 - `autosnippet_scan_project` — 轻量探查（文件清单 + Guard 审计）
-- `autosnippet_bootstrap_knowledge` — 冷启动知识库初始化（9 大知识维度）
+- `autosnippet_bootstrap_knowledge` — 冷启动知识库初始化（9 维度 + 自动生成 Project Skills）
+- `autosnippet_bootstrap_refine` — Bootstrap 候选 AI 润色（summary/insight/relations）
 
 ### Guard & 治理
 - `autosnippet_guard_check` / `autosnippet_guard_audit_files` / `autosnippet_compliance_report`
 
+### Skills
+- `autosnippet_list_skills` — 列出所有可用 Skills（内置 + 项目级）
+- `autosnippet_load_skill` — 加载 Skill 完整文档
+- `autosnippet_create_skill` — 创建项目级 Skill（写入 `AutoSnippet/skills/`）
+- `autosnippet_suggest_skills` — 基于使用模式推荐创建 Skill
+
 ### 其它
 - `autosnippet_health` / `autosnippet_capabilities` / `autosnippet_confirm_usage`
 
@@ -67,10 +75,19 @@
 - Frontmatter 必填字段（7）：`title`、`trigger`（@开头）、`category`（8 选 1）、`language`、`summary_cn`、`summary_en`、`headers`。
 - Usage Guide 必须用 `###` 三级标题分段，列表式书写，禁止一行文字墙。
 
+## Project Skills
+- **发现**：`autosnippet_list_skills` — 列出所有可用 Skills（内置 + 项目级）
+- **加载**：`autosnippet_load_skill(skillName)` — 获取 Skill 完整操作指南
+- **创建**：`autosnippet_create_skill(name, description, content)` — 创建项目级 Skill
+- **推荐**：`autosnippet_suggest_skills` — 基于使用模式推荐创建 Skill
+- **Bootstrap 自动生成**：冷启动 Phase 5.5 自动生成 4 个 Project Skills（code-standard, architecture, project-profile, agent-guidelines）
+- **优先级**：项目级 Skill 同名覆盖内置；宏观知识查 Skill，微观代码模式查 Recipe
+
 ## 推荐工作流
 - **查找**：`autosnippet_search`（推荐）或 `autosnippet_context_search`（上下文感知）。
 - **产出候选**：`autosnippet_validate_candidate` 预校验 → `autosnippet_submit_candidate` 提交。
-- **批量扫描**：`autosnippet_bootstrap_knowledge`（冷启动）→ 按 analysisFramework 逐维度分析 → `autosnippet_submit_candidates`。
+- **冷启动**：`autosnippet_bootstrap_knowledge` → `autosnippet_enrich_candidates` → `autosnippet_bootstrap_refine` → 逐 Target 深入 → `autosnippet_submit_candidates`。
+- **Skills 创建**：`autosnippet_suggest_skills` 分析 → `autosnippet_create_skill` 固化知识。
 - **采纳反馈**：`autosnippet_confirm_usage`（记录使用量影响排序权重）。
 
 ## 与 Cursor 规则联动

package/templates/cursor-rules/autosnippet-conventions.mdc

@@ -41,9 +41,19 @@ Recipes are classified into three kinds:
 - **Retry policy**: If an MCP call fails, do not retry within the same agent turn; fall back to static docs or already-read context.
 - **Adoption tracking**: Tool `autosnippet_confirm_usage` records that a Recipe was adopted or applied (affects usage stats and authority ranking). Show it when the user explicitly adopts a recipe, not immediately after presenting one.
 - **Batch scan**: Ask Cursor in natural language (e.g. "scan all targets in this project", "batch extract candidates") to trigger the batch-scan workflow. The workflow calls `autosnippet_get_targets` → `autosnippet_get_target_files` → extract per file → `autosnippet_submit_candidates` automatically.
-- **Cold start**: Use `autosnippet_bootstrap_knowledge` for full project knowledge initialization covering 9 dimensions (project norms, usage patterns, architecture, code patterns, best practices, bug fixes, knowledge graph, library characteristics, agent dev notes).
+- **Cold start**: Use `autosnippet_bootstrap_knowledge` for full project knowledge initialization covering 9 dimensions. Phase 5.5 auto-generates 4 Project Skills (code-standard, architecture, project-profile, agent-guidelines) to `AutoSnippet/skills/`.
 
-## MCP tools (31 total)
+## Project Skills
+
+- **Skills 目录**: `AutoSnippet/skills/<name>/SKILL.md` — 跟随项目 Git 管理
+- **发现**: `autosnippet_list_skills` — 列出所有可用 Skills（内置 + 项目级）
+- **加载**: `autosnippet_load_skill(skillName)` — 获取 Skill 完整文档
+- **创建**: `autosnippet_create_skill(name, description, content)` — 创建项目级 Skill
+- **推荐**: `autosnippet_suggest_skills` — 基于使用模式推荐创建 Skill
+- **优先级**: 项目级 Skill 同名覆盖内置 Skill；Skill > Recipe（宏观知识优先查 Skill）
+- **Bootstrap 自动生成**: 冷启动会自动生成 `project-code-standard`、`project-architecture`、`project-profile`、`project-agent-guidelines` 四个 Project Skills
+
+## MCP tools (36 total)
 
 ### Search (prefer search / context_search)
 - `autosnippet_search` — Unified search (auto: BM25 + semantic fusion)
@@ -66,14 +76,21 @@ Recipes are classified into three kinds:
 - `autosnippet_submit_draft_recipes` — Parse draft Markdown files
 - `autosnippet_enrich_candidates` — AI-fill missing semantic fields
 
-### Project scanning
+### Project scanning & bootstrap
 - `autosnippet_get_targets` / `autosnippet_get_target_files` / `autosnippet_get_target_metadata`
 - `autosnippet_scan_project` — Lightweight probe (file list + Guard audit)
-- `autosnippet_bootstrap_knowledge` — Cold-start knowledge initialization
+- `autosnippet_bootstrap_knowledge` — Cold-start knowledge initialization (9 dimensions + auto Project Skills)
+- `autosnippet_bootstrap_refine` — AI refinement for bootstrap candidates (summary/insight/relations)
 
 ### Guard & governance
 - `autosnippet_guard_check` / `autosnippet_guard_audit_files` / `autosnippet_compliance_report`
 
+### Skills
+- `autosnippet_list_skills` — List all available Skills (builtin + project)
+- `autosnippet_load_skill` — Load a Skill's full document
+- `autosnippet_create_skill` — Create a project-level Skill in `AutoSnippet/skills/`
+- `autosnippet_suggest_skills` — Recommend Skills based on usage patterns
+
 ### Other
 - `autosnippet_health` / `autosnippet_capabilities` / `autosnippet_confirm_usage`
 

package/templates/cursor-rules/autosnippet-skills.mdc

@@ -0,0 +1,45 @@
+---
+description: AutoSnippet Project Skills — 项目级知识增强文档索引与使用指引
+alwaysApply: true
+---
+
+# AutoSnippet Project Skills
+
+Project Skills 是针对当前项目自动生成或手动创建的 AI Agent 知识增强文档。
+它们存放在 `AutoSnippet/skills/` 目录下，跟随项目 Git 管理。
+
+## 如何发现与加载
+
+1. **列出所有 Skills**：调用 `autosnippet_list_skills` 查看当前可用的 Skills（含内置 + 项目级）
+2. **加载完整内容**：调用 `autosnippet_load_skill(skillName)` 获取具体 Skill 的完整文档
+3. **按需加载**：不确定该用哪个 Skill 时，先加载 `autosnippet-intent` 做意图路由
+4. **创建 Skill**：调用 `autosnippet_create_skill(name, description, content)` 创建项目级 Skill
+5. **Skill 推荐**：调用 `autosnippet_suggest_skills` 获取基于使用模式的 Skill 创建建议
+
+## Bootstrap 自动生成的 Project Skills
+
+冷启动（`autosnippet_bootstrap_knowledge`）Phase 5.5 会自动为 4 个宏观维度生成 Project Skills：
+
+| Skill | 维度 | 说明 |
+|-------|------|------|
+| `project-code-standard` | 代码规范 | 命名约定、文件组织规范 |
+| `project-architecture` | 架构模式 | 分层架构、模块边界、依赖图 |
+| `project-profile` | 项目特征 | 技术栈、模块结构、代码指标 |
+| `project-agent-guidelines` | Agent 约束 | 强制规则、TODO/FIXME、WARNING |
+
+生成后的 Skill 文件位于 `AutoSnippet/skills/<name>/SKILL.md`，自动跟随 Git。
+调用 `autosnippet_load_skill` 可加载完整内容。
+
+## 推荐工作流
+
+冷启动完整流程：
+1. `autosnippet_bootstrap_knowledge` — 9 维度分析 + 自动生成 Project Skills
+2. `autosnippet_enrich_candidates` — 补全缺失语义字段
+3. `autosnippet_bootstrap_refine` — AI 润色 summary/insight/relations
+4. 逐 Target 深入分析 → `autosnippet_submit_candidates`
+
+## 使用优先级
+
+- **Project Skills > 内置 Skills**：同名时项目级覆盖内置
+- **Skill > Recipe**：宏观架构/规范知识优先查 Skill，微观代码模式查 Recipe
+- **Skills 是只读参考**：不要直接修改 SKILL.md，应通过 `autosnippet_create_skill` 工具创建或更新